chain-studio/lib/data/friendly_error.dart

// Friendly-error mapper. Turns a thrown object (typically a
// `GrpcError` from package:grpc) into a short human sentence
// plus an optional recovery hint, ready to drop into the UI.
//
// Why this exists: Studio used to render `GrpcError.toString()`
// verbatim — operators saw walls of text like
// "gRPC Error (code: 13, codeName: INTERNAL, message: ..., details: [], rawResponse: null, trailers: {...})".
// The friendly mapper folds every gRPC code into a one-line
// explanation we can localise, plus a recovery action when one
// is obvious (open settings, restart hub, retry).

import '../l10n/app_localizations.dart';

/// Result of running an error through [friendlyError]. The
/// `headline` is the short user-facing sentence; `detail` is
/// the verbatim original error string (kept around in case the
/// operator wants to copy-paste it into a bug report). `hint`
/// is a one-sentence recovery suggestion or `null`.
class FriendlyError {
  final String headline;
  final String detail;
  final String? hint;

  const FriendlyError({
    required this.headline,
    required this.detail,
    this.hint,
  });

  // The on-disk error log serialises thrown objects via toString —
  // keep the whole story (headline, hint, verbatim detail) in one
  // readable record.
  @override
  String toString() => [
    headline,
    ?hint,
    if (detail.isNotEmpty && detail != headline) detail,
  ].join('\n');
}

/// Map an arbitrary thrown object to a [FriendlyError]. Always
/// returns a value — never throws — so callers can drop the
/// result straight into UI without try/catch ceremony.
FriendlyError friendlyError(Object error, AppLocalizations l) {
  // A pre-built FriendlyError passes through unchanged — call
  // sites that already know the precise story (e.g. the setup
  // wizard's CLI-version-skew case) construct one directly and
  // still route through the shared presentation helpers.
  if (error is FriendlyError) return error;
  // We deliberately don't import package:grpc here so Studio
  // doesn't have to add it to its own pubspec — the dependency
  // lives one layer down in chain_client_sdk. `GrpcError` has a
  // stable `.code` (int) and `.message` (String?) shape; we
  // duck-type on those instead of an `is` check.
  final code = _intField(error, 'code');
  final detail = _stringField(error, 'message') ?? '';
  // Hub-specific pattern detection — runs BEFORE the gRPC-code
  // switch so a precise hit ("approval rejected by ...") wins
  // over the generic "permission denied" label even though
  // both correspond to gRPC PERMISSION_DENIED.
  final specific = _matchHubPattern(detail, l);
  if (specific != null) return specific;
  if (code != null) {
    switch (code) {
      case 3: // INVALID_ARGUMENT
        return FriendlyError(
          headline: l.errInvalidArgument,
          detail: detail,
          hint: l.errInvalidArgumentHint,
        );
      case 5: // NOT_FOUND
        return FriendlyError(
          headline: l.errNotFound,
          detail: detail,
          hint: l.errNotFoundHint,
        );
      case 6: // ALREADY_EXISTS
        return FriendlyError(
          headline: l.errAlreadyExists,
          detail: detail,
          hint: null,
        );
      case 7: // PERMISSION_DENIED
        return FriendlyError(
          headline: l.errPermissionDenied,
          detail: detail,
          hint: l.errPermissionDeniedHint,
        );
      case 9: // FAILED_PRECONDITION
        return FriendlyError(
          headline: l.errFailedPrecondition,
          detail: detail,
          hint: l.errFailedPreconditionHint,
        );
      case 13: // INTERNAL
        return FriendlyError(
          headline: l.errInternal,
          detail: detail,
          hint: l.errInternalHint,
        );
      case 14: // UNAVAILABLE
        return FriendlyError(
          headline: l.errUnavailable,
          detail: detail,
          hint: l.errUnavailableHint,
        );
      case 16: // UNAUTHENTICATED
        return FriendlyError(
          headline: l.errUnauthenticated,
          detail: detail,
          hint: l.errUnauthenticatedHint,
        );
      default:
        final codeName = _stringField(error, 'codeName') ?? 'gRPC $code';
        return FriendlyError(
          headline: '$codeName: ${detail.isEmpty ? l.errGeneric : detail}',
          detail: detail,
          hint: null,
        );
    }
  }
  // Non-gRPC error (e.g. FormatException from a bad URL). Show
  // its toString — but as the headline, not buried in a wall.
  return FriendlyError(
    headline: error.toString(),
    detail: error.toString(),
    hint: null,
  );
}

