feat: export error contract helpers

Author: thymikee

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

@@ -1,14 +1,20 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
+import { AppError } from '../index.ts';
 import {
+  defaultHintForCode,
   daemonCommandRequestSchema,
   daemonRuntimeSchema,
   jsonRpcRequestSchema,
   leaseAllocateSchema,
   leaseHeartbeatSchema,
   leaseReleaseSchema,
+  normalizeError,
+  type AppErrorCode,
 } from '../contracts.ts';
 
+const invalidArgsCode = 'INVALID_ARGS' satisfies AppErrorCode;
+
 test('public contract schemas validate daemon requests and lease payloads', () => {
   const runtime = daemonRuntimeSchema.parse({
     platform: 'ios',
@@ -56,6 +62,17 @@ test('public contract schemas validate daemon requests and lease payloads', () =
   assert.equal(release.leaseId, 'lease-1');
 });
 
+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/errors.ts';
+export { defaultHintForCode, normalizeError } from './utils/errors.ts';
+
 export type SessionRuntimeHints = {
   platform?: 'ios' | 'android';
   metroHost?: string;

src/utils/errors.ts

@@ -1,6 +1,6 @@
 import { redactDiagnosticData } from './diagnostics.ts';
 
-type ErrorCode =
+export type AppErrorCode =
   | 'INVALID_ARGS'
   | 'DEVICE_NOT_FOUND'
   | 'TOOL_MISSING'
@@ -28,11 +28,11 @@ export type NormalizedError = {
 };
 
 export class AppError extends Error {
-  code: ErrorCode;
+  code: AppErrorCode;
   details?: AppErrorDetails;
   cause?: unknown;
 
-  constructor(code: ErrorCode, message: string, details?: AppErrorDetails, cause?: unknown) {
+  constructor(code: AppErrorCode, message: string, details?: AppErrorDetails, cause?: unknown) {
     super(message);
     this.code = code;
     this.details = details;
@@ -115,7 +115,7 @@ function stripDiagnosticMeta(
   return Object.keys(output).length > 0 ? output : undefined;
 }
 
-function defaultHintForCode(code: string): string | undefined {
+export function defaultHintForCode(code: string): string | undefined {
   switch (code) {
     case 'INVALID_ARGS':
       return 'Check command arguments and run --help for usage examples.';