openclaw/src/cli/program/route-args.ts

// Route-first argv parsers for commands that can skip full Commander startup.
import { isValueToken } from "../../infra/cli-root-options.js";
import {
  getCommandPositionalsWithRootOptions,
  getFlagValue,
  getPositiveIntFlagValue,
  getVerboseFlag,
  hasFlag,
} from "../argv.js";
import { parseStrictPositiveIntOrUndefined } from "./helpers.js";

type OptionalFlagParse = {
  ok: boolean;
  value?: string;
};

function parseOptionalFlagValue(argv: string[], name: string): OptionalFlagParse {
  const value = getFlagValue(argv, name);
  if (value === null) {
    return { ok: false };
  }
  return { ok: true, value };
}

function parseRepeatedFlagValues(argv: string[], name: string): string[] | null {
  const values: string[] = [];
  const args = argv.slice(2);
  for (let i = 0; i < args.length; i += 1) {
    const arg = args[i];
    if (!arg || arg === "--") {
      break;
    }
    if (arg === name) {
      const next = args[i + 1];
      if (next === undefined || !isValueToken(next)) {
        // Invalid fast-path shapes fall back to Commander so its normal errors and help text win.
        return null;
      }
      values.push(next);
      i += 1;
      continue;
    }
    if (arg.startsWith(`${name}=`)) {
      const value = arg.slice(name.length + 1).trim();
      if (!value) {
        return null;
      }
      values.push(value);
    }
  }
  return values;
}

type RoutedCommandArgShape = {
  commandPath: string[];
  booleanFlags?: string[];
  valueFlags?: string[];
};

function getRoutedCommandPositionals(
  argv: string[],
  shape: RoutedCommandArgShape,
): string[] | null {
  if (argv.slice(2).includes("--")) {
    return null;
  }
  return getCommandPositionalsWithRootOptions(argv, shape);
}

function parseSinglePositional(
  argv: string[],
  params: {
    commandPath: string[];
    booleanFlags?: string[];
  },
): string | null {
  const positionals = getRoutedCommandPositionals(argv, params);
  if (!positionals || positionals.length !== 1) {
    return null;
  }
  return positionals[0] ?? null;
}

/** Parse `openclaw health` flags for the route-first status family. */
export function parseHealthRouteArgs(argv: string[]) {
  const positionals = getRoutedCommandPositionals(argv, {
    commandPath: ["health"],
    booleanFlags: ["--json", "--verbose", "--debug"],
    valueFlags: ["--timeout"],
  });
  if (!positionals || positionals.length !== 0) {
    return null;
  }
  const timeoutMs = getPositiveIntFlagValue(argv, "--timeout");
  if (timeoutMs === null) {
    return null;
  }
  return {
    json: hasFlag(argv, "--json"),
    verbose: getVerboseFlag(argv, { includeDebug: true }),
    timeoutMs,
  };
}

/** Parse `openclaw status` flags without registering the full command tree. */
export function parseStatusRouteArgs(argv: string[]) {
  const positionals = getRoutedCommandPositionals(argv, {
    commandPath: ["status"],
    booleanFlags: ["--json", "--deep", "--all", "--usage", "--verbose", "--debug"],
    valueFlags: ["--timeout"],
  });
  if (!positionals || positionals.length !== 0) {
    return null;
  }
  const timeoutMs = getPositiveIntFlagValue(argv, "--timeout");
  if (timeoutMs === null) {
    return null;
  }
  return {
    json: hasFlag(argv, "--json"),
    deep: hasFlag(argv, "--deep"),
    all: hasFlag(argv, "--all"),
    usage: hasFlag(argv, "--usage"),
    verbose: getVerboseFlag(argv, { includeDebug: true }),
    timeoutMs,
  };
}

/** Parse `openclaw gateway status` RPC-only flags accepted by the fast route. */
export function parseGatewayStatusRouteArgs(argv: string[]) {
  const positionals = getRoutedCommandPositionals(argv, {
    commandPath: ["gateway", "status"],
    booleanFlags: ["--deep", "--json", "--require-rpc", "--no-probe", "--ssh-auto"],
    valueFlags: ["--url", "--token", "--password", "--timeout", "--ssh", "--ssh-identity"],
  });
  if (!positionals || positionals.length !== 0) {
    return null;
  }
  const url = parseOptionalFlagValue(argv, "--url");
  if (!url.ok) {
    return null;
  }
  const token = parseOptionalFlagValue(argv, "--token");
  if (!token.ok) {
    return null;
  }
  const password = parseOptionalFlagValue(argv, "--password");
  if (!password.ok) {
    return null;
  }
  const timeout = parseOptionalFlagValue(argv, "--timeout");
  if (!timeout.ok) {
    return null;
  }
  const ssh = parseOptionalFlagValue(argv, "--ssh");
  if (!ssh.ok || ssh.value !== undefined) {
    // SSH probe options need the full command because they resolve host aliases and identity files.
    return null;
  }
  const sshIdentity = parseOptionalFlagValue(argv, "--ssh-identity");
  if (!sshIdentity.ok || sshIdentity.value !== undefined) {
    return null;
  }
  if (hasFlag(argv, "--ssh-auto")) {
    return null;
  }
  return {
    rpc: {
      url: url.value,
      token: token.value,
      password: password.value,
      timeout: timeout.value,
    },
    deep: hasFlag(argv, "--deep"),
    json: hasFlag(argv, "--json"),
    requireRpc: hasFlag(argv, "--require-rpc"),
    probe: !hasFlag(argv, "--no-probe"),
  };
}

