npm package: @idoa/dev-doctor-zeta
Description: ZetaChain-focused developer diagnostics and Universal App preflight toolkit
Latest version: 0.1.0

# Zeta Dev Doctor

Zeta Dev Doctor is a ZetaChain-native diagnostics CLI PoC for Universal App workflows.

Package: `@idoa/dev-doctor-zeta`  
Binary: `zeta-doctor`

## What It Does

The CLI focuses on the first debugging steps for ZetaChain development:

- checks local environment readiness
- validates ZetaChain config
- probes ZetaChain RPC and API reachability
- performs static Gateway preflight checks
- provides a minimal CCTX lookup flow
- emits AI-ready JSON for LLM-assisted debugging

## Included in This PoC

- `doctor`
  Full preflight run.
- `doctor env`
  Node.js, package manager, and optional ZetaChain CLI checks.
- `doctor preflight`
  Environment, config, endpoint, and Gateway checks.
- `doctor cctx --hash <txHash>`
  Minimal CCTX lookup and interpretation.
- `doctor json`
  JSON output mode for the full preflight run.

## Out of Scope

- full explorer functionality
- wallet-backed transaction submission
- real cross-chain writes
- full Gateway execution
- exhaustive CCTX lifecycle decoding

## Install

Global install:

```bash
npm i -g @idoa/dev-doctor-zeta
```

Then run:

```bash
zeta-doctor doctor
```

Without global install:

```bash
npx @idoa/dev-doctor-zeta doctor
npx @idoa/dev-doctor-zeta doctor env
```

## Usage

After installation, the published package exposes the `zeta-doctor` binary.

```bash
zeta-doctor doctor
zeta-doctor doctor env
zeta-doctor doctor preflight
zeta-doctor doctor cctx --hash 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
zeta-doctor doctor json
```

Optional flags:

```bash
zeta-doctor doctor preflight --config zeta-doctor.config.json
zeta-doctor doctor preflight --json
```

## Config

The CLI looks for `zeta-doctor.config.json` by default.

Start from `zeta-doctor.config.example.json` in this repo/package and copy it to `zeta-doctor.config.json`.

Example:

```json
{
  "network": "athens3",
  "zetaRpcUrl": "https://zetachain-athens-evm.blockpi.network/v1/rpc/public",
  "zetaApiUrl": "https://zetachain-athens.blockpi.network/lcd",
  "connectedChain": "base-sepolia",
  "explorerBaseUrl": "https://athens.explorer.zetachain.com",
  "gatewayAddress": "0x1111111111111111111111111111111111111111",
  "requestTimeoutMs": 5000
}
```

Required fields:

- `network`
- `zetaRpcUrl`
- `zetaApiUrl`
- `connectedChain`
- `explorerBaseUrl`

Optional fields:

- `gatewayAddress`
- `requestTimeoutMs`

## Example Output

Human output:

```text
Zeta Dev Doctor (2026-03-22T12:00:00.000Z)
Status: DEGRADED | Score: 84/100
Checks: 7 | Pass: 5 | Warn: 2 | Fail: 0 | Skip: 0

Target: athens3 -> base-sepolia

[PASS] Node.js runtime
  Root cause: runtime_ready
  Node.js 20.18.0 satisfies the minimum 20.0.0 requirement.
[PASS] ZetaChain API reachability
  Root cause: api_reachable
  API responded in 172ms with HTTP 200.
[WARN] Gateway config preflight
  Root cause: gateway_address_missing
  No gatewayAddress was configured. Core preflight can still run, but gateway-specific validation is limited.
  Next step: Add gatewayAddress if your Universal App depends on Gateway-based deposits or calls.
```

JSON output:

```json
{
  "aiReport": {
    "schemaVersion": "1.0.0",
    "generatedAt": "2026-03-22T12:00:00.000Z",
    "tool": {
      "name": "zeta-doctor",
      "packageName": "@idoa/dev-doctor-zeta",
      "chain": "zetachain"
    },
    "target": {
      "network": "athens3",
      "connectedChain": "base-sepolia",
      "configPath": "/workspace/zeta-doctor.config.json",
      "cwd": "/workspace"
    },
    "status": "degraded",
    "score": 84,
    "summary": {
      "total": 7,
      "passed": 5,
      "warned": 2,
      "failed": 0,
      "skipped": 0,
      "highestSeverity": "warning"
    },
    "findings": [
      {
        "id": "gateway.preflight",
        "title": "Gateway config preflight",
        "status": "warn",
        "severity": "warning",
        "rootCauseLabel": "gateway_address_missing",
        "confidence": 0.85,
        "summary": "No gatewayAddress was configured. Core preflight can still run, but gateway-specific validation is limited.",
        "recommendedActions": [
          "Add gatewayAddress if your Universal App depends on Gateway-based deposits or calls."
        ],
        "promptReadyExplanation": "Gateway checks are partial because no gateway address was supplied in config.",
        "evidence": [
          "GATEWAY_OPTIONAL_MISSING: No gatewayAddress was configured. Core preflight can still run, but gateway-specific validation is limited."
        ]
      }
    ],
    "recommendedActions": [
      "Add gatewayAddress if your Universal App depends on Gateway-based deposits or calls."
    ],
    "promptReadyExplanation": "ZetaChain Universal App preflight finished with status degraded and score 84/100. Summary: 5 pass, 2 warn, 0 fail, 0 skip. Primary diagnostic labels: gateway.preflight=gateway_address_missing."
  }
}
```

## Shared Architecture

This package reuses the shared `chain-dev-doctor-core` packages and keeps ZetaChain-specific logic in the adapter layer:

- `src/checks`
- `src/config`
- `src/services`
- `src/reporters`
- `src/commands`
- `src/adapters`

Shared packages:

- `@idoa/dev-doctor-core`
- `@idoa/dev-doctor-types`
- `@idoa/dev-doctor-utils`
- `@idoa/dev-doctor-reporter`
- `@idoa/dev-doctor-cli-kit`

## Local Development

Install dependencies and run validation:

```bash
npm install
npm run build
npm run typecheck
npm run lint
npm run test
```

Local CLI testing before publishing:

```bash
cp zeta-doctor.config.example.json zeta-doctor.config.json
npm run build
node dist/cli.js doctor
node dist/cli.js doctor env
node dist/cli.js doctor preflight
node dist/cli.js doctor json
node dist/cli.js doctor cctx --hash 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
```

Use the final binary name locally:

```bash
npm link
zeta-doctor doctor
zeta-doctor doctor env
```