Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

30.5 KB
Raw Blame
/**
 * Command execution: validates args, manages browser sessions, runs commands.
 *
 * This is the single entry point for executing any CLI command. It handles:
 * 1. Argument validation and coercion
 * 2. Browser session lifecycle (if needed)
 * 3. Domain pre-navigation for cookie strategies
 * 4. Timeout enforcement
 * 5. Lazy-loading of TS modules from manifest
 * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
 */

import {
  type BrowserCliCommand,
  type CliCommand,
  type InternalCliCommand,
  type SiteSessionMode,
  type Arg,
  type CommandArgs,
  getRegistry,
  fullName,
} from './registry.js';
import type { IPage } from './types.js';
import { pathToFileURL } from 'node:url';
import * as crypto from 'node:crypto';
import * as fs from 'node:fs';
import * as os from 'node:os';
import { executePipeline } from './pipeline/index.js';
import { adapterLoadError, ArgumentError, CommandExecutionError, SessionBusyError, attachTraceReceipt, getErrorMessage } from './errors.js';
import { shouldUseBrowserSession } from './capabilityRouting.js';
import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT, type BrowserWindowMode } from './runtime.js';
import { profileRouteParams, resolveProfileSelection } from './browser/profile.js';
import { SLOT_WAIT_DEFAULT_MS, MAX_SLOT_DELAY_MS, parseSlotPolicy, type SlotPolicy } from './site-slots.js';
import { acquireSiteSlot, clearDaemonRunContext, generateRunId, isUnknownOutcomeError, releaseSiteSessionLease, setDaemonCommandTimeoutSeconds, setDaemonRunContext } from './browser/daemon-client.js';
import { emitHook, type HookContext } from './hooks.js';
import { log } from './logger.js';
import { ObservationSession, exportObservationSession, type ObservationExportResult, type ObservationExportStatus } from './observation/index.js';
import { resolveAdapterSourcePath } from './adapter-source.js';

const _loadedModules = new Map<string, Promise<void>>();
/** Track mtime of loaded user adapter files for hot-reload in daemon mode. */
const _moduleMtimes = new Map<string, number>();
const _userClisDir = `${os.homedir()}/.opencli/clis/`;

type TraceMode = 'off' | 'on' | 'retain-on-failure';

function normalizeTraceMode(raw: unknown): TraceMode {
  if (raw === undefined || raw === null || raw === '' || raw === 'off') return 'off';
  if (raw === 'on' || raw === 'retain-on-failure') return raw;
  throw new ArgumentError(`--trace must be one of: off, on, retain-on-failure. Received: "${String(raw)}"`);
}

export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs {
  const result: CommandArgs = { ...kwargs };

  for (const argDef of cmdArgs) {
    const val = result[argDef.name];

    if (argDef.required && (val === undefined || val === null || val === '')) {
      throw new ArgumentError(
        `Argument "${argDef.name}" is required.`,
        argDef.help ?? `Provide a value for --${argDef.name}`,
      );
    }

    if (val !== undefined && val !== null) {
      if (argDef.type === 'int' || argDef.type === 'number') {
        const num = Number(val);
        if (!Number.isFinite(num)) {
          throw new ArgumentError(`Argument "${argDef.name}" must be a valid number. Received: "${val}"`);
        }
        if (argDef.type === 'int' && !Number.isInteger(num)) {
          throw new ArgumentError(`Argument "${argDef.name}" must be a valid integer. Received: "${val}"`);
        }
        result[argDef.name] = num;
      } else if (argDef.type === 'boolean' || argDef.type === 'bool') {
        if (typeof val === 'string') {
          const lower = val.toLowerCase();
          if (lower === 'true' || lower === '1') result[argDef.name] = true;
          else if (lower === 'false' || lower === '0') result[argDef.name] = false;
          else throw new ArgumentError(`Argument "${argDef.name}" must be a boolean (true/false). Received: "${val}"`);
        } else {
          result[argDef.name] = Boolean(val);
        }
      }

      const coercedVal = result[argDef.name];
      if (argDef.choices && argDef.choices.length > 0) {
        if (!argDef.choices.map(String).includes(String(coercedVal))) {
          throw new ArgumentError(`Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"`);
        }
      }
    } else if (argDef.default !== undefined) {
      result[argDef.name] = argDef.default;
    }
  }
  return result;
}

