@powersync/diagnostics 0.0.3 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +48 -2
  2. package/dist/devtools/assets/powersync-B1PBHXj2.js +184 -0
  3. package/dist/devtools/assets/powersync-CpTiA65L.css +1 -0
  4. package/dist/devtools/powersync.html +24 -0
  5. package/dist/rozenite.json +14 -0
  6. package/lib/src/agent.js +32 -4
  7. package/lib/src/agent.js.map +1 -1
  8. package/lib/src/definition.js +11 -17
  9. package/lib/src/definition.js.map +1 -1
  10. package/lib/src/js-agent.d.ts +1 -0
  11. package/lib/src/js-agent.js +11 -1
  12. package/lib/src/js-agent.js.map +1 -1
  13. package/lib/src/react-native/agent-tools.d.ts +3 -0
  14. package/lib/src/react-native/agent-tools.js +137 -0
  15. package/lib/src/react-native/agent-tools.js.map +1 -0
  16. package/lib/src/react-native/protocol.d.ts +22 -0
  17. package/lib/src/react-native/protocol.js +5 -0
  18. package/lib/src/react-native/protocol.js.map +1 -0
  19. package/lib/src/react-native/usePowerSyncDevTools.d.ts +7 -0
  20. package/lib/src/react-native/usePowerSyncDevTools.js +56 -0
  21. package/lib/src/react-native/usePowerSyncDevTools.js.map +1 -0
  22. package/lib/src/react-native.d.ts +7 -0
  23. package/lib/src/react-native.js +8 -0
  24. package/lib/src/react-native.js.map +1 -0
  25. package/lib/src/rpc-types.d.ts +1 -1
  26. package/lib/src/tools.d.ts +19 -0
  27. package/lib/src/tools.js +24 -0
  28. package/lib/src/tools.js.map +1 -0
  29. package/lib/tsconfig.tsbuildinfo +1 -1
  30. package/package.json +31 -8
  31. package/src/agent.ts +37 -4
  32. package/src/definition.ts +11 -17
  33. package/src/js-agent.ts +12 -1
  34. package/src/react-native/agent-tools.ts +148 -0
  35. package/src/react-native/protocol.ts +33 -0
  36. package/src/react-native/usePowerSyncDevTools.ts +59 -0
  37. package/src/react-native.ts +14 -0
  38. package/src/rpc-types.ts +1 -1
  39. package/src/tools.ts +35 -0
package/README.md CHANGED
@@ -9,8 +9,9 @@ One implementation runs in several hosts:
9
9
  | A Vite app (React, Vue, Svelte, …) with Vite DevTools | `@powersync/diagnostics/vite` | A **PowerSync** dock in Vite DevTools, and MCP tools at `/__devtools/__mcp` |
