/debug-app

name: debug-app
description: Diagnose Power Apps mobile install/startup failures, npm run dev errors, missing package entry points, or QR/device-opening problems even before an app is loaded. Inspect locally first; restore locked dependencies or restart Metro only with explicit approval, never upgrade packages or patch host/MSAL source. For a running native app, monitor sanitized project-local Metro logs and diagnose runtime errors or silent failures such as empty lists and blank screens. Supports startup-only diagnosis, symptoms, port/platform filters, bounded monitoring, and non-mutating --no-fix mode. Verify the original symptom, not merely installation or quiet logs.
user-invocable: true
allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion, WebFetch, mcp__plugin_mobile-app_microsoft-learn__microsoft_docs_search
model: sonnet

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` - if it outputs a message, show it to the user before proceeding.

**📋 Shared instructions: [shared-instructions.md](${PLUGIN_ROOT}/shared/shared-instructions.md)** — read first.

Startup diagnosis uses the targeted compatibility inspection below instead of the shared blanket version check; missing dependencies must not prevent diagnosis. It does not check for updates. Explicit startup repair/restart approval overrides shared auto-proceed/default-answer guidance.

Debug App — Monitor & Fix

Monitor the running app through the project-local `.powernative/metro-logs/` files written by `metro.config.js`, detect runtime and bundle errors, and fix them autonomously by editing the affected files (or routing to the right skill when the fix belongs in a domain like Dataverse schema or auth registration). For silent failures, inject temporary `console.log` statements at data-path boundaries, read only newly appended log bytes, then clean the traces after the root cause is fixed. Modeled on the upstream `app-debugger.agent.md` pattern — foreground loop, bounded polling, configurable clean-check/timeout exits, and optional watch-only operation.

When setup/startup or device opening is failing, first execute [startup-diagnostics.md](references/startup-diagnostics.md). This bounded phase can run without Metro logs or a loaded app and returns to the runtime path only when its prerequisites actually hold. Running `npm run dev` alone does not activate an agent, and this skill installs no background watcher.

> **Dev-client limitation:** the standalone dev client sends app/runtime logs, React errors, host diagnostics, and Metro bundler output through Metro. The template's `metro.config.js` writes Metro terminal output and HTTP bundle failures into `.powernative/metro-logs/`; there is no separate device log source. Host diagnostics include strings such as `[AuthProvider] MSAL init failed:`, `[bridge] fetch THREW for`, `[bridge] HTTP <status> for`, `[addAadAppToConnectionAcl] failed HTTP <status> for connection`, `[useConnectionRefs] could not verify connection ACLs; treating existing connections as setup-required`, and `[PAHost][ErrorBoundary] Unhandled JS error:`.

Subcommands (parsed from `$ARGUMENTS`)

| Form | Behavior | |---|---| | `/debug-app` (no args) | **Default — project-log-driven mode.** Run Phase 0, discover valid project-local Metro sessions, select automatically when one is live or ask when several are live, then monitor the selected log. No host terminal ID is required. | | `/debug-app "<symptom text>"` | **Symptom-driven mode** (recommended when there's a user-visible problem). Free-text symptom such as `"todos not appearing on home screen"`, `"login button does nothing"`, `"list empty after refresh"`. Run Phase 0 → Phase 0.5 (parse symptom → ask the user to reproduce/navigate → walk the likely data path from terminal traces) → enter monitor loop. Catches silent failures (empty lists, blank screens, swallowed errors) that pure log polling misses. | | `/debug-app startup ["<symptom text>"] [--tunnel] [--tunnel-tenant <tenant-guid>]` | **Startup-only diagnosis.** Inspect install/startup/QR failures, offer bounded approved repair, and verify the original symptom. Preserve explicitly selected authenticated tunnel options for an approved retry. Return without the runtime monitor; also used by creation-time failure handoffs. | | `/debug-app status` | Discover all project-local Metro logs and print each valid session's project, platform, PID, port, start time, and log path. Mark the session referenced by the saved cursor when present, then print fixes and unresolved errors. Do NOT ask for a selection or enter the loop. | | `/debug-app stop` | Stop only the foreground debug loop and preserve `.powernative/debug-app/` state. It does not stop Metro; the user owns the `npm run dev` process. | | `/debug-app version` | Print the installed `mobile-app` plugin name and version from `${PLUGIN_ROOT}/.plugin/plugin.json`, then exit. |

Monitoring options

Options may follow the default command, a symptom, or `status`:

| Option | Meaning | Default | |---|---|---| | `--working-dir <path>` | App root containing `package.json`. Startup diagnosis accepts missing Metro config or dependencies; runtime monitoring requires a configured, live Metro session. Relative paths resolve from the current shell directory. | Current shell directory | | `--port <1-65535>` | Monitor only the valid Metro session on this port. | Any port | | `--platform <ios\|android>` | Consider only sessions whose recent log identifies this platform. | Any platform | | `--cycles <1-50>` | Exit after this many consecutive clean observation intervals. | `3` | | `--timeout <duration>` | Maximum wall-clock monitoring time. Accept `30s`–`60m` using `s`, `m`, or `h`. | `5m` | | `--no-fix` | Inspect/watch-only: never edit project source/config, inject traces, install, regenerate, start/stop/restart Metro, open the device app, or invoke a mutating handoff. Debug cursor/audit/health state may still advance. | Fix enabled |