async function runCommand(
  cmd: CliCommand,
  page: IPage | null,
  kwargs: CommandArgs,
  debug: boolean,
): Promise<unknown> {
  const internal = cmd as InternalCliCommand;
  if (internal._lazy && internal._modulePath) {
    const modulePath = internal._modulePath;
    // Hot-reload: if a user adapter's file has changed on disk, invalidate cache
    const isUserAdapter = modulePath.startsWith(_userClisDir);
    if (isUserAdapter && _loadedModules.has(modulePath)) {
      try {
        const stat = fs.statSync(modulePath);
        const prevMtime = _moduleMtimes.get(modulePath);
        if (prevMtime !== undefined && stat.mtimeMs !== prevMtime) {
          _loadedModules.delete(modulePath);
          _moduleMtimes.delete(modulePath);
        }
      } catch { /* file may have been deleted; let import below handle it */ }
    }
    if (!_loadedModules.has(modulePath)) {
      const url = pathToFileURL(modulePath).href;
      const importUrl = _moduleMtimes.has(modulePath) ? `${url}?t=${Date.now()}` : url;
      const loadPromise = import(importUrl).then(
        () => {
          try { _moduleMtimes.set(modulePath, fs.statSync(modulePath).mtimeMs); } catch {}
        },
        (err) => {
          _loadedModules.delete(modulePath);
          throw adapterLoadError(
            `Failed to load adapter module ${modulePath}: ${getErrorMessage(err)}`,
            'Check that the adapter file exists and has no syntax errors.',
          );
        },
      );
      _loadedModules.set(modulePath, loadPromise);
    }
    await _loadedModules.get(modulePath);

    const updated = getRegistry().get(fullName(cmd));
    if (updated?.func) {
      return runCommandFunc(updated, page, kwargs, debug);
    }
    if (updated?.pipeline) return executePipeline(page, updated.pipeline, { args: kwargs, debug });
  }

  if (cmd.func) return runCommandFunc(cmd, page, kwargs, debug);
  if (cmd.pipeline) return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
  throw new CommandExecutionError(
    `Command ${fullName(cmd)} has no func or pipeline`,
    'This is likely a bug in the adapter definition. Please report this issue.',
  );
}

function runCommandFunc(cmd: CliCommand, page: IPage | null, kwargs: CommandArgs, debug: boolean): Promise<unknown> {
  if (cmd.browser === false) return cmd.func!(kwargs, debug);
  if (!page) {
    throw new CommandExecutionError(`Command ${fullName(cmd)} requires a browser session but none was provided`);
  }
  return (cmd as BrowserCliCommand).func!(page, kwargs, debug);
}

function resolvePreNav(cmd: CliCommand): string | null {
  if (cmd.navigateBefore === false) return null;
  if (typeof cmd.navigateBefore === 'string') return cmd.navigateBefore;
  // strategy → navigateBefore expansion already happened in normalizeCommand().
  return null;
}

function urlMatchesDomain(url: string | null | undefined, domain: string | undefined): boolean {
  if (!url || !domain) return false;
  try {
    const hostname = new URL(url).hostname;
    return hostname === domain || hostname.endsWith(`.${domain}`);
  } catch {
    return false;
  }
}

function isDomainRootPreNav(preNavUrl: string, domain: string | undefined): boolean {
  if (!domain) return false;
  try {
    const parsed = new URL(preNavUrl);
    const hostnameMatches = parsed.hostname === domain || parsed.hostname.endsWith(`.${domain}`);
    const rootPath = parsed.pathname === '' || parsed.pathname === '/';
    return hostnameMatches && rootPath && parsed.search === '' && parsed.hash === '';
  } catch {
    return false;
  }
}

async function shouldRunPreNav(cmd: CliCommand, page: IPage, siteSession: SiteSessionMode, preNavUrl: string): Promise<boolean> {
  if (siteSession !== 'persistent' || !cmd.domain) return true;
  if (!isDomainRootPreNav(preNavUrl, cmd.domain)) return true;
  const currentUrl = await page.getCurrentUrl?.().catch(() => null);
  return !urlMatchesDomain(currentUrl, cmd.domain);
}

