diff --git a/README.md b/README.md index 4b928082..2b56acc1 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,9 @@ Change the running device's appearance, text size, rotation, location, and statu ### App Flow Build a visual map of your app's screens and the navigation between them, for Expo Router and React Navigation projects. **Structure only** reads the navigation out of your source in seconds and needs no device; **Screen UI + Structure** also walks the app on an iOS simulator and photographs every screen it reaches, optionally opening each screen's sheets, modals, and dialogs. The walk runs your project's own `ios` script and reaches each screen through in-app navigation, a deep link, or a path you recorded; record one by hand on the live wireframe for a screen it cannot reach. Explore with AI lists the screens the deterministic pass missed and retries only the ones you pick. Maps, captures, and recorded paths are stored per project under `~/Library/Application Support/mobile-dev/app-flow`. +### App Intelligence +Trace each Expo Router or React Navigation screen through the source files, assets, and packages it depends on, without building or running the app. Choose a project and generate its static iOS and Android graph, then browse entry points by area, fold or highlight dependency groups, and see which dependencies are platform-specific. Ask your agent what a screen depends on, which screens reach a file, or to show one screen's graph. Saved snapshots live under `~/Library/Application Support/mobile-dev/app-intelligence`; project paths and graph contents are excluded from Sentry telemetry. + ### Native and JavaScript logs Read iOS unified logs, Android logcat, and Metro console messages together. Follow the foreground app, search and filter logs, and send an error and its stack trace to chat. @@ -214,8 +217,9 @@ Ask your agent to work with your app, for example: - “Read the app logs and help me fix this error.” - “Record CPU and memory for 30 seconds while I scroll checkout.” - “Compare these two performance recordings.” +- “Show me the App Intelligence for this project.” -Open Logs, Performance, Storage, or TraceSift to inspect the selected device. Use Screenshot to attach +Open App Intelligence, Logs, Performance, Storage, or TraceSift. App Intelligence analyzes a project without a device; the other tools inspect the selected device. Use Screenshot to attach an image to your next message, or Select to annotate an element or region with an instruction. Physical iOS supports taps and drags; keyboard and hardware-button controls are unavailable. @@ -226,6 +230,7 @@ Detailed guides are available for [devices](https://github.com/callstackincubator/mobile-dev/blob/main/docs/devices.md), [logs](https://github.com/callstackincubator/mobile-dev/blob/main/docs/logs.md), [performance](https://github.com/callstackincubator/mobile-dev/blob/main/docs/performance.md), +[App Intelligence](https://incubator.callstack.com/codex-mobile-dev-plugin/docs/app-intelligence), and [MCP tools](https://github.com/callstackincubator/mobile-dev/blob/main/docs/mcp-tools.md). [Architecture](https://github.com/callstackincubator/mobile-dev/blob/main/docs/architecture.md) explains how the hosts share the server and panel. diff --git a/docs/mcp-tools.md b/docs/mcp-tools.md index a8b31b7e..87137417 100644 --- a/docs/mcp-tools.md +++ b/docs/mcp-tools.md @@ -6,6 +6,7 @@ | --- | --- | | `mobile_open_simulator` | Open the native panel, optionally targeting a platform, device kind, or discovered device ID | | `mobile_open_workspace` | Open fullscreen with the same optional device targeting | +| `mobile_open_app_intel` | Open App Intelligence, optionally focused on an exact screen ID from `mobile_app_intel` | | `mobile_list_simulators` | Start the bundled backend if needed and list devices | | `mobile_choose_devices` | Ask the user to choose task targets in the host's native form; listed only for hosts with one (Codex, Claude Code) | | `mobile_list_ios_devices` | Discover physical iPhones and iPads with USB/Wi-Fi, pairing state, UDID, and CoreDevice ID | @@ -19,6 +20,14 @@ | `mobile_stream_input` | Send a batch of panel input, app-only | | `mobile_stream_reset` | Recover one iOS panel's MJPEG capture, app-only | | `mobile_stream_close` | Close a panel stream, app-only | +| `mobile_generate_app_intel` | Generate or replace a React Native project's static screen and dependency graph | +| `mobile_app_intel` | Search the saved graph or query a screen/file's incoming or outgoing relationships | +| `mobile_pick_app_intel_project` | Choose a project with the host folder picker, app-only | +| `mobile_select_app_intel_project` | Switch to a remembered project, app-only | +| `mobile_app_intel_snapshot` | Read the selected project's graph for the visualization, app-only | +| `mobile_app_intel_status` | Read generation progress and saved-snapshot status, app-only | +| `mobile_clear_app_intel` | Delete the selected project's saved graph, app-only | +| `mobile_cancel_app_intel` | Cancel generation before its atomic save, app-only | | `mobile_log_sources` | List connected Android devices and local Metro targets | | `mobile_logs_session` | Start native and/or Metro log readers | | `mobile_read_logs` | Read a log batch and source status | diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 8fd746d6..adc27f74 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -23,6 +23,7 @@ const sidebar = [ { label: 'Getting started', slug: 'docs/getting-started' }, { label: 'Devices', slug: 'docs/devices' }, { label: 'App control', slug: 'docs/app-control' }, + { label: 'App Intelligence', slug: 'docs/app-intelligence' }, { label: 'App Flow', slug: 'docs/app-flow' }, { label: 'Logs', slug: 'docs/logs' }, { label: 'Performance', slug: 'docs/performance' }, diff --git a/website/src/content/docs/docs/app-intelligence.md b/website/src/content/docs/docs/app-intelligence.md new file mode 100644 index 00000000..5af32d47 --- /dev/null +++ b/website/src/content/docs/docs/app-intelligence.md @@ -0,0 +1,45 @@ +--- +title: App Intelligence +description: Trace Expo Router and React Navigation screens through their source files, assets, and packages without building or running the app. +--- + +Open **App Intelligence** to see how each screen reaches the source files, assets, and packages it depends on. It statically analyzes an Expo Router or React Navigation project, so it does not need a running device, Metro, or an App Flow map. + +App Intelligence answers source-structure questions. Use [App Flow](/docs/app-flow) when you need a map of runtime navigation, screen captures, UI states, or recorded paths through the running app. + +## Generate a graph + +Choose the React Native project folder in the panel, then choose **Generate**. You can also ask your agent: + +> Show me the App Intelligence for this project. + +The analysis discovers Expo Router routes and React Navigation screen registrations, then follows static imports for iOS and Android. It understands project-relative path aliases and platform-specific module resolution. Source files and assets remain individual nodes; third-party packages are shown as leaf nodes rather than expanding their internals. + +Generation reads the project but does not modify, build, or launch it. If source files change, choose **Regenerate** to replace the saved snapshot. + +## Read the graph + +The first view groups entry points by architectural area, such as navigation, components, state, or API and data. Select an area, open the entry-point list, and choose a screen to trace its dependency flow. + +The flow starts at that screen and follows its component, layouts, imports, assets, and packages. Groups can be folded to reduce detail, expanded to show every entry, or highlighted to follow one boundary across the graph. Platform markers identify dependencies that resolve only for iOS or Android. A file or package's reach count is the number of screens that depend on it. + +Use the filter to search screen titles, routes, IDs, and source paths, or to show only selected areas. + +## Ask the agent about dependencies + +Your agent can query the saved graph without opening the view. For example: + +- “What does the Checkout screen depend on?” +- “Which screens import `src/components/Price.tsx`?” +- “Find files related to authentication in App Intelligence.” +- “Show the dependency graph for the Profile screen.” + +Screen queries can follow outgoing dependencies or incoming consumers. File queries can find imports, importers, and the screens connected to a project-relative path. The agent starts with a compact result and can request more depth or pages when needed. + +Static analysis cannot prove relationships created only at runtime. Unresolved imports or screen components appear as diagnostics, and dynamic behavior may be absent from the graph. + +## Saved data and clearing + +Each project has one saved snapshot under `~/Library/Application Support/mobile-dev/app-intelligence`. It contains project-relative paths, screen names and routes, package names, dependency relationships, and diagnostics. The selected project and up to eight recent project paths are also remembered locally. + +Choose **Clear** to delete the selected project's graph. The project remains selected and in the recent-project list, so it can be analyzed again. App Intelligence graph contents and project paths are excluded from Mobile Dev's Sentry telemetry. Results rendered by or returned to your host follow the host's own handling; see [Privacy](/docs/privacy). diff --git a/website/src/content/docs/docs/getting-started.md b/website/src/content/docs/docs/getting-started.md index 1f335cc7..7b18c35c 100644 --- a/website/src/content/docs/docs/getting-started.md +++ b/website/src/content/docs/docs/getting-started.md @@ -114,7 +114,7 @@ Follow your client's configuration format. Device panels and interactive recordi 1. Ask **“Build and run my app in the simulator beside this chat.”** You can name iOS, Android, a simulator model, or a connected device. 2. Choose or reuse a device. Selecting a stopped simulator or AVD boots it. -3. Watch the app beside the conversation. Use **Select** to annotate an element, or open **Logs**, **Performance**, **Storage**, or **TraceSift**. +3. Watch the app beside the conversation. Use **Select** to annotate an element, or open **App Intelligence**, **Logs**, **Performance**, **Storage**, or **TraceSift**. Your app's own build tools compile, install, and launch it. Mobile Dev does not install Xcode runtimes or replace your project's build system. diff --git a/website/src/content/docs/docs/introduction.md b/website/src/content/docs/docs/introduction.md index f62d6db6..849a1862 100644 --- a/website/src/content/docs/docs/introduction.md +++ b/website/src/content/docs/docs/introduction.md @@ -1,9 +1,9 @@ --- title: Introduction -description: Bring devices, logs, performance, and app storage into your ADE so you and your coding agent can work on the same running app. +description: Bring app structure, devices, logs, performance, and app storage into your ADE so you and your coding agent can work on the same mobile project. --- -Mobile Dev is a plugin for mobile development in your agentic development environment (ADE). It brings iOS and Android devices beside your conversation, with tools to inspect the running app, read logs, record performance, and explore app storage. +Mobile Dev is a plugin for mobile development in your agentic development environment (ADE). It brings your app's structure and iOS and Android devices beside your conversation, with tools to trace source dependencies, inspect the running app, read logs, record performance, and explore app storage. It works with Expo, React Native, SwiftUI, and other native mobile projects. Your project's own tools build and run the app. Mobile Dev supplies the device workspace and the information you and your agent use to work on it. @@ -21,6 +21,7 @@ The agent opens Mobile Dev, selects a suitable installed device, and uses the pr | --- | --- | | Select simulators, emulators, or physical devices; inspect and annotate the screen | [Devices](/docs/devices) | | Install or relaunch an app, open a deep link, change permissions, or test another language | [App control](/docs/app-control) | +| Trace screens through their source files and packages without running the app | [App Intelligence](/docs/app-intelligence) | | Map an app's screens and navigation, capture each screen, and record a path to one | [App Flow](/docs/app-flow) | | Read native and Metro messages together and send a log to your agent | [Logs](/docs/logs) | | Record CPU, memory, and supported device Display FPS; select and compare ranges | [Performance](/docs/performance) | diff --git a/website/src/content/docs/docs/privacy.md b/website/src/content/docs/docs/privacy.md index 636ece78..28fd48a8 100644 --- a/website/src/content/docs/docs/privacy.md +++ b/website/src/content/docs/docs/privacy.md @@ -39,6 +39,9 @@ Depending on the tools you use, Mobile Dev processes: - Native and Metro logs, including messages, timestamps, app/process metadata, and stack traces. - App CPU, memory, thread, FPS, and frame-timing measurements and saved recordings. +- App Intelligence project paths, screen names and routes, project-relative source + and asset paths, package names, static import relationships, and analysis + diagnostics when you generate or query a source graph. - App storage keys, values, database rows, and file metadata when you inspect storage. Results are filtered before reaching the host or panel: recognized sensitive fields, credential-like values, and binary values are redacted. These @@ -91,8 +94,9 @@ not a guarantee of anonymity. These IDs are excluded from performance metrics and span attributes. The reporting code excludes MCP arguments/results, screenshots, screen video, -app log content, typed/pasted text, app storage contents, profile contents, and -device performance recordings. It scrubs common secrets, email addresses, URLs, +app log content, typed/pasted text, App Intelligence graph contents, app storage +contents, profile contents, and device performance recordings. It scrubs common +secrets, email addresses, URLs, and local home paths from error text. Session Replay, minidumps, and profiling are disabled in the configured Sentry integrations. Scrubbing is a safeguard, not a reason to put secrets into your test data. @@ -178,6 +182,7 @@ and [OpenAI's privacy policy](https://openai.com/policies/privacy-policy/). | Sentry performance spans and Application Metrics | 30 days under our Sentry Team plan. | | Mixpanel product analytics | Up to 24 months, then deleted. | | Local live logs | Held in bounded memory buffers. A server log session expires after five minutes without reads or keep-alives; closing the session stops collection. Copies already attached to the host follow the host's retention. | +| Saved App Intelligence graphs and project history | Stored under `~/Library/Application Support/mobile-dev/app-intelligence` until you clear a graph or remove the files. Clearing a graph keeps the project in the recent-project list. | | Saved performance recordings | Stored under `~/Library/Application Support/mobile-dev/recordings` until you remove them; the recording store has no automatic age-based expiry. | | TraceSift integration results/references and the chosen project folder | Stored under `~/.tracesift/integrations/mobile-dev` by default, or the corresponding `TRACE_SIFT_HOME` directory, until removed. Original profiles and the TraceSift service's own data are separate. | | Installation ID | Stored at `~/Library/Application Support/mobile-dev/telemetry/anonymous-user-id` until you remove it. Process-session IDs last for the process; copies in sent reports follow Sentry retention. | diff --git a/website/src/pages/index.astro b/website/src/pages/index.astro index 8a4ba27b..5bc6535f 100644 --- a/website/src/pages/index.astro +++ b/website/src/pages/index.astro @@ -9,6 +9,7 @@ const tools = [ { name: 'Logs', href: docs.logs }, { name: 'Performance', href: docs.performance }, { name: 'Storage', href: docs.storage }, + { name: 'App Intelligence', href: docs.appIntelligence }, ]; --- diff --git a/website/src/site/content.ts b/website/src/site/content.ts index 8f19d2c8..6a9602b6 100644 --- a/website/src/site/content.ts +++ b/website/src/site/content.ts @@ -13,7 +13,7 @@ export const site = { repo: 'https://github.com/callstackincubator/codex-mobile-dev-plugin', subtitle: 'Mobile development in your ADE', headline: ['Mobile development.', 'In your ADE.'], - lede: 'A plugin for mobile development in your ADE. Bring your running app, devices, logs, performance, and storage into Codex, Claude, Cursor, and more.', + lede: 'A plugin for mobile development in your ADE. Bring your app structure, running app, devices, logs, performance, and storage into Codex, Claude, Cursor, and more.', description: 'A plugin for mobile development in your ADE. Run, inspect, and debug iOS and Android apps inside Codex, Claude, Cursor, and more.', install: 'codex plugin add mobile-dev@mobile-dev', skill: undefined as string | undefined, @@ -35,6 +35,7 @@ export const docs = { start: at('/docs/getting-started'), devices: at('/docs/devices'), control: at('/docs/app-control'), + appIntelligence: at('/docs/app-intelligence'), appFlow: at('/docs/app-flow'), logs: at('/docs/logs'), performance: at('/docs/performance'), @@ -93,6 +94,7 @@ export const features: Feature[] = [ { icon: 'panel', title: 'Native and app logs', body: 'Follow iOS, Android, and Metro logs, then send the relevant error to your agent.', href: docs.logs }, { icon: 'gauge', title: 'Performance recordings', body: 'Record CPU, memory, and supported device Display FPS over the interaction you want to understand.', href: docs.performance }, { icon: 'flame', title: 'Profile analysis', body: 'Explore CPU and React profiles with TraceSift, and investigate selected frames with your agent.', href: docs.profiles }, + { icon: 'network', title: 'App Intelligence', body: 'Trace each screen through your source files and packages without building or running the app.', href: docs.appIntelligence }, { icon: 'grid', title: 'App Flow', body: 'Map every screen and navigation edge, and capture each screen on a simulator or emulator.', href: docs.appFlow }, { icon: 'database', title: 'App storage', body: 'Inspect files, databases, and key-value stores. Watch changes while you use your app.', href: docs.storage }, { icon: 'network', title: 'Your existing stack', body: 'Use your app’s own build tools with Expo, React Native, SwiftUI, and native projects.', href: docs.start },