@powersync/diagnostics 0.0.2 → 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 (54) hide show
  1. package/README.md +71 -4
  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-server.d.ts +21 -0
  7. package/lib/src/agent-server.js +51 -0
  8. package/lib/src/agent-server.js.map +1 -0
  9. package/lib/src/agent.d.ts +8 -19
  10. package/lib/src/agent.js +39 -59
  11. package/lib/src/agent.js.map +1 -1
  12. package/lib/src/client.js +5 -4
  13. package/lib/src/client.js.map +1 -1
  14. package/lib/src/definition.js +11 -17
  15. package/lib/src/definition.js.map +1 -1
  16. package/lib/src/js-agent.d.ts +6 -13
  17. package/lib/src/js-agent.js +18 -9
  18. package/lib/src/js-agent.js.map +1 -1
  19. package/lib/src/node.d.ts +1 -1
  20. package/lib/src/node.js +2 -2
  21. package/lib/src/node.js.map +1 -1
  22. package/lib/src/page.js +2 -3
  23. package/lib/src/page.js.map +1 -1
  24. package/lib/src/react-native/agent-tools.d.ts +3 -0
  25. package/lib/src/react-native/agent-tools.js +137 -0
  26. package/lib/src/react-native/agent-tools.js.map +1 -0
  27. package/lib/src/react-native/protocol.d.ts +22 -0
  28. package/lib/src/react-native/protocol.js +5 -0
  29. package/lib/src/react-native/protocol.js.map +1 -0
  30. package/lib/src/react-native/usePowerSyncDevTools.d.ts +7 -0
  31. package/lib/src/react-native/usePowerSyncDevTools.js +56 -0
  32. package/lib/src/react-native/usePowerSyncDevTools.js.map +1 -0
  33. package/lib/src/react-native.d.ts +7 -0
  34. package/lib/src/react-native.js +8 -0
  35. package/lib/src/react-native.js.map +1 -0
  36. package/lib/src/rpc-types.d.ts +1 -1
  37. package/lib/src/tools.d.ts +19 -0
  38. package/lib/src/tools.js +24 -0
  39. package/lib/src/tools.js.map +1 -0
  40. package/lib/tsconfig.tsbuildinfo +1 -1
  41. package/package.json +41 -13
  42. package/src/agent-server.ts +73 -0
  43. package/src/agent.ts +50 -82
  44. package/src/client.ts +5 -5
  45. package/src/definition.ts +11 -17
  46. package/src/js-agent.ts +28 -26
  47. package/src/node.ts +3 -3
  48. package/src/page.ts +2 -4
  49. package/src/react-native/agent-tools.ts +148 -0
  50. package/src/react-native/protocol.ts +33 -0
  51. package/src/react-native/usePowerSyncDevTools.ts +59 -0
  52. package/src/react-native.ts +14 -0
  53. package/src/rpc-types.ts +1 -1
  54. package/src/tools.ts +35 -0
package/README.md CHANGED
@@ -9,10 +9,11 @@ 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
- DevTools run in development only. Nothing from this package goes into a production build.
16
+ The hosts above run in development only, and nothing from them goes into a production build.
16
17
 
17
18
  Full guide: [PowerSync DevTools](https://docs.powersync.com/tools/devtools-overview).
18
19
 
@@ -71,9 +72,74 @@ 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
+
119
+ ## Your own host
120
+
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:
122
+
123
+ ```ts
124
+ import { attachIframe, createIntegration } from '@powersync/diagnostics/agent';
125
+
126
+ const integration = createIntegration(db, '@powersync/web');
127
+ const detach = attachIframe(integration, iframe);
128
+
129
+ // When the panel goes away:
130
+ detach();
131
+ await integration.close();
132
+ ```
133
+
134
+ `uiDistDir()` from `@powersync/diagnostics` returns the folder that holds the DevTools page. Serve it at a route of your own and point the iframe at its `index.html`. In development, the `@powersync/diagnostics/vite-static` plugin serves it at `/__powersync/`. For production, copy the folder into your build output.
135
+
136
+ The port can run any SQL and read the sync token, so `attachIframe` only hands it to a page from the origin of the iframe's `src`. The `targetOrigin` option allows a different origin. The `onHandOff` option is called each time `attachIframe` hands the page a port, for example to hide a loading state.
137
+
138
+ **Clear & re-sync** in DevTools deletes the local rows, which is slow on a large database. A host with a throwaway client, like the PowerSync Dashboard, can pass `attachIframe` a wrapper whose `action` handles `clearData` itself and whose other methods call the integration's. Write each method out, because `{ ...integration }` copies none of them and TypeScript does not catch it. Do not delete a real app's database files, because the client would get a new client id. `disconnectAndClear()` keeps the existing one.
139
+
74
140
  ## MCP
75
141
 
76
- 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).
77
143
 
78
144
  | Tool | Arguments | Returns |
79
145
  | ------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
@@ -105,9 +171,10 @@ curl -X POST http://localhost:<port>/__mcp \
105
171
 
106
172
  ## Requirements
107
173
 
108
- - `@powersync/web >= 2.5` for browser apps, `@powersync/node` for node apps.
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.
109
175
  - Vite DevTools for the dock: Vite `>= 8.3` with `devtools: true`, or the `@vitejs/devtools` plugin on Vite 7.
110
176
  - Node `>= 20.16` for the node entry.
177
+ - React Native `>= 0.76` and Rozenite `>= 2.5` for the `react-native` entry.
111
178
 
112
179
  ## Related packages
113
180