/// Pattern-match the gRPC error message for hub-specific
/// failure shapes. The hub's [FlowExecutionError] uses
/// well-shaped Display formats (e.g.
/// `step 'ap1' rejected by alice: ...`) — we read the prefix
/// to return a more specific [FriendlyError] than the
/// gRPC-code default. Returns null when nothing matches.
FriendlyError? _matchHubPattern(String detail, AppLocalizations l) {
  if (detail.isEmpty) return null;

  // Module bundle download failed (bad / unhosted URL). The hub wraps
  // these as "download failed: ..." and (older builds) mapped them to
  // gRPC Unavailable — which the code-default would render as the
  // misleading "hub not reachable". The hub is fine; show the real URL
  // + status (carried in `detail`) under a clear headline.
  if (detail.contains('download failed') || detail.contains('download error')) {
    return FriendlyError(
      headline: l.errModuleDownload,
      detail: detail,
      hint: l.errModuleDownloadHint,
    );
  }

  // Approval rejected: "step 'X' rejected by Y: reason"
  if (detail.contains('rejected by')) {
    return FriendlyError(
      headline: l.errApprovalRejected,
      detail: detail,
      hint: l.errApprovalRejectedHint,
    );
  }
  // Approval timeout: "step 'X' timed out waiting for approval after Ns"
  if (detail.contains('timed out waiting for approval')) {
    return FriendlyError(
      headline: l.errApprovalTimedOut,
      detail: detail,
      hint: l.errApprovalTimedOutHint,
    );
  }
  // Output too large: "step 'X' produced N bytes of output, exceeding the M MB cap"
  if (detail.contains('exceeding the') &&
      detail.contains('MB cap')) {
    return FriendlyError(
      headline: l.errOutputTooLarge,
      detail: detail,
      hint: l.errOutputTooLargeHint,
    );
  }
  // Host service unavailable: "step 'X' requires service 'Y' which is not declared"
  if (detail.contains('requires service') &&
      detail.contains('not declared')) {
    return FriendlyError(
      headline: l.errServiceUnavailableForStep,
      detail: detail,
      hint: l.errServiceUnavailableForStepHint,
    );
  }
  // Missing value: "step 'X' references missing value 'Y'"
  if (detail.contains('references missing value')) {
    return FriendlyError(
      headline: l.errMissingValue,
      detail: detail,
      hint: l.errMissingValueHint,
    );
  }
  // MCP server unreachable — hub surfaces these as Unavailable
  // with the MCP transport name in the message.
  if (detail.toLowerCase().contains('mcp') &&
      (detail.contains('unreachable') ||
          detail.contains('connection refused') ||
          detail.contains('timed out'))) {
    return FriendlyError(
      headline: l.errMcpUnreachable,
      detail: detail,
      hint: l.errMcpUnreachableHint,
    );
  }
  // Install target unresolvable — the hub's install resolver found
  // no store entry with that exact name ("no store entry for 'X' —
  // hint"). Distinct from capability-not-installed below: the store
  // cannot deliver it at all, so the recovery is one of the three
  // acquisition paths, not the Fix button. Reachable despite the
  // honest badge (stale store snapshot, race with a store refresh,
  // older hub).
  if (detail.contains('no store entry for')) {
    return FriendlyError(
      headline: l.errNoStoreEntry,
      detail: detail,
      hint: l.errNoStoreEntryHint,
    );
  }
  // Capability not in registry — hub returns NotFound with this
  // shape from the flow engine.
  if (detail.toLowerCase().contains('no capability provider') ||
      detail.toLowerCase().contains('capability not installed')) {
    return FriendlyError(
      headline: l.errCapabilityNotInstalled,
      detail: detail,
      hint: l.errCapabilityNotInstalledHint,
    );
  }
  return null;
}

/// How a page-level load failure should be presented. Every page
/// that fetches its content from the hub used to fold ANY failure
/// into "hub not reachable", which contradicted the sidebar's
/// green connected dot whenever the hub answered but the RPC
/// failed (version skew, feature gates, real bugs). The shared
/// classification keeps "not reachable" reserved for genuine
/// connection failures.
enum HubLoadIssue {
  /// Socket-level failure or gRPC UNAVAILABLE / DEADLINE_EXCEEDED:
  /// the hub itself cannot be reached.
  unreachable,

  /// gRPC UNIMPLEMENTED: the hub answered, but its version
  /// predates the RPC this view needs — connected, just too old.
  unsupported,

  /// Anything else — show the friendly error with copyable detail.
  other,
}

/// Classify a page-load failure (see [HubLoadIssue]).
HubLoadIssue classifyHubLoadError(Object error) {
  switch (grpcCodeOf(error)) {
    case 12: // UNIMPLEMENTED
      return HubLoadIssue.unsupported;
    case 4: // DEADLINE_EXCEEDED
    case 14: // UNAVAILABLE
      return HubLoadIssue.unreachable;
  }
  // Non-gRPC failures: only clear socket-level shapes count as
  // "unreachable"; everything else keeps its real story.
  final s = error.toString().toLowerCase();
  if (s.contains('socketexception') ||
      s.contains('connection refused') ||
      s.contains('connection terminated') ||
      s.contains('failed to connect')) {
    return HubLoadIssue.unreachable;
  }
  return HubLoadIssue.other;
}

/// Duck-typed `GrpcError.code` reader — public so pages that
/// classify errors themselves (e.g. the runs monitor separating
/// "hub down" from "hub too old") share one accessor instead of
/// re-implementing the duck-typing.
int? grpcCodeOf(Object error) => _intField(error, 'code');

/// Duck-typed `GrpcError.message` reader — companion to
/// [grpcCodeOf].
String? grpcMessageOf(Object error) => _stringField(error, 'message');

/// Try to read an `int` field by name off an arbitrary object.
/// Returns `null` when the field doesn't exist or has another
/// runtime type. Used to duck-type `GrpcError.code` without
/// pulling package:grpc as a Studio dependency.
int? _intField(Object obj, String field) {
  try {
    final dyn = obj as dynamic;
    // ignore: avoid_dynamic_calls
    final v = (() {
      switch (field) {
        case 'code':
          return dyn.code;
      }
      return null;
    })();
    return v is int ? v : null;
  } catch (_) {
    return null;
  }
}

String? _stringField(Object obj, String field) {
  try {
    final dyn = obj as dynamic;
    // ignore: avoid_dynamic_calls
    final v = (() {
      switch (field) {
        case 'message':
          return dyn.message;
        case 'codeName':
          return dyn.codeName;
      }
      return null;
    })();
    return v is String ? v : null;
  } catch (_) {
    return null;
  }
}