@powersync/diagnostics 0.0.0-dev-20261020125654

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 (56) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +138 -0
  3. package/lib/src/agent-server.d.ts +21 -0
  4. package/lib/src/agent-server.js +51 -0
  5. package/lib/src/agent-server.js.map +1 -0
  6. package/lib/src/agent.d.ts +11 -0
  7. package/lib/src/agent.js +30 -0
  8. package/lib/src/agent.js.map +1 -0
  9. package/lib/src/client.d.ts +7 -0
  10. package/lib/src/client.js +30 -0
  11. package/lib/src/client.js.map +1 -0
  12. package/lib/src/constants.d.ts +13 -0
  13. package/lib/src/constants.js +14 -0
  14. package/lib/src/constants.js.map +1 -0
  15. package/lib/src/definition.d.ts +16 -0
  16. package/lib/src/definition.js +421 -0
  17. package/lib/src/definition.js.map +1 -0
  18. package/lib/src/index.d.ts +4 -0
  19. package/lib/src/index.js +6 -0
  20. package/lib/src/index.js.map +1 -0
  21. package/lib/src/js-agent.d.ts +63 -0
  22. package/lib/src/js-agent.js +298 -0
  23. package/lib/src/js-agent.js.map +1 -0
  24. package/lib/src/node.d.ts +59 -0
  25. package/lib/src/node.js +40 -0
  26. package/lib/src/node.js.map +1 -0
  27. package/lib/src/page.d.ts +5 -0
  28. package/lib/src/page.js +50 -0
  29. package/lib/src/page.js.map +1 -0
  30. package/lib/src/rpc-types.d.ts +42 -0
  31. package/lib/src/rpc-types.js +2 -0
  32. package/lib/src/rpc-types.js.map +1 -0
  33. package/lib/src/sync-state.d.ts +4 -0
  34. package/lib/src/sync-state.js +53 -0
  35. package/lib/src/sync-state.js.map +1 -0
  36. package/lib/src/vite-static.d.ts +18 -0
  37. package/lib/src/vite-static.js +67 -0
  38. package/lib/src/vite-static.js.map +1 -0
  39. package/lib/src/vite.d.ts +27 -0
  40. package/lib/src/vite.js +43 -0
  41. package/lib/src/vite.js.map +1 -0
  42. package/lib/tsconfig.tsbuildinfo +1 -0
  43. package/package.json +98 -0
  44. package/src/agent-server.ts +73 -0
  45. package/src/agent.ts +58 -0
  46. package/src/client.ts +37 -0
  47. package/src/constants.ts +15 -0
  48. package/src/definition.ts +504 -0
  49. package/src/index.ts +7 -0
  50. package/src/js-agent.ts +378 -0
  51. package/src/node.ts +89 -0
  52. package/src/page.ts +61 -0
  53. package/src/rpc-types.ts +55 -0
  54. package/src/sync-state.ts +61 -0
  55. package/src/vite-static.ts +83 -0
  56. package/src/vite.ts +55 -0
