feat: export error contract helpers

Author: thymikee

src/__tests__/contracts-schema-public.test.ts

@@ -1,17 +1,24 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { AppError } from '../index.ts';
 import {
+  defaultHintForCode,
   daemonCommandRequestSchema,
   daemonRuntimeSchema,
   centerOfRect,
   jsonRpcRequestSchema,
   leaseAllocateSchema,
   leaseHeartbeatSchema,
   leaseReleaseSchema,
+  normalizeError,
+  type AppErrorCode,
   type Rect,
   type SnapshotNode,
 } from '../contracts.ts';
 
+const invalidArgsCode = 'INVALID_ARGS' satisfies AppErrorCode;
 const rect = { x: 1, y: 2, width: 3, height: 4 } satisfies Rect;
 const node = {
   index: 0,
@@ -21,6 +28,15 @@ const node = {
   rect,
 } satisfies SnapshotNode;
 
+test('public contracts entrypoint does not import Node-only error module', () => {
+  const contractsSource = fs.readFileSync(
+    path.join(import.meta.dirname, '..', 'contracts.ts'),
+    'utf8',
+  );
+
+  assert.doesNotMatch(contractsSource, /['"]\.\/utils\/errors\.ts['"]/);
+});
+
 test('public contract schemas validate daemon requests and lease payloads', () => {
   const runtime = daemonRuntimeSchema.parse({
     platform: 'ios',
@@ -70,6 +86,17 @@ test('public contract schemas validate daemon requests and lease payloads', () =
   assert.equal(node.ref, 'e1');
 });
 
+test('public contract exports normalize and hint app errors', () => {
+  const normalized = normalizeError(new AppError(invalidArgsCode, 'Invalid command'));
+
+  assert.equal(normalized.code, invalidArgsCode);
+  assert.equal(normalized.hint, defaultHintForCode(invalidArgsCode));
+  assert.equal(
+    defaultHintForCode('UNKNOWN'),
+    'Retry with --debug and inspect diagnostics log for details.',
+  );
+});
+
 test('public contract schemas reject invalid payloads', () => {
   assert.throws(
     () =>

src/contracts.ts

@@ -1,3 +1,6 @@
+export type { AppErrorCode } from './utils/error-contract.ts';
+export { defaultHintForCode, normalizeError } from './utils/error-contract.ts';
+
 export type SessionRuntimeHints = {
   platform?: 'ios' | 'android';
   metroHost?: string;

src/utils/diagnostics.ts

@@ -3,6 +3,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { redactDiagnosticData } from './redaction.ts';
 
 type DiagnosticLevel = 'info' | 'warn' | 'error' | 'debug';
 
@@ -33,11 +34,6 @@ type DiagnosticsScope = DiagnosticsScopeOptions & {
 
 const diagnosticsStorage = new AsyncLocalStorage<DiagnosticsScope>();
 
-const SENSITIVE_KEY_RE =
-  /(token|secret|password|authorization|cookie|api[_-]?key|access[_-]?key|private[_-]?key)/i;
-const SENSITIVE_VALUE_RE =
-  /(bearer\s+[a-z0-9._-]+|(?:api[_-]?key|token|secret|password)\s*[=:]\s*\S+)/i;
-
 export function createRequestId(): string {
   return crypto.randomBytes(8).toString('hex');
 }
@@ -161,58 +157,6 @@ export function flushDiagnosticsToSessionFile(options: { force?: boolean } = {})
   }
 }
 
-export function redactDiagnosticData<T>(input: T): T {
-  return redactValue(input, new WeakSet<object>()) as T;
-}
-
-function redactValue(value: unknown, seen: WeakSet<object>, keyHint?: string): unknown {
-  if (value === null || value === undefined) return value;
-  if (typeof value === 'string') return redactString(value, keyHint);
-  if (typeof value !== 'object') return value;
-
-  if (seen.has(value as object)) return '[Circular]';
-  seen.add(value as object);
-
-  if (Array.isArray(value)) {
-    return value.map((entry) => redactValue(entry, seen));
-  }
-
-  const output: Record<string, unknown> = {};
-  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
-    if (SENSITIVE_KEY_RE.test(key)) {
-      output[key] = '[REDACTED]';
-      continue;
-    }
-    output[key] = redactValue(entry, seen, key);
-  }
-  return output;
-}
-
-function redactString(value: string, keyHint?: string): string {
-  const trimmed = value.trim();
-  if (!trimmed) return value;
-  if (keyHint && SENSITIVE_KEY_RE.test(keyHint)) return '[REDACTED]';
-  if (SENSITIVE_VALUE_RE.test(trimmed)) return '[REDACTED]';
-  const maskedUrl = redactUrl(trimmed);
-  if (maskedUrl) return maskedUrl;
-  if (trimmed.length > 400) return `${trimmed.slice(0, 200)}...<truncated>`;
-  return trimmed;
-}
-
-function redactUrl(value: string): string | null {
-  try {
-    const parsed = new URL(value);
-    if (parsed.search) parsed.search = '?REDACTED';
-    if (parsed.username || parsed.password) {
-      parsed.username = 'REDACTED';
-      parsed.password = 'REDACTED';
-    }
-    return parsed.toString();
-  } catch {
-    return null;
-  }
-}
-
 function sanitizePathPart(value: string): string {
   return value.replace(/[^a-zA-Z0-9._-]/g, '_');
 }

src/utils/error-contract.ts

@@ -0,0 +1,139 @@
+import { redactDiagnosticData } from './redaction.ts';
+
+export type AppErrorCode =
+  | 'INVALID_ARGS'
+  | 'DEVICE_NOT_FOUND'
+  | 'TOOL_MISSING'
+  | 'APP_NOT_INSTALLED'
+  | 'UNSUPPORTED_PLATFORM'
+  | 'UNSUPPORTED_OPERATION'
+  | 'COMMAND_FAILED'
+  | 'SESSION_NOT_FOUND'
+  | 'UNAUTHORIZED'
+  | 'UNKNOWN';
+
+type AppErrorDetails = Record<string, unknown> & {
+  hint?: string;
+  diagnosticId?: string;
+  logPath?: string;
+};
+
+export type NormalizedError = {
+  code: string;
+  message: string;
+  hint?: string;
+  diagnosticId?: string;
+  logPath?: string;
+  details?: Record<string, unknown>;
+};
+
+export class AppError extends Error {
+  code: AppErrorCode;
+  details?: AppErrorDetails;
+  cause?: unknown;
+
+  constructor(code: AppErrorCode, message: string, details?: AppErrorDetails, cause?: unknown) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.cause = cause;
+  }
+}
+
+export function asAppError(err: unknown): AppError {
+  if (err instanceof AppError) return err;
+  if (err instanceof Error) {
+    return new AppError('UNKNOWN', err.message, undefined, err);
+  }
+  return new AppError('UNKNOWN', 'Unknown error', { err });
+}
+
+export function normalizeError(
+  err: unknown,
+  context: { diagnosticId?: string; logPath?: string } = {},
+): NormalizedError {
+  const appErr = asAppError(err);
+  const details = appErr.details ? redactDiagnosticData(appErr.details) : undefined;
+  const detailHint = details && typeof details.hint === 'string' ? details.hint : undefined;
+  const diagnosticId =
+    (details && typeof details.diagnosticId === 'string' ? details.diagnosticId : undefined) ??
+    context.diagnosticId;
+  const logPath =
+    (details && typeof details.logPath === 'string' ? details.logPath : undefined) ??
+    context.logPath;
+  const hint = detailHint ?? defaultHintForCode(appErr.code);
+  const cleanDetails = stripDiagnosticMeta(details);
+  const message = maybeEnrichCommandFailedMessage(appErr.code, appErr.message, details);
+
+  return {
+    code: appErr.code,
+    message,
+    hint,
+    diagnosticId,
+    logPath,
+    details: cleanDetails,
+  };
+}
+
+function maybeEnrichCommandFailedMessage(
+  code: string,
+  message: string,
+  details: Record<string, unknown> | undefined,
+): string {
+  if (code !== 'COMMAND_FAILED') return message;
+  if (details?.processExitError !== true) return message;
+  const stderr = typeof details?.stderr === 'string' ? details.stderr : '';
+  const excerpt = firstStderrLine(stderr);
+  if (!excerpt) return message;
+  return excerpt;
+}
+
+function firstStderrLine(stderr: string): string | null {
+  const skipPatterns = [
+    /^an error was encountered processing the command/i,
+    /^underlying error\b/i,
+    /^simulator device failed to complete the requested operation/i,
+  ];
+
+  for (const rawLine of stderr.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (skipPatterns.some((pattern) => pattern.test(line))) continue;
+    return line.length > 200 ? `${line.slice(0, 200)}...` : line;
+  }
+  return null;
+}
+
+function stripDiagnosticMeta(
+  details: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (!details) return undefined;
+  const output = { ...details };
+  delete output.hint;
+  delete output.diagnosticId;
+  delete output.logPath;
+  return Object.keys(output).length > 0 ? output : undefined;
+}
+
+export function defaultHintForCode(code: string): string | undefined {
+  switch (code) {
+    case 'INVALID_ARGS':
+      return 'Check command arguments and run --help for usage examples.';
+    case 'SESSION_NOT_FOUND':
+      return 'Run open first or pass an explicit device selector.';
+    case 'TOOL_MISSING':
+      return 'Install required platform tooling and ensure it is available in PATH.';
+    case 'DEVICE_NOT_FOUND':
+      return 'Verify the target device is booted/connected and selectors match.';
+    case 'APP_NOT_INSTALLED':
+      return 'Run apps to discover the exact installed package or bundle id, or install the app before open.';
+    case 'UNSUPPORTED_OPERATION':
+      return 'This command is not available for the selected platform/device.';
+    case 'COMMAND_FAILED':
+      return 'Retry with --debug and inspect diagnostics log for details.';
+    case 'UNAUTHORIZED':
+      return 'Refresh daemon metadata and retry the command.';
+    default:
+      return 'Retry with --debug and inspect diagnostics log for details.';
+  }
+}