agent-scenario-loop 0.1.0

package/dist/runner/argent.d.ts

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+type CliArgs = {
+    app?: string | boolean;
+    'app-flag'?: string | boolean;
+    argent?: string | boolean;
+    'base-args'?: string | boolean;
+    check?: string | boolean;
+    'command-timeout-ms'?: string | boolean;
+    device?: string | boolean;
+    'device-flag'?: string | boolean;
+    'ios-simctl-screenshot-fallback'?: string | boolean;
+    out?: string | boolean;
+    platform?: string | boolean;
+    'run-id'?: string | boolean;
+    scenario?: string | boolean;
+    serial?: string | boolean;
+    'screen-height'?: string | boolean;
+    'screen-width'?: string | boolean;
+    udid?: string | boolean;
+    'wait-ms'?: string | boolean;
+    xcrun?: string | boolean;
+    [key: string]: string | boolean | undefined;
+};
+type CommandResult = {
+    args: string[];
+    command: string;
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+};
+type CommandExecutor = (command: string, args: string[]) => Promise<CommandResult>;
+type ScenarioExecutionStep = import('../core/execution-plan').ScenarioExecutionStep;
+type ArgentAvailabilityOptions = {
+    argentCommand?: string;
+    baseArgs?: string[];
+    commandTimeoutMs?: number;
+    executor?: CommandExecutor;
+    requiredTools?: string[];
+};
+type ArgentAvailabilityCheck = {
+    args: string[];
+    code: string;
+    command: string;
+    exitCode: number;
+    metadata?: Record<string, string | number | boolean | null>;
+    message: string;
+    name: string;
+    stderrPreview?: string;
+    status: 'failed' | 'passed';
+    stdoutPreview?: string;
+};
+type ArgentAvailabilityResult = {
+    argentCommand: string;
+    baseArgs: string[];
+    checks: ArgentAvailabilityCheck[];
+    requiredTools: string[];
+    status: 'failed' | 'passed';
+};
+type ArgentAvailabilityArtifactOptions = {
+    outputDir: string;
+    result: ArgentAvailabilityResult;
+    runId?: string;
+};
+type ArgentDriverStep = {
+    appId?: string;
+    captureFileName?: string;
+    driverAction: 'assertVisible' | 'inspectTree' | 'launch' | 'screenshot' | 'scroll' | 'tap';
+    durationMs?: number;
+    endX?: number;
+    endY?: number;
+    rawFileName: string;
+    required: boolean;
+    screenSize?: import('./argent-driver').ArgentScreenSize;
+    selector?: import('./argent-driver').ArgentSelector;
+    startX?: number;
+    startY?: number;
+    stepId: string;
+    waitMs: number;
+    x?: number;
+    y?: number;
+};
+type ArgentCaptureOptions = {
+    app?: string | null;
+    appFlag?: string;
+    argentCommand?: string;
+    baseArgs?: string[];
+    commandTimeoutMs?: number;
+    delay?: (ms: number) => Promise<void>;
+    deviceFlag?: string;
+    deviceId: string;
+    executor?: CommandExecutor;
+    iosSimctlExecutor?: CommandExecutor;
+    iosSimctlScreenshotFallback?: boolean;
+    outputDir?: string;
+    platform: 'android' | 'ios';
+    resolveBootedIosSimulatorUdid?: () => Promise<string | null>;
+    runId?: string;
+    scenario: Record<string, unknown>;
+    screenSize?: import('./argent-driver').ArgentScreenSize;
+    waitMs?: number;
+    xcrunPath?: string;
+};
+type ArgentCaptureResult = {
+    agentSummary: string;
+    captures: {
+        screenshots: string[];
+    };
+    health: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    raw: Record<string, string>;
+    runDir: string;
+    verdict: Record<string, unknown>;
+};
+type IosSimctlScreenshotFallbackResult = {
+    capturePath?: string;
+    rawFileName: string;
+    result: CommandResult;
+};
+/**
+ * Prints CLI usage.
+ *
+ * @param {{write: (message: string) => unknown}} output
+ * @returns {void}
+ */
+declare function usage(output?: {
+    write: (message: string) => unknown;
+}): void;
+/**
+ * Parses `--key value` CLI arguments.
+ *
+ * @param {string[]} argv
+ * @returns {CliArgs}
+ */
+declare function parseArgs(argv: string[]): CliArgs;
+/**
+ * Runs a command and captures stdout, stderr, and exit code without throwing.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {Promise<CommandResult>}
+ */
+declare function execFileCommand(command: string, args: string[]): Promise<CommandResult>;
+/**
+ * Runs a command with a bounded timeout and captures stdout, stderr, and exit code without throwing.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @param {number} [timeoutMs]
+ * @returns {Promise<CommandResult>}
+ */
+declare function execFileCommandWithTimeout(command: string, args: string[], timeoutMs?: number): Promise<CommandResult>;
+/**
+ * Returns adapter options for an Argent-backed step.
+ *
+ * @param {ScenarioExecutionStep} step
+ * @returns {Record<string, unknown>}
+ */
+declare function readArgentStepOptions(step: ScenarioExecutionStep): Record<string, unknown>;
+/**
+ * Returns true when a normalized step has a portable selector.
+ *
+ * @param {unknown} value
+ * @returns {value is import('./argent-driver').ArgentSelector}
+ */
+declare function isArgentSelector(value: unknown): value is import('./argent-driver').ArgentSelector;
+/**
+ * Returns the default raw file name for one Argent action.
+ *
+ * @param {{driverAction: ArgentDriverStep['driverAction'], index: number}} options
+ * @returns {string}
+ */
+declare function defaultArgentRawFileName({ driverAction, index, }: {
+    driverAction: ArgentDriverStep['driverAction'];
+    index: number;
+}): string;
+/**
+ * Converts a scenario step id into a safe artifact filename segment.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+declare function sanitizeArtifactFileSegment(value: string): string;
+/**
+ * Returns the simctl fallback screenshot filename for an Argent screenshot step.
+ *
+ * @param {ArgentDriverStep} driverStep
+ * @returns {string}
+ */
+declare function defaultIosSimctlFallbackScreenshotFileName(driverStep: ArgentDriverStep): string;
+/**
+ * Expands normalized scenario steps into Argent driver actions.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @param {import('./argent-driver').ArgentScreenSize | undefined} screenSize
+ * @returns {ArgentDriverStep[]}
+ */
+declare function resolveArgentDriverSteps(scenario: Record<string, any>, screenSize?: import('./argent-driver').ArgentScreenSize): ArgentDriverStep[];
+/**
+ * Returns profile-time validation errors for Argent driver steps.
+ *
+ * @param {ArgentDriverStep[]} driverSteps
+ * @param {{app?: string | null}} options
+ * @returns {string[]}
+ */
+declare function validateArgentDriverSteps(driverSteps: ArgentDriverStep[], options?: {
+    app?: string | null;
+}): string[];
+/**
+ * Builds scalar health metadata for one portable selector.
+ *
+ * @param {import('./argent-driver').ArgentSelector | undefined} selector
+ * @returns {Record<string, string>}
+ */
+declare function buildArgentSelectorHealthMetadata(selector?: import('./argent-driver').ArgentSelector): Record<string, string>;
+/**
+ * Runs one Argent driver action.
+ *
+ * @param {{driver: import('./argent-driver').ArgentDriver, driverStep: ArgentDriverStep}} options
+ * @returns {Promise<import('./argent-driver').ArgentCommandResult>}
+ */
+declare function runArgentDriverStep({ driver, driverStep, }: {
+    driver: import('./argent-driver').ArgentDriver;
+    driverStep: ArgentDriverStep;
+}): Promise<import('./argent-driver').ArgentCommandResult>;
+/**
+ * Captures an iOS screenshot through simctl when Argent's iOS screenshot backend is unavailable.
+ *
+ * @param {{capturesDir: string, deviceId: string, driverStep: ArgentDriverStep, executor?: CommandExecutor, xcrunPath: string}} options
+ * @returns {Promise<IosSimctlScreenshotFallbackResult>}
+ */
+declare function runIosSimctlScreenshotFallback({ capturesDir, deviceId, driverStep, executor, xcrunPath, }: {
+    capturesDir: string;
+    deviceId: string;
+    driverStep: ArgentDriverStep;
+    executor?: CommandExecutor;
+    xcrunPath: string;
+}): Promise<IosSimctlScreenshotFallbackResult>;
+/**
+ * Builds a stable health code suffix for one Argent driver action.
+ *
+ * @param {ArgentDriverStep['driverAction']} driverAction
+ * @returns {string}
+ */
+declare function argentDriverActionCode(driverAction: ArgentDriverStep['driverAction']): string;
+/**
+ * Builds a health artifact from Argent capture checks.
+ *
+ * @param {{flowId?: string, runId: string, scenarioId: string, checks: Record<string, unknown>[]}} options
+ * @returns {Record<string, unknown>}
+ */
+declare function buildArgentHealth({ checks, flowId, runId, scenarioId, }: {
+    checks: Record<string, unknown>[];
+    flowId?: string;
+    runId: string;
+    scenarioId: string;
+}): Record<string, unknown>;
+/**
+ * Builds a verdict artifact for Argent capture readiness.
+ *
+ * @param {{health: Record<string, unknown>, runId: string, scenarioId: string, flowId?: string}} options
+ * @returns {Record<string, unknown>}
+ */
+declare function buildArgentVerdict({ flowId, health, runId, scenarioId, }: {
+    flowId?: string;
+    health: Record<string, unknown>;
+    runId: string;
+    scenarioId: string;
+}): Record<string, unknown>;
+/**
+ * Splits CLI base args without invoking a shell.
+ *
+ * @param {unknown} value
+ * @returns {string[] | undefined}
+ */
+declare function parseBaseArgs(value: unknown): string[] | undefined;
+/**
+ * Returns root-level Argent args from an `argent run` command shape.
+ *
+ * @param {string[]} baseArgs
+ * @returns {string[]}
+ */
+declare function deriveArgentRootArgs(baseArgs: string[]): string[];
+/**
+ * Writes ASL artifacts for an Argent command-surface availability check.
+ *
+ * @param {ArgentAvailabilityArtifactOptions} options
+ * @returns {Promise<{agentSummary: string, health: Record<string, unknown>, runDir: string, verdict: Record<string, unknown>}>}
+ */
+declare function writeArgentAvailabilityArtifacts({ outputDir, result, runId, }: ArgentAvailabilityArtifactOptions): Promise<{
+    agentSummary: string;
+    health: Record<string, unknown>;
+    runDir: string;
+    verdict: Record<string, unknown>;
+}>;
+/**
+ * Builds one availability check result from an Argent command execution.
+ *
+ * @param {{code: string, expectedPattern: RegExp, name: string, result: CommandResult}} options
+ * @returns {ArgentAvailabilityCheck}
+ */
+declare function buildArgentAvailabilityCheck({ code, expectedPattern, name, result, }: {
+    code: string;
+    expectedPattern: RegExp;
+    name: string;
+    result: CommandResult;
+}): ArgentAvailabilityCheck;
+/**
+ * Verifies that the configured Argent command can invoke the ASL-required tool surface.
+ *
+ * @param {ArgentAvailabilityOptions} options
+ * @returns {Promise<ArgentAvailabilityResult>}
+ */
+declare function checkArgentAvailability({ argentCommand, baseArgs, commandTimeoutMs, executor, requiredTools, }?: ArgentAvailabilityOptions): Promise<ArgentAvailabilityResult>;
+/**
+ * Returns a screen size from CLI values when both dimensions are present.
+ *
+ * @param {{width?: unknown, height?: unknown}} options
+ * @returns {import('./argent-driver').ArgentScreenSize | undefined}
+ */
+declare function readScreenSize({ height, width, }: {
+    height?: unknown;
+    width?: unknown;
+}): import('./argent-driver').ArgentScreenSize | undefined;
+/**
+ * Copies a screenshot produced by Argent into the stable ASL captures folder.
+ *
+ * @param {{capturesDir: string, capturePath: string, preferredFileName?: string}} options
+ * @returns {Promise<string | null>}
+ */
+declare function copyArgentCapture({ capturePath, capturesDir, preferredFileName, }: {
+    capturePath: string;
+    capturesDir: string;
+    preferredFileName?: string;
+}): Promise<string | null>;
+/**
+ * Runs scenario-declared portable actions through Argent and writes ASL artifacts.
+ *
+ * @param {ArgentCaptureOptions} options
+ * @returns {Promise<ArgentCaptureResult>}
+ */
+declare function runArgentCapture({ app, appFlag, argentCommand, baseArgs, commandTimeoutMs, delay: wait, deviceFlag, deviceId, executor, iosSimctlExecutor, iosSimctlScreenshotFallback, outputDir, platform, resolveBootedIosSimulatorUdid: resolveBooted, runId, scenario, screenSize, waitMs, xcrunPath, }: ArgentCaptureOptions): Promise<ArgentCaptureResult>;
+/**
+ * Runs the Argent capture CLI.
+ *
+ * @returns {Promise<void>}
+ */
+declare function main(): Promise<void>;
+export { argentDriverActionCode, buildArgentHealth, buildArgentAvailabilityCheck, buildArgentSelectorHealthMetadata, buildArgentVerdict, checkArgentAvailability, copyArgentCapture, defaultArgentRawFileName, defaultIosSimctlFallbackScreenshotFileName, deriveArgentRootArgs, execFileCommand, execFileCommandWithTimeout, isArgentSelector, main, parseArgs, parseBaseArgs, readArgentStepOptions, readScreenSize, resolveArgentDriverSteps, runArgentCapture, runArgentDriverStep, runIosSimctlScreenshotFallback, sanitizeArtifactFileSegment, usage, validateArgentDriverSteps, writeArgentAvailabilityArtifacts, };
+export type { ArgentAvailabilityCheck, ArgentAvailabilityOptions, ArgentAvailabilityResult, ArgentCaptureOptions, ArgentCaptureResult, ArgentDriverStep, CliArgs, CommandExecutor, CommandResult, };