feat: export batch orchestration helpers

Author: thymikee

package.json

@@ -33,6 +33,10 @@
       "import": "./dist/src/metro.js",
       "types": "./dist/src/metro.d.ts"
     },
+    "./batch": {
+      "import": "./dist/src/batch.js",
+      "types": "./dist/src/batch.d.ts"
+    },
     "./remote-config": {
       "import": "./dist/src/remote-config.js",
       "types": "./dist/src/remote-config.d.ts"

rslib.config.ts

@@ -19,6 +19,7 @@ export default defineConfig({
           index: 'src/index.ts',
           io: 'src/io.ts',
           artifacts: 'src/artifacts.ts',
+          batch: 'src/batch.ts',
           metro: 'src/metro.ts',
           'remote-config': 'src/remote-config.ts',
           'install-source': 'src/install-source.ts',

src/__tests__/batch-public.test.ts

@@ -0,0 +1,66 @@
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+import {
+  BATCH_BLOCKED_COMMANDS,
+  DEFAULT_BATCH_MAX_STEPS,
+  INHERITED_PARENT_FLAG_KEYS,
+  buildBatchStepFlags,
+  runBatch,
+  validateAndNormalizeBatchSteps,
+  type BatchStepResult,
+} from '../batch.ts';
+import type { DaemonRequest } from '../contracts.ts';
+
+test('public batch entrypoint exports daemon-compatible orchestration helpers', async () => {
+  const seenCommands: string[] = [];
+  const req: Omit<DaemonRequest, 'token'> = {
+    command: 'batch',
+    positionals: [],
+    flags: {
+      platform: 'ios',
+      udid: 'sim-1',
+      batchSteps: [
+        { command: 'open', positionals: ['settings'] },
+        { command: 'wait', positionals: ['100'], flags: { platform: 'android' } },
+      ],
+    },
+  };
+
+  const response = await runBatch(req, 'resolved-session', async (stepReq) => {
+    seenCommands.push(stepReq.command);
+    assert.equal(stepReq.session, 'resolved-session');
+    assert.equal(stepReq.flags?.session, 'resolved-session');
+    if (stepReq.command === 'open') {
+      assert.equal(stepReq.flags?.platform, 'ios');
+      assert.equal(stepReq.flags?.udid, 'sim-1');
+    }
+    if (stepReq.command === 'wait') {
+      assert.equal(stepReq.flags?.platform, 'android');
+    }
+    return { ok: true, data: { command: stepReq.command } };
+  });
+
+  assert.equal(response.ok, true);
+  assert.deepEqual(seenCommands, ['open', 'wait']);
+  if (response.ok) {
+    assert.equal(response.data?.total, 2);
+    const results = response.data?.results as BatchStepResult[];
+    assert.equal(results[0]?.command, 'open');
+  }
+});
+
+test('public batch helpers expose validation and flag policy', () => {
+  assert.equal(DEFAULT_BATCH_MAX_STEPS, 100);
+  assert.equal(BATCH_BLOCKED_COMMANDS.has('replay'), true);
+  assert.equal(INHERITED_PARENT_FLAG_KEYS.includes('udid'), true);
+  assert.deepEqual(validateAndNormalizeBatchSteps([{ command: 'WAIT', positionals: ['100'] }], 1), [
+    { command: 'wait', positionals: ['100'], flags: {}, runtime: undefined },
+  ]);
+  assert.deepEqual(
+    buildBatchStepFlags(
+      { platform: 'ios', udid: 'sim-1', batchSteps: [{ command: 'open' }] },
+      { batchMaxSteps: 10, platform: 'android' },
+    ),
+    { platform: 'android', udid: 'sim-1' },
+  );
+});

src/batch.ts

@@ -0,0 +1,17 @@
+export {
+  BATCH_BLOCKED_COMMANDS,
+  DEFAULT_BATCH_MAX_STEPS,
+  INHERITED_PARENT_FLAG_KEYS,
+  buildBatchStepFlags,
+  runBatch,
+  validateAndNormalizeBatchSteps,
+} from './core/batch.ts';
+
+export type {
+  BatchFlags,
+  BatchInvoke,
+  BatchRequest,
+  BatchStep,
+  BatchStepResult,
+  NormalizedBatchStep,
+} from './core/batch.ts';

src/cli.ts

@@ -5,8 +5,7 @@ import { readVersion } from './utils/version.ts';
 import { pathToFileURL } from 'node:url';
 import { sendToDaemon } from './daemon-client.ts';
 import fs from 'node:fs';
-import type { BatchStep } from './core/dispatch.ts';
-import { parseBatchStepsJson } from './core/batch.ts';
+import { parseBatchStepsJson, type BatchStep } from './core/batch.ts';
 import {
   createAgentDeviceClient,
   type AgentDeviceClientConfig,

src/cli/commands/connection-runtime.ts

@@ -11,7 +11,7 @@ import {
   type RemoteConnectionState,
 } from '../../remote-connection-state.ts';
 import { REMOTE_CONFIG_FIELD_SPECS, type RemoteConfigProfile } from '../../remote-config-schema.ts';
-import type { BatchStep } from '../../core/dispatch.ts';
+import type { BatchStep } from '../../core/batch.ts';
 import { AppError } from '../../utils/errors.ts';
 import type { LeaseBackend, SessionRuntimeHints } from '../../contracts.ts';
 import type { CliFlags } from '../../utils/command-schema.ts';

src/core/__tests__/batch.test.ts

@@ -1,7 +1,6 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
-import { validateAndNormalizeBatchSteps } from '../batch.ts';
-import type { BatchStep } from '../dispatch.ts';
+import { validateAndNormalizeBatchSteps, type BatchStep } from '../batch.ts';
 
 test('validateAndNormalizeBatchSteps rejects unknown top-level step fields', () => {
   assert.throws(

src/core/batch.ts

@@ -1,14 +1,42 @@
-import { AppError } from '../utils/errors.ts';
-import type { BatchStep, CommandFlags } from './dispatch.ts';
+import type { DaemonRequest, DaemonResponse } from '../contracts.ts';
+import { AppError, asAppError } from '../utils/errors.ts';
 
 export const DEFAULT_BATCH_MAX_STEPS = 100;
-const BATCH_BLOCKED_COMMANDS = new Set(['batch', 'replay']);
+export const BATCH_BLOCKED_COMMANDS: ReadonlySet<string> = new Set(['batch', 'replay']);
 const BATCH_ALLOWED_STEP_KEYS = new Set(['command', 'positionals', 'flags', 'runtime']);
+export const INHERITED_PARENT_FLAG_KEYS = [
+  'platform',
+  'target',
+  'device',
+  'udid',
+  'serial',
+  'verbose',
+  'out',
+] as const;
+
+export type BatchStep = {
+  command: string;
+  positionals?: string[];
+  flags?: Record<string, unknown>;
+  runtime?: unknown;
+};
+
+export type BatchFlags = Record<string, unknown> & {
+  batchOnError?: 'stop';
+  batchMaxSteps?: number;
+  batchSteps?: BatchStep[];
+};
+
+export type BatchRequest = Omit<DaemonRequest, 'flags'> & {
+  flags?: BatchFlags | Record<string, unknown>;
+};
+
+export type BatchInvoke = (req: BatchRequest) => Promise<DaemonResponse>;
 
 export type NormalizedBatchStep = {
   command: string;
   positionals: string[];
-  flags: Partial<CommandFlags>;
+  flags: Record<string, unknown>;
   runtime?: unknown;
 };
 
@@ -20,6 +48,68 @@ export type BatchStepResult = {
   durationMs: number;
 };
 
+export async function runBatch(
+  req: BatchRequest,
+  sessionName: string,
+  invoke: BatchInvoke,
+): Promise<DaemonResponse> {
+  const flags = readBatchFlags(req.flags);
+  const batchOnError = flags?.batchOnError ?? 'stop';
+  if (batchOnError !== 'stop') {
+    return batchErrorResponse('INVALID_ARGS', `Unsupported batch on-error mode: ${batchOnError}.`);
+  }
+  const batchMaxSteps = flags?.batchMaxSteps ?? DEFAULT_BATCH_MAX_STEPS;
+  if (!Number.isInteger(batchMaxSteps) || batchMaxSteps < 1 || batchMaxSteps > 1000) {
+    return batchErrorResponse(
+      'INVALID_ARGS',
+      `Invalid batch max-steps: ${String(flags?.batchMaxSteps)}`,
+    );
+  }
+  try {
+    const steps = validateAndNormalizeBatchSteps(flags?.batchSteps, batchMaxSteps);
+    const startedAt = Date.now();
+    const partialResults: BatchStepResult[] = [];
+    for (let index = 0; index < steps.length; index += 1) {
+      const step = steps[index];
+      const stepResponse = await runBatchStep(req, sessionName, step, invoke, index + 1);
+      if (!stepResponse.ok) {
+        return {
+          ok: false,
+          error: {
+            code: stepResponse.error.code,
+            message: `Batch failed at step ${stepResponse.step} (${step.command}): ${stepResponse.error.message}`,
+            hint: stepResponse.error.hint,
+            diagnosticId: stepResponse.error.diagnosticId,
+            logPath: stepResponse.error.logPath,
+            details: {
+              ...(stepResponse.error.details ?? {}),
+              step: stepResponse.step,
+              command: step.command,
+              positionals: step.positionals,
+              executed: index,
+              total: steps.length,
+              partialResults,
+            },
+          },
+        };
+      }
+      partialResults.push(stepResponse.result);
+    }
+    return {
+      ok: true,
+      data: {
+        total: steps.length,
+        executed: steps.length,
+        totalDurationMs: Date.now() - startedAt,
+        results: partialResults,
+      },
+    };
+  } catch (error) {
+    const appErr = asAppError(error);
+    return batchErrorResponse(appErr.code, appErr.message, appErr.details);
+  }
+}
+
 export function parseBatchStepsJson(raw: string): BatchStep[] {
   let parsed: unknown;
   try {
@@ -34,7 +124,7 @@ export function parseBatchStepsJson(raw: string): BatchStep[] {
 }
 
 export function validateAndNormalizeBatchSteps(
-  steps: CommandFlags['batchSteps'],
+  steps: unknown,
   maxSteps: number,
 ): NormalizedBatchStep[] {
   if (!Array.isArray(steps) || steps.length === 0) {
@@ -49,7 +139,7 @@ export function validateAndNormalizeBatchSteps(
 
   const normalized: NormalizedBatchStep[] = [];
   for (let index = 0; index < steps.length; index += 1) {
-    const step = steps[index];
+    const step = steps[index] as Partial<BatchStep>;
     if (!step || typeof step !== 'object') {
       throw new AppError('INVALID_ARGS', `Invalid batch step at index ${index}.`);
     }
@@ -93,9 +183,105 @@ export function validateAndNormalizeBatchSteps(
     normalized.push({
       command,
       positionals: positionals as string[],
-      flags: (step.flags ?? {}) as Partial<CommandFlags>,
+      flags: (step.flags ?? {}) as Record<string, unknown>,
       runtime: step.runtime,
     });
   }
   return normalized;
 }
+
+export function buildBatchStepFlags(
+  parentFlags: BatchFlags | Record<string, unknown> | undefined,
+  stepFlags: BatchStep['flags'] | Record<string, unknown> | undefined,
+): BatchFlags {
+  const {
+    batchSteps: _batchSteps,
+    batchOnError: _batchOnError,
+    batchMaxSteps: _batchMaxSteps,
+    ...merged
+  } = stepFlags ?? {};
+  return mergeParentFlags(readBatchFlags(parentFlags), merged as BatchFlags);
+}
+
+export function mergeParentFlags<TFlags extends Record<string, unknown>>(
+  parentFlags: BatchFlags | Record<string, unknown> | undefined,
+  childFlags: TFlags,
+): TFlags {
+  const parentRecord = readBatchFlags(parentFlags) ?? {};
+  const childRecord = childFlags as Record<string, unknown>;
+  for (const key of INHERITED_PARENT_FLAG_KEYS) {
+    if (childRecord[key] === undefined && parentRecord[key] !== undefined) {
+      childRecord[key] = parentRecord[key];
+    }
+  }
+  return childFlags;
+}
+
+async function runBatchStep(
+  req: BatchRequest,
+  sessionName: string,
+  step: NormalizedBatchStep,
+  invoke: BatchInvoke,
+  stepNumber: number,
+): Promise<
+  | { ok: true; step: number; result: BatchStepResult }
+  | {
+      ok: false;
+      step: number;
+      error: {
+        code: string;
+        message: string;
+        hint?: string;
+        diagnosticId?: string;
+        logPath?: string;
+        details?: Record<string, unknown>;
+      };
+    }
+> {
+  const stepStartedAt = Date.now();
+  const stepFlags = buildBatchStepFlags(req.flags, step.flags);
+  if (stepFlags.session === undefined) {
+    stepFlags.session = sessionName;
+  }
+  const response = await invoke({
+    token: req.token,
+    session: sessionName,
+    command: step.command,
+    positionals: step.positionals,
+    flags: stepFlags,
+    runtime: (step.runtime === undefined ? req.runtime : step.runtime) as DaemonRequest['runtime'],
+    meta: req.meta,
+  });
+  const durationMs = Date.now() - stepStartedAt;
+  if (!response.ok) {
+    return { ok: false, step: stepNumber, error: response.error };
+  }
+  return {
+    ok: true,
+    step: stepNumber,
+    result: {
+      step: stepNumber,
+      command: step.command,
+      ok: true,
+      data: response.data ?? {},
+      durationMs,
+    },
+  };
+}
+
+function readBatchFlags(
+  flags: BatchFlags | Record<string, unknown> | undefined,
+): BatchFlags | undefined {
+  return flags as BatchFlags | undefined;
+}
+
+function batchErrorResponse(
+  code: string,
+  message: string,
+  details?: Record<string, unknown>,
+): Extract<DaemonResponse, { ok: false }> {
+  return {
+    ok: false,
+    error: { code, message, ...(details ? { details } : {}) },
+  };
+}