# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

HarmonyOS (鸿蒙) crash diagnostics demo app — `com.example.crashdiagnosticsdemo`. Targets HarmonyOS 6.1.0 (API 23), Stage Mode, phone devices only. Uses the Hvigor build system with DevEco Studio as the IDE.

## Build & Development Commands

This is a HarmonyOS project; use the **deveco-cli skill** for all build, run, and device operations.

- **Build (debug)**: `devecocli build` or via DevEco Studio
- **Run on device/emulator**: DevEco Studio → Run, or `devecocli run`
- **Lint ArkTS**: `code-linter` is configured via `code-linter.json5` (triggers on `.ets` files, enforces security rules like `@security/no-unsafe-aes`, `@security/no-unsafe-hash`, etc.)
- **CLI docs lookup**: use the `deveco-cli` skill to fetch HarmonyOS API docs and samples

### Testing

The project includes `@ohos/hypium` (test framework) and `@ohos/hamock` (mocking) as dev dependencies. Test targets are configured in `entry/build-profile.json5` under the `ohosTest` target.

## Architecture

### Entry Point & Page Routing

```
EntryAbility (entryability/EntryAbility.ets)
  └── loads pages/Index (main page)
        └── navigates to pages/CrashHistory (push route)
```

- `EntryAbility` initializes `CrashDiagnostics` on `onCreate`, sets color mode, and loads `pages/Index` on `onWindowStageCreate`.
- Page routes are declared in `entry/src/main/resources/base/profile/main_pages.json`.

### Core Diagnostic Layer — `CrashDiagnostics` (diagnostics/CrashDiagnostics.ets)

A **static utility class** (never instantiated) that is the backbone of the app. Key responsibilities:

1. **HiAppEvent subscription**: Registers an `hiAppEvent.Watcher` named `debugCrashWatcher` that listens for system `APP_CRASH` fault events. The watcher is created in `initialize()` — because it reuses the same name, it picks up un-consumed crash events from a previous process exit on the next launch.

2. **Persistent crash records**: Stores up to 10 crash record strings in `preferences` (key: `recent_hiappevent_crash_records`). New records are prepended; duplicates are filtered out.

3. **Dismiss-until-new-crash pattern**: Tracks which crash the user dismissed (key: `dismissed_hiappevent_crash_id`). `shouldShowLastCrashDialog()` returns `true` only when the current latest crash differs from the dismissed one.

4. **Listener callback**: `recordsUpdatedListener` — a single callback set by the active UI page; fires when cached records change.

5. **Caught error logging**: `recordCaughtError()` logs to hilog only — it does NOT mix caught exceptions into the APP_CRASH history. The history exclusively contains system-generated crash events.

### Pages

- **`pages/Index`** — Main debug screen. Displays crash record count/status, buttons to simulate a caught error (logged only) and a native CPP crash (via NAPI, kills the app), and a button to view crash history. On `aboutToAppear`, sets itself as the `recordsUpdatedListener` and optionally shows an alert dialog for the last un-dismissed crash.

- **`pages/CrashHistory`** — Lists crash records from `CrashDiagnostics.getRecentRecords()`, with detail view, clear-all, and export-to-ZIP (JSON inside ZIP, saved via `DocumentViewPicker`).

### Native Layer (NAPI)

```
entry/src/main/cpp/napi_init.cpp  →  libentry.so
entry/src/main/cpp/types/libentry/index.d.ts  →  ArkTS type declarations
```

Exports a single function `simulateCppCrash()` that calls `std::abort()`. Used by `pages/Index` to demonstrate a native crash that gets picked up by HiAppEvent on the next launch. Built via CMake (`CMakeLists.txt`) targeting `arm64-v8a` only, linked against `libace_napi.z.so`.

### Key Data Flow

```
App crashes (native/JS)
  → HarmonyOS writes APP_CRASH event to HiAppEvent
  → Next app launch: EntryAbility.onCreate → CrashDiagnostics.initialize()
    → hiAppEvent.addWatcher("debugCrashWatcher") picks up events
    → collectFromHolder() formats and caches records to preferences
    → recordsUpdatedListener fires → Index page updates UI
    → Optionally shows AlertDialog for un-dismissed crash
```

## Important Constraints

- **ArkTS is NOT TypeScript**: ArkTS is a strict subset of TypeScript with its own compiler rules. Use the `arkts-grammar-standards` skill before writing `.ets` files. Key differences: no `any`/`unknown` types in certain contexts, restricted structural typing for `@Component` structs, specific decorator rules (`@State`, `@Entry`, `@Component`).
- **Target ABI is arm64-v8a only** (no x86_64 emulator support in the build config).
- **Obfuscation is disabled** even in release mode (`entry/build-profile.json5`).
- **Strict mode enabled**: `caseSensitiveCheck: true`, `useNormalizedOHMUrl: true`.