export async function executeCommand(
  cmd: CliCommand,
  rawKwargs: CommandArgs,
  debug: boolean = false,
  opts: {
    prepared?: boolean;
    profile?: string;
    trace?: string;
    keepTab?: string;
    windowMode?: string;
    siteSession?: string;
    onTraceExport?: (trace: ObservationExportResult) => void;
  } = {},
): Promise<unknown> {
  // Resolve browser-only configuration before argument hooks or any browser
  // lifecycle setup. Non-browser commands must not be affected by browser
  // environment defaults, even when those defaults are invalid.
  const resolvedSiteSession = shouldUseBrowserSession(cmd)
    ? resolveSiteSession(cmd, opts.siteSession)
    : null;
  // A pooled site (OPENCLI_SITE_SLOTS) runs on persistent slot sessions unless
  // this invocation explicitly asks for a one-shot tab with --site-session.
  const slotPolicy = resolvedSiteSession !== null && opts.siteSession !== 'ephemeral'
    ? resolveSiteSlotPolicy(cmd.site)
    : null;
  if (slotPolicy && process.env.OPENCLI_CDP_ENDPOINT) {
    throw new ArgumentError('OPENCLI_SITE_SLOTS requires Browser Bridge; use --site-session ephemeral with a direct CDP endpoint.');
  }
  const siteSession = slotPolicy ? 'persistent' : resolvedSiteSession;

  let kwargs: CommandArgs;
  try {
    kwargs = opts.prepared ? rawKwargs : prepareCommandArgs(cmd, rawKwargs);
  } catch (err) {
    if (err instanceof ArgumentError) throw err;
    throw new ArgumentError(getErrorMessage(err));
  }

  const userTimeoutSec = readUserTimeoutSeconds(cmd, kwargs);
  // Propagate --timeout to the daemon transport so its per-command deadline
  // (and the derived extension/HTTP deadlines) honor the user's value instead
  // of the default. Set unconditionally so a previous command's value never
  // leaks into this one.
  setDaemonCommandTimeoutSeconds(userTimeoutSec);
  const traceMode = normalizeTraceMode(opts.trace);

  const hookCtx: HookContext = {
    command: fullName(cmd),
    args: kwargs,
    startedAt: Date.now(),
  };
  await emitHook('onBeforeExecute', hookCtx);

  let result: unknown;
  try {
    if (siteSession !== null) {
      const BrowserFactory = getBrowserFactory();
      // Requirement vs preference: --profile / OPENCLI_PROFILE route strictly;
      // the config default is a soft preference the daemon arbitrates.
      const profileSelection = resolveProfileSelection(opts.profile);
      const profileRouting = profileRouteParams(profileSelection);
      const contextId = profileSelection?.contextId;
      const internal = cmd as InternalCliCommand;
      let session = resolveAdapterBrowserSession(cmd, siteSession);
      const keepTab = resolveKeepTab(siteSession, opts.keepTab);
      const windowMode = resolveBrowserWindowMode(cmd.defaultWindowMode ?? 'background', opts.windowMode);
      // Persistent-session write commands take a logical lease on the site
      // session so a concurrent retry fails fast instead of driving the same
      // Chrome tab. The runId flows to the daemon on every command (acquire +
      // heartbeat); we release it explicitly when the command settles. Read and
      // ephemeral commands are never leased.
      let leaseRun = siteSession === 'persistent' && cmd.access === 'write'
        ? { runId: generateRunId(), session }
        : null;
      let slotWaitedSec = 0;
      if (slotPolicy) {
        // A pooled site borrows one slot (= one persistent session = one warm
        // tab) for the whole run, reads included. Every exec carries the
        // runId so the daemon keeps the slot alive; the finally below returns it.
        const runId = leaseRun?.runId ?? generateRunId();
        setDaemonRunContext({ runId, command: fullName(cmd), access: cmd.access });
        try {
          // A user --timeout budgets queue wait + run together; without one the
          // queue has its own default and the run keeps its usual ceiling.
          const waitMs = userTimeoutSec !== null ? Math.min(MAX_SLOT_DELAY_MS, userTimeoutSec * 1000) : SLOT_WAIT_DEFAULT_MS;
          const slotStartedAt = Date.now();
          const grant = await acquireSiteSlot({ site: cmd.site, ...slotPolicy, waitMs, ...profileRouting });
          session = grant.session;
          slotWaitedSec = Math.max(grant.waitedMs / 1000, (Date.now() - slotStartedAt) / 1000);
        } catch (err) {
          setDaemonRunContext(null);
          throw err;
        }
        leaseRun = { runId, session };
      } else if (leaseRun) {
        setDaemonRunContext({ runId: leaseRun.runId, command: fullName(cmd), access: 'write' });
      }
      let browserRunError: unknown;
      // `as` casts defeat literal narrowing: both are assigned only inside the
      // browserSession callback, which TS's flow analysis does not see from the
      // finally block below.
      let adapterStillRunning = false as boolean;
      let adapterRun = null as Promise<unknown> | null;
      try {
      result = await browserSession(BrowserFactory, async (page) => {
        const observation = traceMode === 'off'
          ? null
          : new ObservationSession({
            scope: {
              contextId,
              session,
              target: page.getActivePage?.(),
              site: cmd.site,
              command: fullName(cmd),
              adapterSourcePath: resolveAdapterSourcePath(internal),
            },
          });
        if (observation) {
          observation.record({
            stream: 'action',
            name: 'command',
            phase: 'start',
            data: { args: kwargs },
          });
          await page.startNetworkCapture?.().catch(() => false);
        }
        if (slotPolicy) await activateSlotTab(page);
        const preNavUrl = resolvePreNav(cmd);
        if (preNavUrl && await shouldRunPreNav(cmd, page, siteSession, preNavUrl)) {
          observation?.record({
            stream: 'action',
            name: 'pre_navigate',
            phase: 'start',
            data: { url: preNavUrl },
          });
          // Navigate directly — the extension's handleNavigate already has a fast-path
          // that skips navigation if the tab is already at the target URL.
          // This avoids an extra exec round-trip (getCurrentUrl) on first command.
          try {
            await page.goto(preNavUrl);
            observation?.record({
              stream: 'action',
              name: 'pre_navigate',
              phase: 'end',
              data: { url: preNavUrl },
            });
          } catch (err) {
            // A busy-session rejection is the whole point of the arbitration —
            // surface it verbatim instead of burying it in a pre-nav wrapper.
            if (err instanceof SessionBusyError) throw err;
            observation?.record({
              stream: 'action',
              name: 'pre_navigate',
              phase: 'error',
              data: { url: preNavUrl, error: err instanceof Error ? err.message : String(err) },
            });
            const wrapped = new CommandExecutionError(
              `Pre-navigation to ${preNavUrl} failed: ${err instanceof Error ? err.message : err}`,
              'Check that the site is reachable and the browser extension is running.',
            );
            // Keep the original error reachable: the lease-release decision walks
            // the cause chain, and a pre-nav navigate/exec can itself end with an
            // unknown outcome while still running against the persistent tab.
            wrapped.cause = err;
            if (observation && (traceMode === 'on' || traceMode === 'retain-on-failure')) {
              observation.record({
                stream: 'error',
                message: wrapped.message,
                stack: wrapped.stack,
                code: wrapped.code,
                hint: wrapped.hint,
              });
              await collectObservationEvidence(observation, page).catch(() => {});
              exportTraceArtifact(observation, 'failure', wrapped, opts.onTraceExport);
            }
            throw wrapped;
          }
        }
        const browserTimeout = userTimeoutSec !== null
          ? Math.max(1, userTimeoutSec - slotWaitedSec) + RUNTIME_TIMEOUT_PADDING_SECONDS
          : DEFAULT_BROWSER_COMMAND_TIMEOUT;
        const commandRun = runCommand(cmd, page, kwargs, debug);
        adapterRun = commandRun;
        // runWithTimeout races but never cancels: when the CLI-layer timeout
        // wins, the adapter promise keeps driving the tab from this process.
        // Track settledness so the lease-release decision can tell a finished
        // adapter apart from one still running behind a timeout.
        let commandSettled = false;
        commandRun.then(() => { commandSettled = true; }, () => { commandSettled = true; });
        try {
          const result = await runWithTimeout(commandRun, {
            timeout: browserTimeout,
            label: fullName(cmd),
          });
          observation?.record({
            stream: 'action',
            name: 'command',
            phase: 'end',
          });
          if (observation && traceMode === 'on') {
            await collectObservationEvidence(observation, page).catch(() => {});
            exportTraceArtifact(observation, 'success', undefined, opts.onTraceExport);
          }
          // Adapter commands are one-shot — release the current tab lease immediately
          // instead of waiting for the 30s idle timeout. The automation container
          // window stays open for reuse.
          if (!keepTab) await page.closeWindow?.().catch(() => {});
          return result;
        } catch (err) {
          if (!commandSettled) adapterStillRunning = true;
          if (observation) {
            observation.record({
              stream: 'action',
              name: 'command',
              phase: 'error',
              data: { error: err instanceof Error ? err.message : String(err) },
            });
            observation.record({
              stream: 'error',
              message: err instanceof Error ? err.message : String(err),
              stack: err instanceof Error ? err.stack : undefined,
            });
            if (traceMode === 'on' || traceMode === 'retain-on-failure') {
              await collectObservationEvidence(observation, page).catch(() => {});
              exportTraceArtifact(observation, 'failure', err, opts.onTraceExport);
            }
          }
          // Release the tab lease on failure too — without this, the lease lingers
          // until the extension's idle timer fires (unreliable on Windows where
          // MV3 service workers may be suspended before setTimeout triggers).
          if (!keepTab) await page.closeWindow?.().catch(() => {});
          throw err;
        }
      }, { session, ...profileRouting, windowMode, surface: 'adapter', siteSession });
      } catch (err) {
        browserRunError = err;
        throw err;
      } finally {
        // Clear the run identity whether the command succeeded or failed, then
        // release the lease so a retry succeeds immediately. Best-effort: TTL
        // reclaims it if the release is lost.
        //
        // Exceptions — cases where the session may still be driven, so an
        // immediate explicit release would hand the lease to a challenger that
        // then collides with the stale work (the very collision this lease
        // prevents):
        // - A CLI-layer timeout does not cancel the adapter promise, and the
        //   process only exits when the event loop drains, so the adapter may
        //   keep driving the tab for minutes. Keep the run identity bound: its
        //   follow-up commands heartbeat the lease (challengers stay blocked
        //   past the TTL), and cleanup runs when the adapter finally settles.
        //   If the process dies first, the daemon TTL reclaims the lease.
        // - An unknown-outcome failure (result-unknown / command-lost /
        //   result-evicted, anywhere in the cause chain) means the browser-side
        //   command may STILL be running against the persistent tab; there is
        //   nothing to await client-side, so the TTL is the quiet period.
        if (leaseRun) {
          if (adapterStillRunning && adapterRun) {
            const runId = leaseRun.runId;
            const session = leaseRun.session;
            const settle = (err?: unknown) => {
              clearDaemonRunContext(runId);
              // Same rule as the immediate path below: an unknown-outcome
              // ending means the browser side may still be busy — skip the
              // explicit release and leave the lease to TTL reclamation.
              if (!isUnknownOutcomeError(err)) {
                void releaseSiteSessionLease({ runId, session, surface: 'adapter' });
              }
            };
            adapterRun.then(() => settle(), (err) => settle(err));
          } else {
            setDaemonRunContext(null);
            if (!isUnknownOutcomeError(browserRunError)) {
              await releaseSiteSessionLease({ runId: leaseRun.runId, session: leaseRun.session, surface: 'adapter' });
            }
          }
        }
      }
    } else {
      // Non-browser commands: enforce a timeout only when the command exposes
      // a `--timeout` arg (and the resolved value is positive). Without that
      // arg there is no meaningful default — non-browser cmds are diverse
      // enough that a hard cap would do more harm than good.
      if (userTimeoutSec !== null) {
        const ceiling = userTimeoutSec + RUNTIME_TIMEOUT_PADDING_SECONDS;
        result = await runWithTimeout(runCommand(cmd, null, kwargs, debug), {
          timeout: ceiling,
          label: fullName(cmd),
          hint: `Pass a higher --timeout value (currently ${userTimeoutSec}s)`,
        });
      } else {
        result = await runCommand(cmd, null, kwargs, debug);
      }
    }
  } catch (err) {
    hookCtx.error = err;
    hookCtx.finishedAt = Date.now();
    await emitHook('onAfterExecute', hookCtx);
    throw err;
  }

  hookCtx.finishedAt = Date.now();
  await emitHook('onAfterExecute', hookCtx, result);
  return result;
}

