@powersync/diagnostics 0.0.1 → 0.0.3

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@powersync/diagnostics",
3
- "version": "0.0.1",
3
+ "version": "0.0.3",
4
4
  "description": "PowerSync DevTools: a devframe definition that serves live PowerSync diagnostics as a Vite DevTools dock, a node dev server, and MCP tools.",
5
5
  "type": "module",
6
6
  "main": "lib/src/index.js",
@@ -29,6 +29,10 @@
29
29
  "./node": {
30
30
  "types": "./lib/src/node.d.ts",
31
31
  "default": "./lib/src/node.js"
32
+ },
33
+ "./agent": {
34
+ "types": "./lib/src/agent.d.ts",
35
+ "default": "./lib/src/agent.js"
32
36
  }
33
37
  },
34
38
  "author": "PowerSync",
@@ -50,8 +54,8 @@
50
54
  },
51
55
  "homepage": "https://docs.powersync.com",
52
56
  "peerDependencies": {
53
- "@powersync/common": "^2.3.0",
54
- "@powersync/web": "^2.2.0",
57
+ "@powersync/common": "^2.5.0",
58
+ "@powersync/web": "^2.6.0",
55
59
  "@vitejs/devtools-kit": ">=0.7.5",
56
60
  "vite": ">=7.0.0"
57
61
  },
@@ -70,20 +74,21 @@
70
74
  }
71
75
  },
72
76
  "dependencies": {
73
- "@devframes/agentic": "1.0.0",
74
- "devframe": "1.0.0",
77
+ "@devframes/agentic": "^1.2.6",
78
+ "devframe": "^1.2.6",
75
79
  "zod": "^4.6.5",
76
- "@powersync/diagnostics-core": "0.0.1",
77
- "@powersync/diagnostics-ui": "0.0.1"
80
+ "@powersync/diagnostics-core": "0.0.3",
81
+ "@powersync/diagnostics-ui": "0.0.3"
78
82
  },
79
83
  "devDependencies": {
80
- "@devframes/hub": "1.0.0",
84
+ "@devframes/hub": "^1.2.6",
81
85
  "@types/node": "^24.0.0",
82
86
  "@vitejs/devtools-kit": "^0.7.5",
83
87
  "typescript": "^6.0.3",
84
88
  "vite": "^7.3.6",
85
- "@powersync/common": "2.3.0",
86
- "@powersync/web": "2.4.1"
89
+ "@powersync/common": "2.5.0",
90
+ "@powersync/shared-internals": "1.5.0",
91
+ "@powersync/web": "2.6.0"
87
92
  },
