refactor: reduce duplication and simplify codebase (#374)

* refactor: reduce duplication and simplify codebase

Eliminate copy-pasted functions, inline error boilerplate, and repeated
patterns across daemon handlers and platform modules.

Key changes:
- Deduplicate isEnvTruthy, displayNodeLabel, roundPercent into single sources
- Extract throwDaemonError helper for client/CLI daemon response errors
- Add sessionNotFoundResponse/unsupportedOperationResponse helpers and
  adopt errorResponse() across ~30 handler files (-565 lines)
- Unify BATCH_PARENT_FLAG_KEYS/REPLAY_PARENT_FLAG_KEYS into shared
  mergeParentFlags helper in handler-utils
- Extract createLinuxToolResolver for screenshot/clipboard tool detection
- Remove stale type-sync comments from contracts.ts and metro.ts

* refactor: deeper structural simplification pass

Bigger wins from restructuring, not just mechanical dedup:

- cli.ts: move logTailStopper to try/finally (eliminates 28 duplicate
  calls), extract writeCommandCliOutput/writeLogsCliOutput/writeNetworkCliOutput
  from 350-line if/else chain, fix remaining throwDaemonError site
- session-store.ts: replace 67-line sanitizeFlags destructure/reconstruct
  with 10-line pick-from-array loop
- record-trace: extract finalizeRecordingOverlay helper, replacing 4
  copies of the telemetry+overlay block across ios/android/recording files
- Deduplicate normalizeText (finders.ts + selectors-match.ts)
- Fix isEnvTruthy to preserve whitespace-tolerant parsing (.trim())

* fix: ensure logTailStopper runs before process.exit

process.exit() does not unwind the stack, so finally blocks are
skipped. Restore explicit logTailStopper() calls before each
process.exit() to prevent leaking the background daemon log tail
process. The finally block remains as a safety net for normal
return paths.

Also refactor writeCommandCliOutput to return an exit code instead
of calling process.exit() directly, keeping the exit decision in
the caller where cleanup is visible.

* refactor: simplify daemon failure responses

* refactor: remove redundant daemon response cast

Author: thymikee

src/cli.ts

@@ -1,6 +1,6 @@
 import { sendToDaemon } from './daemon-client.ts';
 import { prepareMetroRuntime } from './client-metro.ts';
-import { AppError } from './utils/errors.ts';
+import { throwDaemonError } from './daemon-error.ts';
 import {
   buildFlags,
   buildMeta,
@@ -58,12 +58,7 @@ export function createAgentDeviceClient(
       meta: buildMeta(merged),
     });
     if (!response.ok) {
-      throw new AppError(response.error.code as any, response.error.message, {
-        ...(response.error.details ?? {}),
-        hint: response.error.hint,
-        diagnosticId: response.error.diagnosticId,
-        logPath: response.error.logPath,
-      });
+      throwDaemonError(response.error);
     }
     return (response.data ?? {}) as Record<string, unknown>;
   };

src/client.ts

@@ -1,5 +1,3 @@
-// Keep this public daemon contract shape aligned with MetroRuntimeHints in src/metro.ts
-// and the internal MetroRuntimeHints in src/client-metro.ts.
 export type SessionRuntimeHints = {
   platform?: 'ios' | 'android';
   metroHost?: string;

src/contracts.ts

@@ -0,0 +1,11 @@
+import { AppError } from './utils/errors.ts';
+import type { DaemonError } from './contracts.ts';
+
+export function throwDaemonError(error: DaemonError): never {
+  throw new AppError(error.code as any, error.message, {
+    ...(error.details ?? {}),
+    hint: error.hint,
+    diagnosticId: error.diagnosticId,
+    logPath: error.logPath,
+  });
+}

src/daemon-error.ts

@@ -194,7 +194,7 @@ async function handleFindWait(
     }
     await new Promise((resolve) => setTimeout(resolve, 300));
   }