async function collectObservationEvidence(session: ObservationSession, page: IPage): Promise<void> {
  const target = page.getActivePage?.() ?? session.scope.target;
  const [url, snapshot, networkEntries, consoleMessages, screenshot] = await Promise.all([
    page.getCurrentUrl?.().catch(() => null) ?? Promise.resolve(null),
    page.snapshot().catch(() => undefined),
    page.readNetworkCapture?.().catch(() => []) ?? Promise.resolve([]),
    page.consoleMessages('all').catch(() => []),
    page.screenshot({ format: 'png' }).catch(() => undefined),
  ]);

  if (snapshot !== undefined || url !== undefined) {
    session.record({ stream: 'state', url, target, snapshot, label: 'final' });
  }
  for (const entry of Array.isArray(networkEntries) ? networkEntries : []) {
    const record = entry as Record<string, unknown>;
    session.record({
      stream: 'network',
      url: String(record.url ?? ''),
      method: typeof record.method === 'string' ? record.method : undefined,
      status: typeof record.responseStatus === 'number' ? record.responseStatus : undefined,
      contentType: typeof record.responseContentType === 'string' ? record.responseContentType : undefined,
      size: typeof record.responseBodyFullSize === 'number' ? record.responseBodyFullSize : undefined,
      requestHeaders: record.requestHeaders as Record<string, unknown> | undefined,
      responseHeaders: record.responseHeaders as Record<string, unknown> | undefined,
      requestBody: record.requestBodyPreview,
      responseBody: record.responsePreview,
      ts: typeof record.timestamp === 'number' ? record.timestamp : undefined,
    });
  }
  for (const message of Array.isArray(consoleMessages) ? consoleMessages : []) {
    if (message && typeof message === 'object') {
      const record = message as Record<string, unknown>;
      session.record({
        stream: 'console',
        level: String(record.type ?? record.level ?? 'log'),
        text: String(record.text ?? record.message ?? ''),
        ts: typeof record.timestamp === 'number' ? record.timestamp : undefined,
      });
    } else {
      session.record({ stream: 'console', level: 'log', text: String(message) });
    }
  }
  if (typeof screenshot === 'string' && screenshot) {
    session.record({ stream: 'screenshot', format: 'png', data: screenshot, label: 'final' });
  }
}