88
93
  "scripts": {
89
94
  "build": "tsc -b",
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Serving agents to a devframe node side over an RPC client: a dock script in a web page, or a
3
+ * node process.
4
+ */
5
+ import type { DevframeRpcClient } from 'devframe/client';
6
+ import type {
7
+ ActionRequest,
8
+ DiagnosticsEvent,
9
+ QueryParams,
10
+ SdkIntegration,
11
+ Unsubscribe
12
+ } from '@powersync/diagnostics-core';
13
+ import { HEARTBEAT_MS } from './constants.js';
14
+ import './rpc-types.js';
15
+
16
+ /** Serves integrations to the node side over one RPC client. */
17
+ export interface AgentServer {
18
+ /** Announces `integration` as `sourceId` and starts forwarding its events. */
19
+ serve(sourceId: string, integration: SdkIntegration, sdk: string): Promise<void>;
20
+ /** Withdraws a served integration. */
21
+ release(sourceId: string): Promise<void>;
22
+ /** Releases everything served through this client. */
23
+ close(): Promise<void>;
24
+ }
25
+
26
+ /**
27
+ * Registers the page-side functions the node side calls (`powersync:page-*`) on `rpc`, and returns
28
+ * a server that announces integrations to it. Call once per RPC client.
29
+ */
30
+ export function createAgentServer(rpc: DevframeRpcClient): AgentServer {
31
+ const served = new Map<string, { integration: SdkIntegration; stop: Unsubscribe }>();
32
+ // The node side only knows this client is alive while it hears from it.
33
+ const heartbeat = setInterval(() => {
34
+ for (const sourceId of served.keys()) void rpc.callEvent('powersync:page-heartbeat', sourceId);
35
+ }, HEARTBEAT_MS);
36
+ (heartbeat as { unref?: () => void }).unref?.();
37
+
38
+ const integrationFor = (sourceId: string): SdkIntegration => {
39
+ const entry = served.get(sourceId);
40
+ if (!entry) throw new Error(`No database "${sourceId}" is served here.`);
41
+ return entry.integration;
42
+ };
43
+ const register = (name: string, handler: (...args: any[]) => unknown) =>
44
+ rpc.client.register({ name, type: 'action', jsonSerializable: true, handler }, true);
45
+ register('powersync:page-query', (id: string, params: QueryParams) => integrationFor(id).runQuery(params));
46
+ register('powersync:page-schema', (id: string) => integrationFor(id).getSchema());
47
+ register('powersync:page-info', (id: string) => integrationFor(id).getInfo());
48
+ register('powersync:page-action', (id: string, request: ActionRequest) => integrationFor(id).action(request));
49
+
50
+ return {
51
+ async serve(sourceId, integration, sdk) {
52
+ await rpc.call('powersync:page-register', sourceId, sdk);
53
+ const stop = await integration.observeEvents((event: DiagnosticsEvent) => {
54
+ void rpc.callEvent('powersync:page-event', sourceId, event);
55
+ });
56
+ served.set(sourceId, { integration, stop });
57
+ },
58
+ async release(sourceId) {
59
+ const entry = served.get(sourceId);
60
+ if (!entry) return;
61
+ served.delete(sourceId);
62
+ entry.stop();
63
+ await entry.integration.close();
64
+ await rpc.call('powersync:page-unregister', sourceId).catch(() => {});
65
+ },
66
+ async close() {
67
+ clearInterval(heartbeat);
68
+ for (const sourceId of [...served.keys()]) {
69
+ await this.release(sourceId);
70
+ }
71
+ }
72
+ };
73
+ }
package/src/agent.ts CHANGED
@@ -1,31 +1,29 @@
1
1
  /**
2
- * Pieces shared by every JavaScript host: building the agent over a live database, and serving
3
- * agents to a devframe node side over an RPC client (a dock script in a web page, or a node process).
2
+ * The agent for a JavaScript host: the `SdkIntegration` built over a live database. This is the
3
+ * package's `./agent` entry, for a host that opens the database and embeds the DevTools page itself;
4
+ * the dock and node entries build their agents here too.
4
5
  */
5
- import type { DevframeRpcClient } from 'devframe/client';
6
- import type { CommonPowerSyncDatabase, PowerSyncBackendConnector, SyncOptions } from '@powersync/common';
7
- import type {
6
+ import type { CommonPowerSyncDatabase } from '@powersync/common';
7
+ import type { CoreDiagnosticsEvent, SdkIntegration, Unsubscribe } from '@powersync/diagnostics-core';
8
+ import { JsAgent, type CoreEventSource } from './js-agent.js';
9
+ import type { BasePowerSyncDatabase } from '@powersync/shared-internals';
10
+
11
+ // The iframe hand-off and the protocol types an embedding host needs, so the host never imports the protocol package.
12
+ export { attachIframe } from '@powersync/diagnostics-core';
13
+ export type {
8
14
  ActionRequest,
9
- CoreDiagnosticsEvent,
15
+ AttachIframeOptions,
10
16
  DiagnosticsEvent,
11
- QueryParams,
12
17
  SdkIntegration,
13
- Unsubscribe
18
+ SyncState
14
19
  } from '@powersync/diagnostics-core';
15
- import { HEARTBEAT_MS } from './constants.js';
16
- import { JsAgent, type CoreEventSource } from './js-agent.js';
17
- import './rpc-types.js';
18
20
 
19
21
  /** The sync client broadcasts core diagnostics events on this channel (see `emitDiagnostics`). */
20
22
  const CORE_EVENTS_CHANNEL = 'powersync-diagnostics-events';
21
23
 
22
- /**
23
- * A live PowerSync JavaScript database the agent can serve: the SDK's database plus the connection
24
- * accessors every SDK's database class exposes.
25
- */
26
- export interface DiagnosableDatabase extends CommonPowerSyncDatabase {
27
- readonly connector: PowerSyncBackendConnector | null | undefined;
28
- readonly connectionOptions: SyncOptions | null | undefined;
24
+ /** The SDK label for the database, or `fallback` on SDK releases that do not report it. */
25
+ export function databaseSdk(database: CommonPowerSyncDatabase, fallback: string): string {
26
+ return (database as Partial<BasePowerSyncDatabase>).sdkName ?? fallback;
29
27
  }
30
28
 
31
29
  /** Consumes the core diagnostics events the sync client broadcasts (from a worker or in-process). */
@@ -43,73 +41,11 @@ class BroadcastCoreEvents implements CoreEventSource {
43
41
  }
44
42
  }
45
43
 
46
- /** Builds the JavaScript integration over a live database. */
47
- export function createIntegration(db: DiagnosableDatabase, sdk: string): SdkIntegration {
44
+ /** Builds the JavaScript integration over a live database. The agent reads the connection from the database itself. */
45
+ export function createIntegration(database: CommonPowerSyncDatabase, sdk: string): SdkIntegration {
46
+ const db = database as BasePowerSyncDatabase;
48
47
  return new JsAgent(db, {
49
48
  sdk,
50
- coreEvents: typeof BroadcastChannel === 'function' ? new BroadcastCoreEvents() : undefined,
51
- connection: {
52
- getConnector: () => db.connector ?? null,
53
- getConnectionOptions: () => db.connectionOptions ?? null
54
- }
49
+ coreEvents: typeof BroadcastChannel === 'function' ? new BroadcastCoreEvents() : undefined
55
50
  });
56
51
  }
57
-
58
- /** Serves integrations to the node side over one RPC client. */
59
- export interface AgentServer {
60
- /** Announces `integration` as `sourceId` and starts forwarding its events. */
61
- serve(sourceId: string, integration: SdkIntegration, sdk: string): Promise<void>;
62
- /** Withdraws a served integration. */
63
- release(sourceId: string): Promise<void>;
64
- /** Releases everything served through this client. */
65
- close(): Promise<void>;
66
- }
67
-
68
- /**
69
- * Registers the page-side functions the node side calls (`powersync:page-*`) on `rpc`, and returns
70
- * a server that announces integrations to it. Call once per RPC client.
71
- */
72
- export function createAgentServer(rpc: DevframeRpcClient): AgentServer {
73
- const served = new Map<string, { integration: SdkIntegration; stop: Unsubscribe }>();
74
- // The node side only knows this client is alive while it hears from it.
75
- const heartbeat = setInterval(() => {
76
- for (const sourceId of served.keys()) void rpc.callEvent('powersync:page-heartbeat', sourceId);
77
- }, HEARTBEAT_MS);
78
- (heartbeat as { unref?: () => void }).unref?.();
79
-
80
- const integrationFor = (sourceId: string): SdkIntegration => {
81
- const entry = served.get(sourceId);
82
- if (!entry) throw new Error(`No database "${sourceId}" is served here.`);
83
- return entry.integration;
84
- };
85
- const register = (name: string, handler: (...args: any[]) => unknown) =>
86
- rpc.client.register({ name, type: 'action', jsonSerializable: true, handler }, true);
87
- register('powersync:page-query', (id: string, params: QueryParams) => integrationFor(id).runQuery(params));
88
- register('powersync:page-schema', (id: string) => integrationFor(id).getSchema());
89
- register('powersync:page-info', (id: string) => integrationFor(id).getInfo());
90
- register('powersync:page-action', (id: string, request: ActionRequest) => integrationFor(id).action(request));
91
-
92
- return {
93
- async serve(sourceId, integration, sdk) {
94
- await rpc.call('powersync:page-register', sourceId, sdk);
95
- const stop = await integration.observeEvents((event: DiagnosticsEvent) => {
96
- void rpc.callEvent('powersync:page-event', sourceId, event);
97
- });
98
- served.set(sourceId, { integration, stop });
99
- },
100
- async release(sourceId) {
101
- const entry = served.get(sourceId);
102
- if (!entry) return;
103
- served.delete(sourceId);
104
- entry.stop();
105
- await entry.integration.close();
106
- await rpc.call('powersync:page-unregister', sourceId).catch(() => {});
107
- },
108
- async close() {
109
- clearInterval(heartbeat);
110
- for (const sourceId of [...served.keys()]) {
111
- await this.release(sourceId);
112
- }
113
- }
114
- };
115
- }
package/src/client.ts CHANGED
@@ -5,9 +5,8 @@
5
5
  */
6
6
  import type { DockClientScriptContext } from '@devframes/hub/client';
7
7
  import { observeRegisteredDatabases } from '@powersync/web/devtools';
8
- import { createAgentServer, createIntegration } from './agent.js';
9
-
10
- const SDK = '@powersync/web';
8
+ import { createIntegration, databaseSdk } from './agent.js';
9
+ import { createAgentServer } from './agent-server.js';
11
10
 
12
11
  export default function setup(context: DockClientScriptContext): void {
13
12
  const server = createAgentServer(context.rpc);
@@ -30,7 +29,8 @@ export default function setup(context: DockClientScriptContext): void {
30
29
  return;
31
30
  }
32
31
  if (currentId) return;
33
- currentId = `web-${++counter}`;
34
- void server.serve(currentId, createIntegration(database, SDK), SDK);
32
+ const sdk = databaseSdk(database, '@powersync/web');
33
+ currentId = `${sdk.replace(/^@powersync\//, '')}-${++counter}`;
34
+ void server.serve(currentId, createIntegration(database, sdk), sdk);
35
35
  });
36
36
  }
package/src/definition.ts CHANGED
@@ -24,9 +24,9 @@ import type {
24
24
  UploadQueueState
25
25
  } from '@powersync/diagnostics-core';
26
26
  import { DEVFRAME_ID, HEARTBEAT_MS, UI_ROUTE } from './constants.js';
27
- import type { SourceInfo } from './rpc-types.js';
27
+ import type { SetupSdk, SourceInfo } from './rpc-types.js';
28
28
 
29
- export type { SourceInfo } from './rpc-types.js';
29
+ export type { SetupSdk, SourceInfo } from './rpc-types.js';
30
30
 
31
31
  /** Event types replayed to a UI that subscribes late. `logs` and `core` are not replayed. */
32
32
  const SNAPSHOT_TYPES = new Set<DiagnosticsEvent['type']>(['status', 'streams', 'buckets', 'uploadQueue']);
@@ -77,6 +77,8 @@ class RemoteIntegration implements SdkIntegration {
77
77
  }
78
78
 
79
79
  const sources = new Map<string, Source>();
80
+ /** The SDKs the entry point that mounted this definition can reach; `null` for all. */
81
+ let setupSdks: SetupSdk[] | null = null;
80
82
  /** UI sessions that asked for events, keyed by session id. */
81
83
  const observers = new Map<number, DevframeNodeRpcSession>();
82
84
  /** The id a page serves a database under, per session, to the id it is listed under here. */
@@ -209,6 +211,14 @@ function removeSource(sourceId: string): void {
209
211
  * Serves an integration that lives in this process (a node app's database). Events are pulled from
210
212
  * it directly. Returns a function that detaches it.
211
213
  */
214
+ /**
215
+ * Names the SDKs this host can reach, so the UI's "no database" screens explain only those. Each entry
216
+ * point sets it: the Vite plugin, the node server, the Nuxt module.
217
+ */
218
+ export function setSetupSdks(sdks: SetupSdk[] | null): void {
219
+ setupSdks = sdks?.length ? [...sdks] : null;
220
+ }
221
+
212
222
  export async function registerIntegration(
213
223
  id: string,
214
224
  integration: SdkIntegration,
@@ -364,6 +374,14 @@ export const definition = defineDevframe({
364
374
  }
365
375
  })
366
376
  );
377
+ ps.rpc.register(
378
+ defineRpcFunction({
379
+ name: 'setup-sdks',
380
+ type: 'query',
381
+ jsonSerializable: true,
382
+ handler: (): SetupSdk[] | null => setupSdks
383
+ })
384
+ );
367
385
  ps.rpc.register(
368
386
  defineRpcFunction({
369
387
  name: 'query',
package/src/index.ts CHANGED
@@ -2,6 +2,6 @@
2
2
  // Hosts mount it: `./vite` (Vite DevTools dock) and `./node` (a node app's dev server).
3
3
  import './rpc-types.js';
4
4
 
5
- export { definition, registerIntegration, uiDistDir } from './definition.js';
6
- export type { SourceInfo } from './rpc-types.js';
5
+ export { definition, registerIntegration, setSetupSdks, uiDistDir } from './definition.js';
6
+ export type { SetupSdk, SourceInfo } from './rpc-types.js';
7
7
  export { UI_ROUTE, DEVFRAME_ID } from './constants.js';
package/src/js-agent.ts CHANGED
@@ -1,7 +1,6 @@
1
1
  import type {
2
- CommonPowerSyncDatabase,
2
+ LogLevels,
3
3
  LogRecord as SdkLogRecord,
4
- PowerSyncBackendConnector,
5
4
  SyncOptions,
6
5
  SyncStatus,
7
6
  SyncStreamSubscription
@@ -18,11 +17,11 @@ import type {
18
17
  SchemaPayload,
19
18
  SdkIntegration,
20
19
  StreamActionArgs,
21
- SyncState,
22
20
  Unsubscribe,
23
21
  UploadQueueState
24
22
  } from '@powersync/diagnostics-core';
25
23
  import { toStreamStates, toSyncState } from './sync-state.js';
24
+ import type { BasePowerSyncDatabase, InternalConnector } from '@powersync/shared-internals';
26
25
 
27
26
  /** Delivers the SQLite core's diagnostics events to the agent. How they arrive is runtime-specific. */
28
27
  export interface CoreEventSource {
@@ -30,24 +29,15 @@ export interface CoreEventSource {
30
29
  dispose(): void;
31
30
  }
32
31
 
33
- /**
34
- * Read access to the live connection. The connector and options are not on the database's public
35
- * interface, so the code that installs the agent (which can see the concrete database) hands them in.
36
- */
37
- export interface ConnectionAccess {
38
- getConnector(): PowerSyncBackendConnector | null;
39
- getConnectionOptions(): SyncOptions | null;
40
- }
41
-
42
32
  export interface JsAgentOptions {
43
33
  /** A label for the SDK behind this agent, e.g. `@powersync/web`. */
44
34
  sdk?: string;
35
+ /** If known, the path to the database */
36
+ databasePath?: string;
45
37
  /** Debounce for re-reading bucket stats after internal-table changes. */
46
38
  bucketThrottleMs?: number;
47
39
  /** Core diagnostics events (per-bucket `target_count`). Omit when core diagnostics are off. */
48
40
  coreEvents?: CoreEventSource;
49
- /** Read access to the live connection; omit if the runtime cannot expose it. */
50
- connection?: ConnectionAccess;
51
41
  }
52
42
 
53
43
  /**
@@ -62,13 +52,13 @@ export class JsAgent implements SdkIntegration {
62
52
  /** Debug subscriptions created through `action`, keyed by name + params, so they can be released. */
63
53
  private streamHandles = new Map<string, SyncStreamSubscription>();
64
54
  // Retained so reconnect / clear work after a disconnect, when the connection no longer exposes them.
65
- private lastConnector: PowerSyncBackendConnector | null = null;
55
+ private lastConnector: InternalConnector | null = null;
66
56
  private lastConnectionOptions: SyncOptions | null = null;
67
57
  // Per-bucket total operation counts from the core diagnostics stream (not stored in ps_buckets).
68
58
  private bucketTargets = new Map<string, number>();
69
59
 
70
60
  constructor(
71
- private db: CommonPowerSyncDatabase,
61
+ private readonly db: BasePowerSyncDatabase,
72
62
  private options: JsAgentOptions = {}
73
63
  ) {}
74
64
 
@@ -86,12 +76,10 @@ export class JsAgent implements SdkIntegration {
86
76
  }
87
77
 
88
78
  async getInfo(): Promise<ProtocolInfo> {
89
- const connection = this.options.connection;
90
-
91
79
  let endpoint: string | null = null;
92
80
  let token: string | null = null;
93
81
  try {
94
- const credentials = await connection?.getConnector()?.fetchCredentials();
82
+ const credentials = await this.db.connector?.fetchCredentials?.();
95
83
  endpoint = credentials?.endpoint ?? null;
96
84
  token = credentials?.token ?? null;
97
85
  } catch {
@@ -113,7 +101,7 @@ export class JsAgent implements SdkIntegration {
113
101
  // Non-fatal.
114
102
  }
115
103
 
116
- const connectionOptions = connection?.getConnectionOptions() ?? null;
104
+ const connectionOptions = this.db.connectionOptions ?? null;
117
105
  return {
118
106
  endpoint,
119
107
  token,
@@ -122,7 +110,8 @@ export class JsAgent implements SdkIntegration {
122
110
  params: connectionOptions?.params ?? null,
123
111
  connected: this.db.currentStatus?.connected ?? false,
124
112
  sqliteCoreVersion,
125
- sdk: this.options.sdk ?? null
113
+ sdk: this.options.sdk ?? null,
114
+ databasePath: this.options.databasePath ?? null
126
115
  };
127
116
  }
128
117
 
@@ -344,17 +333,20 @@ export class JsAgent implements SdkIntegration {
344
333
  }
345
334
 
346
335
  private captureConnection(): void {
347
- const connection = this.options.connection;
348
- const connector = connection?.getConnector() ?? null;
336
+ const connector = this.db.connector ?? null;
349
337
  if (connector) {
350
338
  this.lastConnector = connector;
351
- this.lastConnectionOptions = connection?.getConnectionOptions() ?? null;
339
+ this.lastConnectionOptions = this.db.connectionOptions ?? null;
352
340
  }
353
341
  }
354
342
 
355
343
  private async reconnect(): Promise<void> {
356
344
  if (this.lastConnector) {
357
- await this.db.connect(this.lastConnector, this.lastConnectionOptions ?? undefined);
345
+ await this.db.connectionManager.connect(
346
+ this.lastConnector,
347
+ this.lastConnectionOptions ?? {},
348
+ this.db.schema.toJSON()
349
+ );
358
350
  }
359
351
  }
360
352
  }
@@ -363,11 +355,15 @@ function streamKey(name: string, params?: Record<string, unknown>): string {
363
355
  return `${name}|${JSON.stringify(params ?? null)}`;
364
356
  }
365
357
 
358
+ // The SDK's log levels. `typeof LogLevels` makes the compiler hold these to the values in
359
+ // `@powersync/common`, which stays a type-only import because it is an optional peer.
360
+ const LOG_LEVELS: typeof LogLevels = { trace: 10, debug: 20, info: 30, warn: 40, error: 50 };
361
+
366
362
  /** Maps a numeric SDK log level to its name. */
367
363
  function logLevelName(level: number): string {
368
- if (level >= 50) return 'error';
369
- if (level >= 40) return 'warn';
370
- if (level >= 30) return 'info';
371
- if (level >= 20) return 'debug';
364
+ if (level >= LOG_LEVELS.error) return 'error';
365
+ if (level >= LOG_LEVELS.warn) return 'warn';
366
+ if (level >= LOG_LEVELS.info) return 'info';
367
+ if (level >= LOG_LEVELS.debug) return 'debug';
372
368
  return 'trace';
373
369
  }
package/src/node.ts CHANGED
@@ -5,8 +5,9 @@
5
5
  import type { McpSetting } from 'devframe';
6
6
  import { createDevServer } from 'devframe/adapters/dev';
7
7
  import { buildOtpAuthUrl } from 'devframe/node/auth';
8
- import { createIntegration, type DiagnosableDatabase } from './agent.js';
9
- import { definition, registerIntegration } from './definition.js';
8
+ import type { CommonPowerSyncDatabase } from '@powersync/common';
9
+ import { createIntegration, databaseSdk } from './agent.js';
10
+ import { definition, registerIntegration, setSetupSdks } from './definition.js';
10
11
 
11
12
  export interface EnableDiagnosticsOptions {
12
13
  /**
@@ -23,7 +24,7 @@ export interface EnableDiagnosticsOptions {
23
24
  auth?: boolean;
24
25
  /** Open the browser once the server is up. @default false */
25
26
  open?: boolean;
26
- /** A label for the SDK, shown in the UI. @default '@powersync/node' */
27
+ /** A label for the SDK, shown in the UI. @default the database's SDK name */
27
28
  sdk?: string;
28
29
  /** The source id shown in the UI. @default 'node-1' */
29
30
  id?: string;
@@ -56,17 +57,19 @@ export interface DiagnosticsServer {
56
57
  * ```ts
57
58
  * const db = new PowerSyncDatabase({ ... });
58
59
  * if (process.env.NODE_ENV !== 'production') {
60
+ * const { enablePowerSyncDiagnostics } = await import('@powersync/diagnostics/node');
59
61
  * const devtools = await enablePowerSyncDiagnostics(db);
60
62
  * console.log(`PowerSync DevTools: ${devtools.signInUrl}`);
61
63
  * }
62
64
  * ```
63
65
  */
64
66
  export async function enablePowerSyncDiagnostics(
65
- db: DiagnosableDatabase,
67
+ db: CommonPowerSyncDatabase,
66
68
  options: EnableDiagnosticsOptions = {}
67
69
  ): Promise<DiagnosticsServer> {
68
- const sdk = options.sdk ?? '@powersync/node';
70
+ const sdk = options.sdk ?? databaseSdk(db, '@powersync/node');
69
71
  const detach = await registerIntegration(options.id ?? 'node-1', createIntegration(db, sdk), sdk);
72
+ setSetupSdks(['node']);
70
73
  const auth = options.auth ?? true;
71
74
  const server = await createDevServer(definition, {
72
75
  port: options.port ?? 0,
package/src/page.ts CHANGED
@@ -11,9 +11,7 @@ import {
11
11
  type SdkIntegration
12
12
  } from '@powersync/diagnostics-core';
13
13
  import { observeRegisteredDatabases } from '@powersync/web/devtools';
14
- import { createIntegration } from './agent.js';
15
-
16
- const SDK = '@powersync/web';
14
+ import { createIntegration, databaseSdk } from './agent.js';
17
15
 
18
16
  /**
19
17
  * Serves the app's first live database to any iframe that asks. Call once per page.
@@ -29,7 +27,7 @@ export function serveDiagnostics(): () => void {
29
27
  for (const stop of stops) stop();
30
28
  stops.clear();
31
29
  void integration?.close();
32
- integration = next ? createIntegration(next, SDK) : null;
30
+ integration = next ? createIntegration(next, databaseSdk(next, '@powersync/web')) : null;
33
31
  });
34
32
 
35
33
  const onMessage = (event: MessageEvent) => {
package/src/rpc-types.ts CHANGED
@@ -21,10 +21,14 @@ export interface SourceInfo {
21
21
  sdk: string | null;
22
22
  }
23
23
 
24
+ /** An SDK the UI's "no database" screens can explain, the same names the UI takes as `sdks`. */
25
+ export type SetupSdk = 'web' | 'nuxt' | 'node' | 'dart';
26
+
24
27
  declare module 'devframe/types' {
25
28
  /** Functions the node side serves; called by the UI, by agents over MCP, and by pages announcing a database. */
26
29
  interface DevframeRpcServerFunctions {
27
30
  'powersync:sources': () => SourceInfo[];
31
+ 'powersync:setup-sdks': () => SetupSdk[] | null;
28
32
  'powersync:query': (params: QueryParams, sourceId?: string | null) => Promise<QueryResult>;
29
33
  'powersync:schema': (sourceId?: string | null) => Promise<SchemaPayload>;
30
34
  'powersync:info': (sourceId?: string | null) => Promise<ProtocolInfo>;
package/src/vite.ts CHANGED
@@ -1,12 +1,18 @@
1
1
  import { createPluginFromDevframe } from '@vitejs/devtools-kit/node';
2
2
  import type { Plugin } from 'vite';
3
- import { definition } from './definition.js';
3
+ import { definition, setSetupSdks } from './definition.js';
4
+ import type { SetupSdk } from './rpc-types.js';
4
5
 
5
6
  const PLUGIN_NAME = 'powersync-diagnostics';
6
7
 
7
8
  export interface PowerSyncDevToolsOptions {
8
9
  /** Title of the dock entry. */
9
10
  title?: string;
11
+ /**
12
+ * The SDKs the setup screen explains when no database is attached. @default ['web']. A framework
13
+ * module built on this plugin passes its own, e.g. `['nuxt', 'web']`.
14
+ */
15
+ sdks?: SetupSdk[];
10
16
  }
11
17
 
12
18
  /**
@@ -25,6 +31,7 @@ export interface PowerSyncDevToolsOptions {
25
31
  * ```
26
32
  */
27
33
  export default function powersyncDevtools(options: PowerSyncDevToolsOptions = {}): Plugin {
34
+ setSetupSdks(options.sdks ?? ['web']);
28
35
  const plugin = createPluginFromDevframe(definition, { name: PLUGIN_NAME });
29
36
  plugin.devtools!.setup = async (context) => {
30
37
  // Frameworks that run a second Vite server for server-side rendering set it up too; the browser