-  return { ok: false, error: { code: 'COMMAND_FAILED', message: 'find wait timed out' } };
+  return errorResponse('COMMAND_FAILED', 'find wait timed out');
 }
 
 async function handleFindExists(ctx: FindContext): Promise<DaemonResponse> {
@@ -280,7 +280,7 @@ async function handleFindFill(
 ): Promise<DaemonResponse> {
   const { req, sessionName, sessionStore, session, invoke, command } = ctx;
   if (!value) {
-    return { ok: false, error: { code: 'INVALID_ARGS', message: 'find fill requires text' } };
+    return errorResponse('INVALID_ARGS', 'find fill requires text');
   }
   const response = await invoke({
     token: req.token,
@@ -305,10 +305,7 @@ async function handleFindFocus(ctx: FindContext, match: ResolvedMatch): Promise<
   const { req, sessionStore, session, device, command, logPath } = ctx;
   const coords = match.node.rect ? centerOfRect(match.node.rect) : null;
   if (!coords) {
-    return {
-      ok: false,
-      error: { code: 'COMMAND_FAILED', message: 'matched element has no bounds' },
-    };
+    return errorResponse('COMMAND_FAILED', 'matched element has no bounds');
   }
   const response = await dispatchCommand(
     device,
@@ -337,14 +334,11 @@ async function handleFindType(
 ): Promise<DaemonResponse> {
   const { req, sessionStore, session, device, command, logPath } = ctx;
   if (!value) {
-    return { ok: false, error: { code: 'INVALID_ARGS', message: 'find type requires text' } };
+    return errorResponse('INVALID_ARGS', 'find type requires text');
   }
   const coords = match.node.rect ? centerOfRect(match.node.rect) : null;
   if (!coords) {
-    return {
-      ok: false,
-      error: { code: 'COMMAND_FAILED', message: 'matched element has no bounds' },
-    };
+    return errorResponse('COMMAND_FAILED', 'matched element has no bounds');
   }
   await dispatchCommand(device, 'focus', [String(coords.x), String(coords.y)], req.flags?.out, {
     ...contextFromFlags(logPath, req.flags, session?.appBundleId, session?.trace?.outPath),
@@ -375,19 +369,16 @@ function buildAmbiguousMatchError(
       extractNodeText(candidate) || candidate.label || candidate.identifier || candidate.type || '';
     return `@${candidate.ref}${label ? `(${label})` : ''}`;
   });
-  return {
-    ok: false,
-    error: {
-      code: 'AMBIGUOUS_MATCH',
-      message: `find matched ${matches.length} elements for ${locator} "${query}". Use a more specific locator or selector.`,
-      details: {
-        locator,
-        query,
-        matches: matches.length,
-        candidates,
-      },
+  return errorResponse(
+    'AMBIGUOUS_MATCH',
+    `find matched ${matches.length} elements for ${locator} "${query}". Use a more specific locator or selector.`,
+    {
+      locator,
+      query,
+      matches: matches.length,
+      candidates,
     },
-  };
+  );
 }
 
 type FindAction =

src/daemon/handlers/find.ts

@@ -20,3 +20,34 @@ export function recordSessionAction(
     result: result ?? {},
   });
 }
+
+/**
+ * Flag keys inherited from a parent request (batch/replay) into child step flags.
+ * Shared between batch and replay so the inheritance rules stay in sync.
+ */
+export const INHERITED_PARENT_FLAG_KEYS: ReadonlyArray<keyof CommandFlags> = [
+  'platform',
+  'target',
+  'device',
+  'udid',
+  'serial',
+  'verbose',
+  'out',
+];
+
+/**
+ * Merge parent flag values into child flags for keys that are undefined in the child.
+ */
+export function mergeParentFlags(
+  parentFlags: CommandFlags | undefined,
+  childFlags: CommandFlags,
+): CommandFlags {
+  const parentRecord = (parentFlags ?? {}) as Record<string, unknown>;
+  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;
+}

src/daemon/handlers/handler-utils.ts

@@ -13,6 +13,7 @@ import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
 import { resolveInstallFromSourceResultTarget } from '../../client-shared.ts';
 import { AppError, normalizeError } from '../../utils/errors.ts';
 import { withSuccessText } from '../../utils/success-text.ts';
+import { errorResponse } from './response.ts';
 
 function normalizePlatform(platform: CommandFlags['platform']): 'ios' | 'android' | undefined {
   return platform === 'ios' || platform === 'android' ? platform : undefined;
@@ -73,13 +74,10 @@ export async function handleInstallFromSourceCommand(params: {
       flags: req.flags,
     });
     if (!isCommandSupportedOnDevice('install', device)) {
-      return {
-        ok: false,
-        error: {
-          code: 'UNSUPPORTED_OPERATION',
-          message: 'install_from_source is not supported on this device',
-        },
-      };
+      return errorResponse(
+        'UNSUPPORTED_OPERATION',
+        'install_from_source is not supported on this device',
+      );
     }
 
     const requestSignal = getRequestSignal(req.meta?.requestId);

src/daemon/handlers/install-source.ts

@@ -21,6 +21,7 @@ import { readSnapshotNodesReferenceFrame } from './interaction-touch-reference-f
 import { resolveRefTargetWithRectRefresh, type ResolveRefTarget } from './interaction-targeting.ts';
 import { unsupportedMacOsDesktopSurfaceInteraction } from './interaction-touch-policy.ts';
 import type { RefSnapshotFlagGuardResponse } from './interaction-flags.ts';
+import { errorResponse } from './response.ts';
 
 export async function handleFillCommand(params: {
   req: DaemonRequest;
@@ -49,17 +50,11 @@ export async function handleFillCommand(params: {
     }
   }
   if (session && !isCommandSupportedOnDevice('fill', session.device)) {
-    return {
-      ok: false,
-      error: { code: 'UNSUPPORTED_OPERATION', message: 'fill is not supported on this device' },
-    };
+    return errorResponse('UNSUPPORTED_OPERATION', 'fill is not supported on this device');
   }
   if (req.positionals?.[0]?.startsWith('@')) {
     if (!session) {
-      return {
-        ok: false,
-        error: { code: 'SESSION_NOT_FOUND', message: 'No active session. Run open first.' },
-      };
+      return errorResponse('SESSION_NOT_FOUND', 'No active session. Run open first.');
     }
     const invalidRefFlagsResponse = refSnapshotFlagGuardResponse('fill', req.flags);
     if (invalidRefFlagsResponse) return invalidRefFlagsResponse;
@@ -70,10 +65,7 @@ export async function handleFillCommand(params: {
         ? req.positionals.slice(2).join(' ')
         : req.positionals.slice(1).join(' ');
     if (!text) {
-      return {
-        ok: false,
-        error: { code: 'INVALID_ARGS', message: 'fill requires text after ref' },
-      };
+      return errorResponse('INVALID_ARGS', 'fill requires text after ref');
     }
 
     const resolvedRefFillTarget = await resolveRefTargetWithRectRefresh({
@@ -91,7 +83,7 @@ export async function handleFillCommand(params: {
       captureSnapshotForSession,
       resolveRefTarget,
     });
-    if (!resolvedRefFillTarget.ok) return resolvedRefFillTarget.response;
+    if (!resolvedRefFillTarget.ok) return resolvedRefFillTarget;
 
     const { ref, node, snapshotNodes, point } = resolvedRefFillTarget.target;
     const nodeType = node.type ?? '';
@@ -140,28 +132,19 @@ export async function handleFillCommand(params: {
   }
 
   if (!session) {
-    return {
-      ok: false,
-      error: { code: 'SESSION_NOT_FOUND', message: 'No active session. Run open first.' },
-    };
+    return errorResponse('SESSION_NOT_FOUND', 'No active session. Run open first.');
   }
 
   const selectorArgs = splitSelectorFromArgs(req.positionals ?? [], {
     preferTrailingValue: true,
   });
   if (selectorArgs) {
     if (selectorArgs.rest.length === 0) {
-      return {
-        ok: false,
-        error: { code: 'INVALID_ARGS', message: 'fill requires text after selector' },
-      };
+      return errorResponse('INVALID_ARGS', 'fill requires text after selector');
     }
     const text = selectorArgs.rest.join(' ').trim();
     if (!text) {
-      return {
-        ok: false,
-        error: { code: 'INVALID_ARGS', message: 'fill requires text after selector' },
-      };
+      return errorResponse('INVALID_ARGS', 'fill requires text after selector');
     }
 
     const chain = parseSelectorChain(selectorArgs.selectorExpression);
@@ -184,13 +167,10 @@ export async function handleFillCommand(params: {
       { command: req.command },
     );
     if (!resolved || !resolved.node.rect) {
-      return {
-        ok: false,
-        error: {
-          code: 'COMMAND_FAILED',
-          message: formatSelectorFailure(chain, resolved?.diagnostics ?? [], { unique: true }),
-        },
-      };
+      return errorResponse(
+        'COMMAND_FAILED',
+        formatSelectorFailure(chain, resolved?.diagnostics ?? [], { unique: true }),
+      );
     }
 
     const node = resolved.node;
@@ -235,11 +215,5 @@ export async function handleFillCommand(params: {
     });
   }
 
-  return {
-    ok: false,
-    error: {
-      code: 'INVALID_ARGS',
-      message: 'fill requires x y text, @ref text, or selector text',
-    },
-  };
+  return errorResponse('INVALID_ARGS', 'fill requires x y text, @ref text, or selector text');
 }

src/daemon/handlers/interaction-fill.ts

@@ -1,5 +1,6 @@
 import type { CommandFlags } from '../../core/dispatch.ts';
 import type { DaemonResponse } from '../types.ts';
+import { errorResponse } from './response.ts';
 
 const REF_UNSUPPORTED_FLAG_MAP: ReadonlyArray<[keyof CommandFlags, string]> = [
   ['snapshotDepth', '--depth'],
@@ -13,13 +14,10 @@ export function refSnapshotFlagGuardResponse(
 ): DaemonResponse | null {
   const unsupported = unsupportedRefSnapshotFlags(flags);
   if (unsupported.length === 0) return null;
-  return {
-    ok: false,
-    error: {
-      code: 'INVALID_ARGS',
-      message: `${command} @ref does not support ${unsupported.join(', ')}.`,
-    },
-  };
+  return errorResponse(
+    'INVALID_ARGS',
+    `${command} @ref does not support ${unsupported.join(', ')}.`,
+  );
 }
 
 export type RefSnapshotFlagGuardResponse = typeof refSnapshotFlagGuardResponse;

src/daemon/handlers/interaction-flags.ts

@@ -6,28 +6,18 @@ import { refSnapshotFlagGuardResponse } from './interaction-flags.ts';
 import { readTextForNode } from './interaction-read.ts';
 import { resolveRefTarget } from './interaction-targeting.ts';
 import { resolveSelectorTarget } from './interaction-selector.ts';
+import { errorResponse } from './response.ts';
 
 export async function handleGetCommand(params: InteractionHandlerParams): Promise<DaemonResponse> {
   const { req, sessionName, sessionStore, contextFromFlags } = params;
   const sub = req.positionals?.[0];
   if (sub !== 'text' && sub !== 'attrs') {
-    return {
-      ok: false,
-      error: { code: 'INVALID_ARGS', message: 'get only supports text or attrs' },
-    };
+    return errorResponse('INVALID_ARGS', 'get only supports text or attrs');
   }
   const session = sessionStore.get(sessionName);
-  if (!session) {
-    return {
-      ok: false,
-      error: { code: 'SESSION_NOT_FOUND', message: 'No active session. Run open first.' },
-    };
-  }
+  if (!session) return errorResponse('SESSION_NOT_FOUND', 'No active session. Run open first.');
   if (!isCommandSupportedOnDevice('get', session.device)) {
-    return {
-      ok: false,
-      error: { code: 'UNSUPPORTED_OPERATION', message: 'get is not supported on this device' },
-    };
+    return errorResponse('UNSUPPORTED_OPERATION', 'get is not supported on this device');
   }
   const refInput = req.positionals?.[1] ?? '';
   if (refInput.startsWith('@')) {
@@ -43,7 +33,7 @@ export async function handleGetCommand(params: InteractionHandlerParams): Promis
       invalidRefMessage: 'get text requires a ref like @e2',
       notFoundMessage: `Ref ${refInput} not found`,
     });
-    if (!resolvedRefTarget.ok) return resolvedRefTarget.response;
+    if (!resolvedRefTarget.ok) return resolvedRefTarget;
     const { ref, node } = resolvedRefTarget.target;
     const selectorChain = buildSelectorChainForNode(node, session.device.platform, {
       action: 'get',
@@ -77,10 +67,7 @@ export async function handleGetCommand(params: InteractionHandlerParams): Promis
 
   const selectorExpression = req.positionals.slice(1).join(' ').trim();
   if (!selectorExpression) {
-    return {
-      ok: false,
-      error: { code: 'INVALID_ARGS', message: 'get requires @ref or selector expression' },
-    };
+    return errorResponse('INVALID_ARGS', 'get requires @ref or selector expression');
   }
   const resolvedSelectorTarget = await resolveSelectorTarget({
     command: req.command,
@@ -94,7 +81,7 @@ export async function handleGetCommand(params: InteractionHandlerParams): Promis
     requireUnique: true,
     disambiguateAmbiguous: sub === 'text',
   });
-  if (!resolvedSelectorTarget.ok) return resolvedSelectorTarget.response;
+  if (!resolvedSelectorTarget.ok) return resolvedSelectorTarget;
   const { resolved } = resolvedSelectorTarget;
   const node = resolved.node;
   const selectorChain = buildSelectorChainForNode(node, session.device.platform, {