function exportTraceArtifact(
  session: ObservationSession,
  status: ObservationExportStatus,
  error?: unknown,
  onTraceExport?: (trace: ObservationExportResult) => void,
): ObservationExportResult | undefined {
  try {
    const trace = exportObservationSession(session, { error, status });
    if (status === 'failure' && error !== undefined) {
      attachTraceReceipt(error, trace.receipt);
    } else {
      process.stderr.write(`OpenCLI trace artifact: ${trace.dir}\n`);
    }
    try {
      onTraceExport?.(trace);
    } catch (err) {
      log.warn(`[trace] Trace export callback failed: ${err instanceof Error ? err.message : String(err)}`);
    }
    return trace;
  } catch (err) {
    log.warn(`[trace] Failed to export trace artifact: ${err instanceof Error ? err.message : String(err)}`);
    return undefined;
  }
}

export function prepareCommandArgs(
  cmd: CliCommand,
  rawKwargs: CommandArgs,
): CommandArgs {
  const kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
  cmd.validateArgs?.(kwargs);
  return kwargs;
}

/**
 * Runtime ceiling padding (seconds) added on top of the user's `--timeout`.
 * The adapter's polling loop typically uses the full user value; the padding
 * gives us room for the adapter to return + closeWindow + trace export before
 * the runtime kills the Promise.
 */