/** Parse `openclaw sessions` filters for JSON/list route execution. */
export function parseSessionsRouteArgs(argv: string[]) {
  const positionals = getRoutedCommandPositionals(argv, {
    commandPath: ["sessions"],
    booleanFlags: ["--json", "--all-agents"],
    valueFlags: ["--agent", "--store", "--active", "--limit"],
  });
  if (!positionals || positionals.length !== 0) {
    return null;
  }
  const agent = parseOptionalFlagValue(argv, "--agent");
  if (!agent.ok) {
    return null;
  }
  const store = parseOptionalFlagValue(argv, "--store");
  if (!store.ok) {
    return null;
  }
  const active = parseOptionalFlagValue(argv, "--active");
  if (!active.ok) {
    return null;
  }
  const limit = parseOptionalFlagValue(argv, "--limit");
  if (!limit.ok) {
    return null;
  }
  return {
    json: hasFlag(argv, "--json"),
    allAgents: hasFlag(argv, "--all-agents"),
    agent: agent.value,
    store: store.value,
    active: active.value,
    limit: limit.value,
  };
}

/** Parse `openclaw agents list` display switches for route-first execution. */
export function parseAgentsListRouteArgs(argv: string[]) {
  const listPositionals = getRoutedCommandPositionals(argv, {
    commandPath: ["agents", "list"],
    booleanFlags: ["--json", "--bindings"],
  });
  if (listPositionals && listPositionals.length === 0) {
    return {
      json: hasFlag(argv, "--json"),
      bindings: hasFlag(argv, "--bindings"),
    };
  }
  const aliasPositionals = getRoutedCommandPositionals(argv, {
    commandPath: ["agents"],
    booleanFlags: ["--json", "--bindings"],
  });
  return aliasPositionals?.length === 0
    ? { json: hasFlag(argv, "--json"), bindings: hasFlag(argv, "--bindings") }
    : null;
}

/** Parse `openclaw config get <path>` while preserving root option handling. */
export function parseConfigGetRouteArgs(argv: string[]) {
  const path = parseSinglePositional(argv, {
    commandPath: ["config", "get"],
    booleanFlags: ["--json"],
  });
  if (!path) {
    return null;
  }
  return {
    path,
    json: hasFlag(argv, "--json"),
  };
}

/** Parse `openclaw config unset <path>` and its mutation guard flags. */
export function parseConfigUnsetRouteArgs(argv: string[]) {
  const path = parseSinglePositional(argv, {
    commandPath: ["config", "unset"],
    booleanFlags: ["--dry-run", "--allow-exec", "--json"],
  });
  if (!path) {
    return null;
  }
  return {
    path,
    cliOptions: {
      dryRun: hasFlag(argv, "--dry-run"),
      allowExec: hasFlag(argv, "--allow-exec"),
      json: hasFlag(argv, "--json"),
    },
  };
}

/** Parse `openclaw models list` filters for the lightweight model catalog route. */
export function parseModelsListRouteArgs(argv: string[]) {
  const positionals = getRoutedCommandPositionals(argv, {
    commandPath: ["models", "list"],
    booleanFlags: ["--all", "--local", "--json", "--plain"],
    valueFlags: ["--provider"],
  });
  if (!positionals || positionals.length !== 0) {
    return null;
  }
  const provider = parseOptionalFlagValue(argv, "--provider");
  if (!provider.ok) {
    return null;
  }
  return {
    provider: provider.value,
    all: hasFlag(argv, "--all"),
    local: hasFlag(argv, "--local"),
    json: hasFlag(argv, "--json"),
    plain: hasFlag(argv, "--plain"),
  };
}

/** Parse `openclaw models status` probe controls for the route-first status path. */
export function parseModelsStatusRouteArgs(argv: string[]) {
  const positionals = getRoutedCommandPositionals(argv, {
    commandPath: ["models", "status"],
    booleanFlags: ["--json", "--plain", "--check", "--probe"],
    valueFlags: [
      "--probe-provider",
      "--probe-timeout",
      "--probe-concurrency",
      "--probe-max-tokens",
      "--probe-profile",
      "--agent",
    ],
  });
  if (!positionals || positionals.length !== 0) {
    return null;
  }
  const probeProvider = parseOptionalFlagValue(argv, "--probe-provider");
  if (!probeProvider.ok) {
    return null;
  }
  const probeTimeout = parseOptionalFlagValue(argv, "--probe-timeout");
  if (!probeTimeout.ok) {
    return null;
  }
  const probeConcurrency = parseOptionalFlagValue(argv, "--probe-concurrency");
  if (!probeConcurrency.ok) {
    return null;
  }
  const probeMaxTokens = parseOptionalFlagValue(argv, "--probe-max-tokens");
  if (!probeMaxTokens.ok) {
    return null;
  }
  const agent = parseOptionalFlagValue(argv, "--agent");
  if (!agent.ok) {
    return null;
  }
  const probeProfileValues = parseRepeatedFlagValues(argv, "--probe-profile");
  if (probeProfileValues === null) {
    return null;
  }
  const probeProfile =
    probeProfileValues.length === 0
      ? undefined
      : probeProfileValues.length === 1
        ? probeProfileValues[0]
        : probeProfileValues;
  return {
    probeProvider: probeProvider.value,
    probeTimeout: probeTimeout.value,
    probeConcurrency: probeConcurrency.value,
    probeMaxTokens: probeMaxTokens.value,
    agent: agent.value,
    probeProfile,
    json: hasFlag(argv, "--json"),
    plain: hasFlag(argv, "--plain"),
    check: hasFlag(argv, "--check"),
    probe: hasFlag(argv, "--probe"),
  };
}