10
10
  | A Nuxt app | [`@powersync/nuxt`](https://github.com/powersync-ja/powersync-js/tree/main/packages/nuxt) with `useDiagnostics: true` | A **PowerSync** tab or dock in Nuxt DevTools |
11
11
  | A node app (`@powersync/node`) | `@powersync/diagnostics/node` | A DevTools window served by your process, and MCP tools at `/__mcp` |
12
+ | A React Native app (`@powersync/react-native`) | `@powersync/diagnostics/react-native` with [Rozenite](https://www.rozenite.dev/) | A **PowerSync** panel in React Native DevTools, and Rozenite agent tools |
12
13
 
13
- The process that runs your app also serves the DevTools window. You start nothing else.
14
+ The process that runs your app (or Metro, for React Native) also serves the DevTools window. You start nothing else.
14
15
 
15
16
  The hosts above run in development only, and nothing from them goes into a production build.
16
17
 
@@ -71,6 +72,50 @@ Your process serves the DevTools window on a random free port. Open the printed
71
72
 
72
73
  Options: `port` (default: a random free port), `host`, `auth` (default `true`), `open` (open the browser, default `false`), `sdk` and `id` (labels in the UI), `mcp` (see [MCP](#mcp)).
73
74
 
75
+ ## React Native
76
+
77
+ PowerSync DevTools run as a [Rozenite](https://www.rozenite.dev/) plugin, a panel in React Native DevTools. Install:
78
+
79
+ ```bash
80
+ pnpm add -D @powersync/diagnostics @rozenite/metro @rozenite/plugin-bridge @rozenite/agent-bridge
81
+ ```
82
+
83
+ Install them as direct dependencies of the app. Rozenite finds the plugin among those.
84
+
85
+ Enable Rozenite in Metro:
86
+
87
+ ```js
88
+ // metro.config.js
89
+ const { getDefaultConfig } = require('expo/metro-config'); // or '@react-native/metro-config'
90
+ const { withRozenite } = require('@rozenite/metro');
91
+
92
+ module.exports = withRozenite(getDefaultConfig(__dirname), {
93
+ enabled: process.env.WITH_ROZENITE === 'true',
94
+ projectType: 'expo' // for Expo apps with app.config.ts or app.config.js
95
+ });
96
+ ```
97
+
98
+ Rozenite detects Expo only from an `app.json`. Without `projectType`, an Expo app with `app.config.ts` gets React Native DevTools without the Rozenite tab.
99
+
100
+ Call the hook once, in a component that stays mounted, such as the root layout:
101
+
102
+ ```tsx
103
+ import { usePowerSyncDevTools } from '@powersync/diagnostics/react-native';
104
+
105
+ usePowerSyncDevTools(db);
106
+ ```
107
+
108
+ The hook is a no-op in production builds, and bundlers leave its code out. For per-bucket download totals, connect with `db.connect(connector, { diagnostics: __DEV__ })`.
109
+
110
+ Start the app with `WITH_ROZENITE=true` (for example `WITH_ROZENITE=true npx expo run:ios`), open React Native DevTools (press `j` in the Metro terminal), select **Rozenite**, then **PowerSync**.
111
+
112
+ Coding agents use the same tools through Rozenite's agent CLI, under the `powersync/diagnostics` domain:
113
+
114
+ ```bash
115
+ npx rozenite agent powersync/diagnostics status
116
+ npx rozenite agent powersync/diagnostics query --sql "SELECT * FROM ps_buckets"
117
+ ```
118
+
74
119
  ## Your own host
75
120
 
76
121
  A page that opens the database itself and shows DevTools in its own iframe, such as the PowerSync Dashboard, builds the integration and hands it to the frame:
@@ -94,7 +139,7 @@ The port can run any SQL and read the sync token, so `attachIframe` only hands i
94
139
 
95
140
  ## MCP
96
141
 
97
- Every host exposes the same tools. Names are `powersync_<function>`. Arguments are positional, `arg0` first:
142
+ Every host exposes the same tools. Names are `powersync_<function>`. Arguments are positional, `arg0` first. React Native has no MCP endpoint: the same tools are Rozenite agent tools (`query`, `schema`, `info`, `status`, `upload-queue`, `action`) with named arguments, for the one database passed to the hook. See [React Native](#react-native).
98
143
 
99
144
  | Tool | Arguments | Returns |
100
145
  | ------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
@@ -129,6 +174,7 @@ curl -X POST http://localhost:<port>/__mcp \
129
174
  - `@powersync/web >= 2.5` for browser apps and the `agent` entry, and `@powersync/node >= 1.2` for node apps. Earlier versions drop the connector once the database connects, so DevTools cannot reconnect the client.
130
175
  - Vite DevTools for the dock: Vite `>= 8.3` with `devtools: true`, or the `@vitejs/devtools` plugin on Vite 7.
131
176
  - Node `>= 20.16` for the node entry.
177
+ - React Native `>= 0.76` and Rozenite `>= 2.5` for the `react-native` entry.
132
178
 
133
179
  ## Related packages
134
180