const RUNTIME_TIMEOUT_PADDING_SECONDS = 30;

function normalizeSiteSession(name: string, raw: unknown): SiteSessionMode | null {
  if (raw === undefined) return null;
  if (raw === 'ephemeral' || raw === 'persistent') return raw;
  throw new ArgumentError(`${name} must be one of: ephemeral, persistent. Received: "${String(raw)}"`);
}

function resolveSiteSession(cmd: CliCommand, rawOption?: unknown): SiteSessionMode {
  return normalizeSiteSession('--site-session', rawOption)
    ?? normalizeSiteSession('OPENCLI_SITE_SESSION', process.env.OPENCLI_SITE_SESSION)
    ?? cmd.siteSession
    ?? 'ephemeral';
}

/**
 * Every adapter tab shares one automation window, and only a window's active
 * tab renders: a background tab stalls IntersectionObserver/rAF-driven lazy
 * loading. A warm slot tab may have been backgrounded since its last run, so
 * bring it to the front. A session bound to its tab lists exactly that tab;
 * any other shape (no tab yet — the first navigate creates it active — or a
 * window-wide listing) is left alone rather than risk selecting a tab that
 * belongs to another session.
 */
async function activateSlotTab(page: IPage): Promise<void> {
  const tabs = await page.tabs() as Array<{ page?: string; active?: boolean }>;
  if (tabs.length === 1 && tabs[0].page && !tabs[0].active) await page.selectTab(tabs[0].page);
}

