@powersync/diagnostics 0.0.1 → 0.0.2

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.2",
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",
@@ -50,8 +50,8 @@
50
50
  },
51
51
  "homepage": "https://docs.powersync.com",
52
52
  "peerDependencies": {
53
- "@powersync/common": "^2.3.0",
54
- "@powersync/web": "^2.2.0",
53
+ "@powersync/common": "^2.4.0",
54
+ "@powersync/web": "^2.5.0",
55
55
  "@vitejs/devtools-kit": ">=0.7.5",
56
56
  "vite": ">=7.0.0"
57
57
  },
@@ -73,8 +73,8 @@
73
73
  "@devframes/agentic": "1.0.0",
74
74
  "devframe": "1.0.0",
75
75
  "zod": "^4.6.5",
76
- "@powersync/diagnostics-core": "0.0.1",
77
- "@powersync/diagnostics-ui": "0.0.1"
76
+ "@powersync/diagnostics-ui": "0.0.2",
77
+ "@powersync/diagnostics-core": "0.0.2"
78
78
  },
79
79
  "devDependencies": {
80
80
  "@devframes/hub": "1.0.0",
@@ -82,8 +82,8 @@
82
82
  "@vitejs/devtools-kit": "^0.7.5",
83
83
  "typescript": "^6.0.3",
84
84
  "vite": "^7.3.6",
85
- "@powersync/common": "2.3.0",
86
- "@powersync/web": "2.4.1"
85
+ "@powersync/common": "2.4.0",
86
+ "@powersync/web": "2.5.0"
87
87
  },
88
88
  "scripts": {
89
89
  "build": "tsc -b",
package/src/agent.ts CHANGED
@@ -20,10 +20,10 @@ import './rpc-types.js';
20
20
  const CORE_EVENTS_CHANNEL = 'powersync-diagnostics-events';
21
21
 
22
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.
23
+ * The connection accessors every SDK's database class has. They are not on the public
24
+ * `CommonPowerSyncDatabase` interface, so the agent reads them through this internal view.
25
25
  */
26
- export interface DiagnosableDatabase extends CommonPowerSyncDatabase {
26
+ interface DiagnosableDatabase extends CommonPowerSyncDatabase {
27
27
  readonly connector: PowerSyncBackendConnector | null | undefined;
28
28
  readonly connectionOptions: SyncOptions | null | undefined;
29
29
  }
@@ -44,7 +44,8 @@ class BroadcastCoreEvents implements CoreEventSource {
44
44
  }
45
45
 
46
46
  /** Builds the JavaScript integration over a live database. */
47
- export function createIntegration(db: DiagnosableDatabase, sdk: string): SdkIntegration {
47
+ export function createIntegration(database: CommonPowerSyncDatabase, sdk: string): SdkIntegration {
48
+ const db = database as DiagnosableDatabase;
48
49
  return new JsAgent(db, {
49
50
  sdk,
50
51
  coreEvents: typeof BroadcastChannel === 'function' ? new BroadcastCoreEvents() : undefined,
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,5 +1,6 @@
1
1
  import type {
2
2
  CommonPowerSyncDatabase,
3
+ LogLevels,
3
4
  LogRecord as SdkLogRecord,
4
5
  PowerSyncBackendConnector,
5
6
  SyncOptions,
@@ -363,11 +364,15 @@ function streamKey(name: string, params?: Record<string, unknown>): string {
363
364
  return `${name}|${JSON.stringify(params ?? null)}`;
364
365
  }
365
366
 
367
+ // The SDK's log levels. `typeof LogLevels` makes the compiler hold these to the values in
368
+ // `@powersync/common`, which stays a type-only import because it is an optional peer.
369
+ const LOG_LEVELS: typeof LogLevels = { trace: 10, debug: 20, info: 30, warn: 40, error: 50 };
370
+
366
371
  /** Maps a numeric SDK log level to its name. */
367
372
  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';
373
+ if (level >= LOG_LEVELS.error) return 'error';
374
+ if (level >= LOG_LEVELS.warn) return 'warn';
375
+ if (level >= LOG_LEVELS.info) return 'info';
376
+ if (level >= LOG_LEVELS.debug) return 'debug';
372
377
  return 'trace';
373
378
  }
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 } from './agent.js';
10
+ import { definition, registerIntegration, setSetupSdks } from './definition.js';
10
11
 
11
12
  export interface EnableDiagnosticsOptions {
12
13
  /**
@@ -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
70
  const sdk = options.sdk ?? '@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/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