/** Parse `openclaw channels list` display flags for the route-first list path. */
export function parseChannelsListRouteArgs(argv: string[]) {
  const positionals = getRoutedCommandPositionals(argv, {
    commandPath: ["channels", "list"],
    booleanFlags: ["--json", "--all"],
  });
  if (!positionals || positionals.length !== 0) {
    return null;
  }
  return {
    json: hasFlag(argv, "--json"),
    all: hasFlag(argv, "--all"),
  };
}

/** Parse `openclaw channels status` probe flags without full CLI registration. */
export function parseChannelsStatusRouteArgs(argv: string[]) {
  const positionals = getRoutedCommandPositionals(argv, {
    commandPath: ["channels", "status"],
    booleanFlags: ["--json", "--probe"],
    valueFlags: ["--timeout", "--channel"],
  });
  if (!positionals || positionals.length !== 0) {
    return null;
  }
  const timeout = parseOptionalFlagValue(argv, "--timeout");
  const channel = parseOptionalFlagValue(argv, "--channel");
  if (!timeout.ok) {
    return null;
  }
  if (!channel.ok) {
    return null;
  }
  return {
    channel: channel.value,
    json: hasFlag(argv, "--json"),
    probe: hasFlag(argv, "--probe"),
    timeout: timeout.value,
  };
}

/** Parse JSON-only `openclaw plugins list` flags for plugin inventory output. */
export function parsePluginsListRouteArgs(argv: string[]) {
  if (!hasFlag(argv, "--json")) {
    return null;
  }
  const positionals = getRoutedCommandPositionals(argv, {
    commandPath: ["plugins", "list"],
    booleanFlags: ["--json", "--enabled", "--verbose"],
  });
  if (!positionals || positionals.length !== 0) {
    return null;
  }
  return {
    json: true as const,
    enabled: hasFlag(argv, "--enabled"),
    verbose: hasFlag(argv, "--verbose"),
  };
}

function parseTasksListRouteArgsForCommandPath(argv: string[], commandPath: string[]) {
  if (!hasFlag(argv, "--json")) {
    return null;
  }
  const positionals = getRoutedCommandPositionals(argv, {
    commandPath,
    booleanFlags: ["--json"],
    valueFlags: ["--runtime", "--status"],
  });
  if (!positionals || positionals.length !== 0) {
    return null;
  }
  const runtime = parseOptionalFlagValue(argv, "--runtime");
  if (!runtime.ok) {
    return null;
  }
  const status = parseOptionalFlagValue(argv, "--status");
  if (!status.ok) {
    return null;
  }
  return {
    json: true as const,
    runtime: runtime.value,
    status: status.value,
  };
}

/** Parse both `openclaw tasks --json` and `openclaw tasks list --json` aliases. */
export function parseTasksListRouteArgs(argv: string[]) {
  return (
    parseTasksListRouteArgsForCommandPath(argv, ["tasks"]) ??
    parseTasksListRouteArgsForCommandPath(argv, ["tasks", "list"])
  );
}

/** Parse JSON-only `openclaw tasks audit` filters for the route-first audit path. */
export function parseTasksAuditRouteArgs(argv: string[]) {
  if (!hasFlag(argv, "--json")) {
    return null;
  }
  const positionals = getRoutedCommandPositionals(argv, {
    commandPath: ["tasks", "audit"],
    booleanFlags: ["--json"],
    valueFlags: ["--severity", "--code", "--limit"],
  });
  if (!positionals || positionals.length !== 0) {
    return null;
  }
  const severity = parseOptionalFlagValue(argv, "--severity");
  if (!severity.ok) {
    return null;
  }
  const code = parseOptionalFlagValue(argv, "--code");
  if (!code.ok) {
    return null;
  }
  const rawLimit = getFlagValue(argv, "--limit");
  if (rawLimit === null) {
    return null;
  }
  const limit = rawLimit === undefined ? undefined : parseStrictPositiveIntOrUndefined(rawLimit);
  if (rawLimit !== undefined && limit === undefined) {
    return null;
  }
  return {
    json: true as const,
    severity: severity.value,
    code: code.value,
    limit,
  };
}