/**
 * OPENCLI_SITE_SLOTS="xiaohongshu:1:1500-3000,weibo:2" pools the listed sites:
 * `site:poolSize[:minMs[-maxMs]]`, where the optional interval spaces slot
 * grants (one per command run) by a jittered delay.
 */
function resolveSiteSlotPolicy(site: string): SlotPolicy | null {
  for (const raw of (process.env.OPENCLI_SITE_SLOTS ?? '').split(',')) {
    const entry = raw.trim();
    if (entry !== site && !entry.startsWith(`${site}:`)) continue;
    const match = /^(\d+)(?::(\d+)(?:-(\d+))?)?$/.exec(entry.slice(site.length + 1));
    if (!match || Number(match[1]) < 1) {
      throw new ArgumentError(`OPENCLI_SITE_SLOTS entry "${entry}" must be site:poolSize[:minMs[-maxMs]] with poolSize >= 1.`);
    }
    const minIntervalMs = Number(match[2] ?? 0);
    const maxIntervalMs = Math.max(minIntervalMs, Number(match[3] ?? minIntervalMs));
    const policy = parseSlotPolicy({ poolSize: Number(match[1]), minIntervalMs, maxIntervalMs });
    if (!policy) throw new ArgumentError('OPENCLI_SITE_SLOTS requires poolSize 1–32 and finite intervals no greater than 2147483647 ms.');
    return policy;
  }
  return null;
}

function resolveAdapterBrowserSession(cmd: CliCommand, siteSession: SiteSessionMode): string {
  if (siteSession === 'persistent') return `site:${cmd.site}`;
  return `site:${cmd.site}:${crypto.randomUUID()}`;
}

function normalizeBooleanOption(name: string, raw: unknown): boolean | null {
  if (raw === undefined || raw === '') return null;
  if (raw === 'true') return true;
  if (raw === 'false') return false;
  throw new ArgumentError(`${name} must be one of: true, false. Received: "${String(raw)}"`);
}

function resolveKeepTab(siteSession: SiteSessionMode, rawOption?: unknown): boolean {
  if (siteSession === 'persistent') return true;
  return normalizeBooleanOption('--keep-tab', rawOption) ?? false;
}

function normalizeWindowMode(name: string, raw: unknown): BrowserWindowMode | null {
  if (raw === undefined || raw === '') return null;
  if (raw === 'foreground' || raw === 'background') return raw;
  throw new ArgumentError(`${name} must be one of: foreground, background. Received: "${String(raw)}"`);
}

function resolveBrowserWindowMode(defaultMode: BrowserWindowMode = 'background', rawOption?: unknown): BrowserWindowMode {
  return normalizeWindowMode('--window', rawOption)
    ?? normalizeWindowMode('OPENCLI_WINDOW', process.env.OPENCLI_WINDOW)
    ?? defaultMode;
}

/**
 * Resolve the user-controllable `--timeout` arg, in seconds.
 *
 * Convention: a command opts into runtime-enforced timeouts by declaring an
 * arg named `timeout`. The arg's `default` flows through `prepareCommandArgs`
 * into `kwargs.timeout`, so by the time runtime enforcement runs, the value
 * is the merged user-supplied-or-default seconds.
 *
 * Returns the parsed positive integer (seconds), or null if the command does
 * not expose a `timeout` arg. Declaring `timeout` opts into runtime timeout
 * enforcement, so invalid values must fail upfront instead of silently
 * disabling the runtime ceiling.
 */
function readUserTimeoutSeconds(cmd: CliCommand, kwargs: CommandArgs): number | null {
  if (!cmd.args.some(a => a.name === 'timeout')) return null;
  const raw = kwargs.timeout;
  if (raw === undefined || raw === null || raw === '') {
    throw new ArgumentError(`Argument "timeout" must be a positive integer. Received: "${String(raw)}"`);
  }
  const parsed = Number(raw);
  if (!Number.isInteger(parsed) || parsed <= 0) {
    throw new ArgumentError(`Argument "timeout" must be a positive integer. Received: "${String(raw)}"`);
  }
  return parsed;
}