@@ -0,0 +1,83 @@
1
+ import { createReadStream, existsSync, readFileSync, statSync } from 'node:fs';
2
+ import type { ServerResponse } from 'node:http';
3
+ import { extname, join, normalize } from 'node:path';
4
+ import type { Plugin, ViteDevServer } from 'vite';
5
+ import { UI_ROUTE } from './constants.js';
6
+ import { uiDistDir } from './definition.js';
7
+
8
+ const MIME: Record<string, string> = {
9
+ '.html': 'text/html; charset=utf-8',
10
+ '.js': 'text/javascript; charset=utf-8',
11
+ '.css': 'text/css; charset=utf-8',
12
+ '.json': 'application/json; charset=utf-8',
13
+ '.svg': 'image/svg+xml',
14
+ '.woff2': 'font/woff2',
15
+ '.map': 'application/json; charset=utf-8'
16
+ };
17
+
18
+ export interface PowersyncStaticOptions {
19
+ /**
20
+ * URLs of scripts to run inside the UI page, added as `<script type="module">` tags. For a host
21
+ * that has to bridge something from its own environment into the page, such as its theme, without
22
+ * the UI knowing the host.
23
+ */
24
+ scripts?: string[];
25
+ }
26
+
27
+ /**
28
+ * Serves the diagnostics UI at {@link UI_ROUTE} from a plain Vite dev server, with no devframe hub.
29
+ *
30
+ * For hosts that embed the UI in their own iframe and hand it the integration over `postMessage`:
31
+ * Nuxt DevTools v3 does this, with `./page` loaded in the app. The UI is a static page outside the
32
+ * app's router, so no route guard or auth middleware applies to it. Serve-only; nothing reaches a
33
+ * production build.
34
+ */
35
+ export default function powersyncStatic(options: PowersyncStaticOptions = {}): Plugin {
36
+ const distDir = uiDistDir();
37
+ return {
38
+ name: 'powersync-diagnostics-static',
39
+ apply: 'serve',
40
+ configureServer(server: ViteDevServer) {
41
+ server.middlewares.use(UI_ROUTE.slice(0, -1), serveStatic(distDir, options.scripts ?? []));
42
+ }
43
+ };
44
+ }
45
+
46
+ /** The page with the host's script tags added before `</head>`. */
47
+ function pageWithScripts(indexPath: string, scripts: string[]): string {
48
+ const html = readFileSync(indexPath, 'utf8');
49
+ if (scripts.length === 0) return html;
50
+ const tags = scripts.map((src) => `<script type="module" src="${src}"></script>`).join('');
51
+ return html.includes('</head>') ? html.replace('</head>', `${tags}</head>`) : tags + html;
52
+ }
53
+
54
+ /** Serves the built UI from `root`. Unknown extension-less paths fall back to `index.html` for the page itself. */
55
+ function serveStatic(root: string, scripts: string[]) {
56
+ return (request: { url?: string }, response: ServerResponse, next: () => void) => {
57
+ const requestPath = decodeURIComponent((request.url ?? '/').split('?')[0]);
58
+ // Resolve inside the dist dir only; a path that escapes it is not served.
59
+ const relative = normalize(requestPath === '/' || requestPath === '' ? 'index.html' : requestPath).replace(
60
+ /^(\.\.[/\\])+/,
61
+ ''
62
+ );
63
+ const filePath = join(root, relative);
64
+ if (!filePath.startsWith(root)) {
65
+ return next();
66
+ }
67
+ const exists = existsSync(filePath) && statSync(filePath).isFile();
68
+ if (!exists && extname(relative)) {
69
+ // A missing file (for example a devframe probe for `__connection.json`) is a 404, not the page.
70
+ response.statusCode = 404;
71
+ response.end();
72
+ return;
73
+ }
74
+ const target = exists ? filePath : join(root, 'index.html');
75
+ response.setHeader('Content-Type', MIME[extname(target)] ?? 'application/octet-stream');
76
+ response.setHeader('Cache-Control', 'no-store');
77
+ if (extname(target) === '.html') {
78
+ response.end(pageWithScripts(target, scripts));
79
+ return;
80
+ }
81
+ createReadStream(target).pipe(response);
82
+ };
83
+ }
package/src/vite.ts ADDED
@@ -0,0 +1,55 @@
1
+ import { createPluginFromDevframe } from '@vitejs/devtools-kit/node';
2
+ import type { Plugin } from 'vite';
3
+ import { definition, setSetupSdks } from './definition.js';
4
+ import type { SetupSdk } from './rpc-types.js';
5
+
6
+ const PLUGIN_NAME = 'powersync-diagnostics';
7
+
8
+ export interface PowerSyncDevToolsOptions {
9
+ /** Title of the dock entry. */
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[];
16
+ }
17
+
18
+ /**
19
+ * Mounts PowerSync diagnostics into Vite DevTools.
20
+ *
21
+ * The definition becomes a dock: the diagnostics UI in an iframe, a client script in the app page
22
+ * that serves the app's live databases, and the same functions exposed to agents over MCP at
23
+ * `/__devtools/__mcp`. Requires Vite DevTools (Vite >= 8.3 with `devtools: true`, or the
24
+ * `@vitejs/devtools` plugin). Nothing is added to a production build.
25
+ *
26
+ * @example
27
+ * ```ts
28
+ * // vite.config.ts
29
+ * import powersyncDevtools from '@powersync/diagnostics/vite';
30
+ * export default defineConfig({ devtools: true, plugins: [powersyncDevtools()] });
31
+ * ```
32
+ */
33
+ export default function powersyncDevtools(options: PowerSyncDevToolsOptions = {}): Plugin {
34
+ setSetupSdks(options.sdks ?? ['web']);
35
+ const plugin = createPluginFromDevframe(definition, { name: PLUGIN_NAME });
36
+ plugin.devtools!.setup = async (context) => {
37
+ // Frameworks that run a second Vite server for server-side rendering set it up too; the browser
38
+ // never talks to that server, so the definition mounts on the client-facing one only.
39
+ if (context.viteConfig?.build?.ssr) return;
40
+ const base = (context.viteConfig?.base ?? '/').replace(/\/?$/, '/');
41
+ const mount = createPluginFromDevframe(definition, {
42
+ name: PLUGIN_NAME,
43
+ dock: {
44
+ ...(options.title ? { title: options.title } : {}),
45
+ // Vite serves any module at `<base>@id/<specifier>`. Naming that URL here, instead of the bare
46
+ // specifier the definition carries, keeps the server's `base` (Nuxt serves Vite at `/_nuxt/`),
47
+ // which the host's own `/@id/{specifier}` template drops, and spares the host a warning about
48
+ // a bare specifier it checks before it has advertised that template.
49
+ clientScript: { importFrom: `${base}@id/${definition.packageName}/client`, eager: true }
50
+ }
51
+ });
52
+ await mount.devtools?.setup(context);
53
+ };
54
+ return plugin;
55
+ }