refactor: standardize runtime guard patterns with lodash-es (#154)

* refactor(ui): replace runtime type guards with lodash-es predicates

* refactor(runtime): migrate typeof checks to lodash-es in core modules

* refactor(ipc): standardize runtime guards with lodash-es

* test(refactor): align runtime guard checks with lodash-es

* docs(agents): add lodash-es runtime guard skill summary

Author: Draculabo

.agents/skills/lodash-es-runtime-guards/SKILL.md

@@ -0,0 +1,74 @@
+# lodash-es-runtime-guards
+
+Replace runtime `typeof` checks and ad-hoc empty-string checks with `lodash-es` predicates.
+
+## When to Use
+
+- You see runtime checks like `typeof value === 'string'`.
+- You see object guards like `value && typeof value === 'object'`.
+- You see emptiness checks like `value.trim() !== ''` or `value.trim() === ''`.
+- You want consistent guard style across app, server, IPC, and tests.
+
+## Do Not Replace
+
+- Type-level `typeof` (TypeScript only), for example:
+  - `ReturnType<typeof fn>`
+  - `keyof typeof CONST_MAP`
+  - `z.infer<typeof Schema>`
+
+These are compile-time types and must remain as-is.
+
+## Guard Mapping
+
+- `typeof x === 'string'` -> `isString(x)`
+- `typeof x !== 'string'` -> `!isString(x)`
+- `typeof x === 'number'` -> `isNumber(x)`
+- `typeof x === 'boolean'` -> `isBoolean(x)`
+- `typeof x === 'function'` -> `isFunction(x)`
+- `typeof x === 'undefined'` -> `isUndefined(x)`
+- `x && typeof x === 'object'` -> `isObjectLike(x)`
+- `typeof x === 'object' && x !== null` -> `isObjectLike(x)`
+- `typeof x === 'object' && !Array.isArray(x)` -> `isObjectLike(x) && !isArray(x)`
+
+## String Emptiness Pattern
+
+- Prefer:
+  - `isEmpty(value.trim())`
+- Instead of:
+  - `value.trim() === ''`
+  - `value.trim() !== ''`
+  - `value.trim().length === 0`
+
+## Import Style
+
+- Use named imports from `lodash-es`:
+
+```ts
+import { isString, isNumber, isObjectLike, isEmpty } from 'lodash-es';
+```
+
+- Do not use full-package imports.
+- Reuse existing imports in file; avoid duplicate imports.
+
+## Refactor Checklist
+
+1. Replace runtime checks first, preserving behavior.
+2. Keep array/object branching semantics unchanged.
+3. Re-scan:
+
+```bash
+rg -n "typeof\s+[^\n]+(?:===|!==)\s*'" src
+```
+
+4. Confirm only type-level `typeof` remains:
+
+```bash
+rg -n "\btypeof\b" src
+```
+
+5. Run verification:
+
+```bash
+npm run type-check
+```
+

src/components/CloudAccountList.tsx

@@ -71,7 +71,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from '@/components/ui/select';
-import { filter, flatMap, isEmpty, size, sumBy } from 'lodash-es';
+import { filter, flatMap, isEmpty, isNumber, size, sumBy } from 'lodash-es';
 import {
   clampQuotaPercentage,
   getQuotaStatus,
@@ -313,7 +313,7 @@ export function CloudAccountList() {
       {
         onSuccess: (updatedAccount) => {
           const credits = updatedAccount.quota?.ai_credits?.credits;
-          if (typeof credits === 'number') {
+          if (isNumber(credits)) {
             toast({
               title: t('cloud.toast.quotaRefreshed'),
               description: `AI credits: $${credits.toFixed(2)}`,

src/components/ui/dropdown-menu.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
+import { isNumber, isObjectLike } from 'lodash-es';
 import { Check, ChevronRight, Circle } from 'lucide-react';
 import { cn } from '@/lib/utils';
 
@@ -52,11 +53,11 @@ const DropdownMenuContent = React.forwardRef<
     collisionPadding?: number | Partial<Record<'top' | 'right' | 'bottom' | 'left', number>>;
   }
 >(({ className, sideOffset = 4, collisionPadding = 8, ...props }, ref) => {
-  if (typeof collisionPadding === 'number') {
+  if (isNumber(collisionPadding)) {
     if (collisionPadding < 0) {
       throw new Error('collisionPadding must be a non-negative number');
     }
-  } else if (typeof collisionPadding === 'object' && collisionPadding !== null) {
+  } else if (isObjectLike(collisionPadding)) {
     for (const key of Object.keys(collisionPadding)) {
       if ((collisionPadding as any)[key] < 0) {
         throw new Error(`collisionPadding.${key} must be a non-negative number`);

src/ipc/cloud/handler.ts

@@ -6,6 +6,7 @@ import { logger } from '../../utils/logger';
 
 import { shell } from 'electron';
 import fs from 'fs';
+import { isEmpty, isString } from 'lodash-es';
 import { updateTrayMenu } from '../../ipc/tray/handler';
 import {
   ensureGlobalOriginalFromCurrentStorage,
@@ -46,7 +47,7 @@ function isEnterpriseClient(clientKey?: string): boolean {
 }
 
 function normalizeProjectId(projectId?: string): string | null {
-  if (typeof projectId !== 'string') {
+  if (!isString(projectId)) {
     return null;
   }
   const normalized = projectId.trim();
@@ -148,7 +149,7 @@ async function clearAccountStatus(account: CloudAccount): Promise<void> {
 
 function hydrateActiveOAuthClientFromSettings(): void {
   const preferredClientKey = CloudAccountRepo.getSetting<string>(ACTIVE_OAUTH_CLIENT_KEY_SETTING, '');
-  if (preferredClientKey && preferredClientKey.trim() !== '') {
+  if (isString(preferredClientKey) && !isEmpty(preferredClientKey.trim())) {
     try {
       GoogleAPIService.setActiveOAuthClientKey(preferredClientKey);
     } catch (error) {
@@ -195,7 +196,7 @@ async function backfillMissingOAuthClientKeyForLegacyAccounts(
     }
 
     const projectMissing =
-      typeof account.token.project_id !== 'string' || account.token.project_id.trim() === '';
+      !isString(account.token.project_id) || isEmpty(account.token.project_id.trim());
     if (activeClientKey === ENTERPRISE_OAUTH_CLIENT_KEY && projectMissing) {
       skippedEnterpriseGuardCount += 1;
       continue;
@@ -232,7 +233,7 @@ export async function addGoogleAccount(
   oauthClientKey?: string,
 ): Promise<CloudAccount> {
   try {
-    if (oauthClientKey && oauthClientKey.trim() !== '') {
+    if (isString(oauthClientKey) && !isEmpty(oauthClientKey.trim())) {
       setActiveOAuthClient(oauthClientKey);
     } else {
       hydrateActiveOAuthClientFromSettings();
@@ -684,7 +685,7 @@ export async function forcePollCloudMonitor(): Promise<void> {
 }
 
 export async function startAuthFlow(oauthClientKey?: string): Promise<void> {
-  if (oauthClientKey && oauthClientKey.trim() !== '') {
+  if (isString(oauthClientKey) && !isEmpty(oauthClientKey.trim())) {
     setActiveOAuthClient(oauthClientKey);
   } else {
     hydrateActiveOAuthClientFromSettings();

src/ipc/database/cloudHandler.ts

@@ -4,6 +4,7 @@ import fs from 'fs';
 import { v4 as uuidv4 } from 'uuid';
 import { desc, eq } from 'drizzle-orm';
 import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import { isNumber, isObjectLike, isPlainObject, isString } from 'lodash-es';
 import { getCloudAccountsDbPath, getAntigravityDbPaths } from '../../utils/paths';
 import { logger } from '../../utils/logger';
 import {
@@ -35,14 +36,14 @@ type DrizzleExecutor = Pick<
 >;
 
 function isSqliteBusyError(error: unknown): boolean {
-  if (!error || typeof error !== 'object') {
+  if (!isObjectLike(error)) {
     return false;
   }
   const err = error as { code?: string; message?: string };
   if (err.code && SQLITE_BUSY_CODES.has(err.code)) {
     return true;
   }
-  if (typeof err.message === 'string') {
+  if (isString(err.message)) {
     return err.message.includes('SQLITE_BUSY') || err.message.includes('SQLITE_LOCKED');
   }
   return false;
@@ -168,32 +169,29 @@ interface MigrationStats {
   failedFields: number;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
-
 function readStringCandidate(
   source: Record<string, unknown>,
   ...keys: string[]
 ): string | undefined {
   for (const key of keys) {
     const candidate = source[key];
-    if (typeof candidate === 'string' && candidate.length > 0) {
+    if (isString(candidate) && candidate.length > 0) {
       return candidate;
     }
   }
   return undefined;
 }
 
 function normalizeDeviceProfile(value: unknown): DeviceProfile | undefined {
-  if (!isRecord(value)) {
+  if (!isPlainObject(value)) {
     return undefined;
   }
+  const valueRecord = value as Record<string, unknown>;
 
-  const machineId = readStringCandidate(value, 'machineId', 'machine_id');
-  const macMachineId = readStringCandidate(value, 'macMachineId', 'mac_machine_id');
-  const devDeviceId = readStringCandidate(value, 'devDeviceId', 'dev_device_id');
-  const sqmId = readStringCandidate(value, 'sqmId', 'sqm_id');
+  const machineId = readStringCandidate(valueRecord, 'machineId', 'machine_id');
+  const macMachineId = readStringCandidate(valueRecord, 'macMachineId', 'mac_machine_id');
+  const devDeviceId = readStringCandidate(valueRecord, 'devDeviceId', 'dev_device_id');
+  const sqmId = readStringCandidate(valueRecord, 'sqmId', 'sqm_id');
 
   if (!machineId || !macMachineId || !devDeviceId || !sqmId) {
     return undefined;
@@ -217,45 +215,47 @@ function areDeviceProfilesEqual(left: DeviceProfile, right: DeviceProfile): bool
 }
 
 function readVersionedProfilePayload(value: unknown): unknown {
-  if (!isRecord(value)) {
+  if (!isPlainObject(value)) {
     return value;
   }
-  if (!('schemaVersion' in value)) {
+  const valueRecord = value as Record<string, unknown>;
+  if (!('schemaVersion' in valueRecord)) {
     return value;
   }
 
-  const schemaVersion = value.schemaVersion;
-  if (typeof schemaVersion !== 'number' || !Number.isFinite(schemaVersion)) {
+  const schemaVersion = valueRecord.schemaVersion;
+  if (!isNumber(schemaVersion) || !Number.isFinite(schemaVersion)) {
     throw new Error('invalid_device_profile_schema_version');
   }
   if (schemaVersion !== DEVICE_PAYLOAD_SCHEMA_VERSION) {
     throw new Error(`unsupported_device_profile_schema_version:${schemaVersion}`);
   }
-  if (!('profile' in value)) {
+  if (!('profile' in valueRecord)) {
     throw new Error('invalid_device_profile_payload');
   }
-  return value.profile;
+  return valueRecord.profile;
 }
 
 function readVersionedHistoryPayload(value: unknown): unknown {
-  if (!isRecord(value)) {
+  if (!isPlainObject(value)) {
     return value;
   }
-  if (!('schemaVersion' in value)) {
+  const valueRecord = value as Record<string, unknown>;
+  if (!('schemaVersion' in valueRecord)) {
     return value;
   }
 
-  const schemaVersion = value.schemaVersion;
-  if (typeof schemaVersion !== 'number' || !Number.isFinite(schemaVersion)) {
+  const schemaVersion = valueRecord.schemaVersion;
+  if (!isNumber(schemaVersion) || !Number.isFinite(schemaVersion)) {
     throw new Error('invalid_device_history_schema_version');
   }
   if (schemaVersion !== DEVICE_PAYLOAD_SCHEMA_VERSION) {
     throw new Error(`unsupported_device_history_schema_version:${schemaVersion}`);
   }
-  if (!('history' in value)) {
+  if (!('history' in valueRecord)) {
     throw new Error('invalid_device_history_payload');
   }
-  return value.history;
+  return valueRecord.history;
 }
 
 function serializeDeviceProfile(profile: DeviceProfile | undefined): string | null {
@@ -285,23 +285,25 @@ function normalizeDeviceHistory(value: unknown): DeviceProfileVersion[] | undefi
 
   const normalized: DeviceProfileVersion[] = [];
   for (const item of value) {
-    if (!isRecord(item)) {
+    if (!isPlainObject(item)) {
       continue;
     }
+    const itemRecord = item as Record<string, unknown>;
 
-    const profile = normalizeDeviceProfile(item.profile);
+    const profile = normalizeDeviceProfile(itemRecord.profile);
     if (!profile) {
       continue;
     }
 
-    const id = typeof item.id === 'string' && item.id.length > 0 ? item.id : uuidv4();
-    const createdAtCandidate = item.createdAt;
+    const id = isString(itemRecord.id) && itemRecord.id.length > 0 ? itemRecord.id : uuidv4();
+    const createdAtCandidate = itemRecord.createdAt;
     const createdAt =
-      typeof createdAtCandidate === 'number' && Number.isFinite(createdAtCandidate)
+      isNumber(createdAtCandidate) && Number.isFinite(createdAtCandidate)
         ? Math.floor(createdAtCandidate)
         : Math.floor(Date.now() / 1000);
-    const label = typeof item.label === 'string' && item.label.length > 0 ? item.label : 'legacy';
-    const isCurrent = item.isCurrent === true;
+    const label =
+      isString(itemRecord.label) && itemRecord.label.length > 0 ? itemRecord.label : 'legacy';
+    const isCurrent = itemRecord.isCurrent === true;
 
     normalized.push({
       id,

src/ipc/database/handler.ts

@@ -2,6 +2,7 @@ import Database from 'better-sqlite3';
 import fs from 'fs';
 import path from 'path';
 import { eq } from 'drizzle-orm';
+import { isString } from 'lodash-es';
 import { AccountBackupData, AccountInfo } from '../../types/account';
 import { ItemTableValueRowSchema, type ItemTableKey } from '../../types/db';
 import { logger } from '../../utils/logger';
@@ -192,8 +193,8 @@ export function getCurrentAccountInfo(): AccountInfo {
     // Helper to find email in object
     const findEmail = (obj: { email?: string; user?: { email?: string } }): string => {
       if (!obj) return '';
-      if (typeof obj.email === 'string') return obj.email;
-      if (obj.user && typeof obj.user.email === 'string') return obj.user.email;
+      if (isString(obj.email)) return obj.email;
+      if (obj.user && isString(obj.user.email)) return obj.user.email;
       return '';
     };
 
@@ -323,7 +324,7 @@ function _restoreSingleDb(dbPath: string, backup: AccountBackupData): boolean {
       for (const key of KEYS_TO_BACKUP) {
         if (key in backup.data) {
           const value = backup.data[key];
-          const stringValue = typeof value === 'string' ? value : JSON.stringify(value);
+          const stringValue = isString(value) ? value : JSON.stringify(value);
           tx.insert(itemTable)
             .values({ key, value: stringValue })
             .onConflictDoUpdate({