@dxos/plugin-devtools 0.10.0

package/src/capabilities/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const AppGraphBuilder = Capability.lazy('AppGraphBuilder', () => import('./app-graph-builder'));
+export const ReactContext = Capability.lazy('ReactContext', () => import('./react-context'));
+export const ReactSurface = Capability.lazy('ReactSurface', () => import('./react-surface'));

package/src/capabilities/react-context.tsx

@@ -0,0 +1,25 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
+import { DevtoolsContextProvider } from '@dxos/devtools';
+
+import { meta } from '#meta';
+
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactContext, {
+      id: meta.profile.key,
+      context: ({ children }) => (
+        <Surface.ProfilerProvider>
+          <DevtoolsContextProvider>{children}</DevtoolsContextProvider>
+        </Surface.ProfilerProvider>
+      ),
+    }),
+  ),
+);

package/src/capabilities/react-surface.tsx

@@ -0,0 +1,331 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React, { useCallback } from 'react';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface, useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation, Paths } from '@dxos/app-toolkit';
+import { AppSurface, useActiveSpace } from '@dxos/app-toolkit/ui';
+import { EDGE_SERVICE_DEFAULTS, EdgeServiceName } from '@dxos/config';
+import {
+  AutomergePanel,
+  ConfigPanel,
+  CredentialsPanel,
+  DeviceListPanel,
+  DiagnosticsPanel,
+  EdgeDashboardPanel,
+  FeedsPanel,
+  IdentityPanel,
+  InvocationTraceContainer,
+  KeyringPanel,
+  LoggingPanel,
+  MembersPanel,
+  MetadataPanel,
+  NetworkPanel,
+  ObjectsPanel,
+  QueuesPanel,
+  SchemaPanel,
+  SignalPanel,
+  SpaceInfoPanel,
+  SpaceListPanel,
+  SqlitePanel,
+  StoragePanel,
+  SwarmPanel,
+  TestingPanel,
+  WorkflowPanel,
+} from '@dxos/devtools';
+import { Feed } from '@dxos/echo';
+import { log } from '@dxos/log';
+import { type Graph } from '@dxos/plugin-graph';
+import { ScriptOperation } from '@dxos/plugin-script';
+import { SpaceOperation } from '@dxos/plugin-space';
+import { type Space } from '@dxos/react-client/echo';
+import { ToolsExplorer } from '@dxos/react-ui-introspect';
+
+import { DebugGraph, DevtoolsOverviewContainer, RegistryPanel } from '#containers';
+import { Devtools } from '#types';
+
+const MCP_SERVER_URL = EDGE_SERVICE_DEFAULTS[EdgeServiceName.Introspect];
+
+type GraphDebug = {
+  graph: Graph.Graph;
+  root: string;
+};
+
+const isGraphDebug = (data: any): data is GraphDebug => {
+  const graph = data?.graph;
+  return (
+    graph != null && typeof graph === 'object' && typeof graph.json === 'function' && typeof data?.root === 'string'
+  );
+};
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'appGraph',
+        filter: AppSurface.subject(AppSurface.Article, isGraphDebug),
+        component: ({ data }) => <DebugGraph graph={data.subject.graph} root={data.subject.root} />,
+      }),
+      Surface.create({
+        id: 'toolsExplorer',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.ToolsExplorer),
+        component: () => <ToolsExplorer serverUrl={MCP_SERVER_URL} />,
+      }),
+      Surface.create({
+        id: 'registry',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Echo.Registry),
+        component: () => <RegistryPanel />,
+      }),
+      Surface.create({
+        id: 'devtoolsOverview',
+        filter: Surface.makeFilter(AppSurface.deckCompanion('devtoolsOverview')),
+        component: () => <DevtoolsOverviewContainer />,
+      }),
+
+      //
+      // Devtools
+      //
+
+      Surface.create({
+        id: 'client.config',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Client.Config),
+        component: () => <ConfigPanel vaultSelector={false} />,
+      }),
+      Surface.create({
+        id: 'client.storage',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Client.Storage),
+        component: () => <StoragePanel />,
+      }),
+      Surface.create({
+        id: 'client.sqlite',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Client.Sqlite),
+        component: () => <SqlitePanel />,
+      }),
+      Surface.create({
+        id: 'client.logs',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Client.Logs),
+        component: () => <LoggingPanel />,
+      }),
+      Surface.create({
+        id: 'client.diagnostics',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Client.Diagnostics),
+        component: () => <DiagnosticsPanel />,
+      }),
+      Surface.create({
+        id: 'halo.identity',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Halo.Identity),
+        component: () => <IdentityPanel />,
+      }),
+      Surface.create({
+        id: 'halo.devices',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Halo.Devices),
+        component: () => <DeviceListPanel />,
+      }),
+      Surface.create({
+        id: 'halo.keyring',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Halo.Keyring),
+        component: () => <KeyringPanel />,
+      }),
+      Surface.create({
+        id: 'halo.credentials',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Halo.Credentials),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
+
+          return <CredentialsPanel space={space} />;
+        },
+      }),
+      Surface.create({
+        id: 'echo.spaces',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Echo.Spaces),
+        component: () => {
+          const { invokePromise } = useOperationInvoker();
+          const handleSelect = useCallback(
+            () => invokePromise(LayoutOperation.Open, { subject: [Devtools.Echo.Space] }),
+            [invokePromise],
+          );
+          return <SpaceListPanel onSelect={handleSelect} />;
+        },
+      }),
+      Surface.create({
+        id: 'echo.space',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Echo.Space),
+        component: () => {
+          const space = useActiveSpace();
+          const { invokePromise } = useOperationInvoker();
+          const handleSelect = useCallback(
+            () => invokePromise(LayoutOperation.Open, { subject: [Devtools.Echo.Feeds] }),
+            [invokePromise],
+          );
+          if (!space) {
+            return null;
+          }
+
+          return <SpaceInfoPanel space={space} onSelectFeed={handleSelect} onSelectPipeline={handleSelect} />;
+        },
+      }),
+      Surface.create({
+        id: 'echo.feeds',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Echo.Feeds),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
+
+          return <FeedsPanel space={space} />;
+        },
+      }),
+      Surface.create({
+        id: 'echo.objects',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Echo.Objects),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
+
+          return <ObjectsPanel space={space} />;
+        },
+      }),
+      Surface.create({
+        id: 'echo.schema',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Echo.Schema),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
+
+          return <SchemaPanel space={space} />;
+        },
+      }),
+      Surface.create({
+        id: 'echo.automerge',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Echo.Automerge),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
+
+          return <AutomergePanel space={space} />;
+        },
+      }),
+      Surface.create({
+        id: 'echo.queues',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Echo.Queues),
+        component: () => <QueuesPanel />,
+      }),
+      Surface.create({
+        id: 'echo.members',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Echo.Members),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
+
+          return <MembersPanel space={space} />;
+        },
+      }),
+      Surface.create({
+        id: 'echo.metadata',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Echo.Metadata),
+        component: () => <MetadataPanel />,
+      }),
+      Surface.create({
+        id: 'mesh.signal',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Mesh.Signal),
+        component: () => <SignalPanel />,
+      }),
+      Surface.create({
+        id: 'mesh.swarm',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Mesh.Swarm),
+        component: () => <SwarmPanel />,
+      }),
+      Surface.create({
+        id: 'mesh.network',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Mesh.Network),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
+
+          return <NetworkPanel space={space} />;
+        },
+      }),
+      Surface.create({
+        id: 'edge.dashboard',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Edge.Dashboard),
+        component: () => <EdgeDashboardPanel />,
+      }),
+      Surface.create({
+        id: 'edge.workflows',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Edge.Workflows),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
+
+          return <WorkflowPanel space={space} />;
+        },
+      }),
+      Surface.create({
+        id: 'edge.traces',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Edge.Traces),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
+
+          const feed = space.properties.invocationTraceFeed?.target;
+          const feedDXN = feed ? Feed.getFeedUri(feed) : undefined;
+          return <InvocationTraceContainer db={space.db} feedDXN={feedDXN} detailAxis='block' />;
+        },
+      }),
+      Surface.create({
+        id: 'edge.testing',
+        filter: AppSurface.literal(AppSurface.Article, Devtools.Edge.Testing),
+        component: () => {
+          const { invokePromise } = useOperationInvoker();
+          const onSpaceCreate = useCallback(
+            async (space: Space) => {
+              await space.waitUntilReady();
+              await invokePromise(SpaceOperation.Migrate, { space });
+              await space.db.flush();
+            },
+            [invokePromise],
+          );
+          const onScriptPluginOpen = useCallback(
+            async (space: Space) => {
+              await space.waitUntilReady();
+              const createResult = await invokePromise(ScriptOperation.CreateScript, { db: space.db });
+              if (createResult.data?.object) {
+                await invokePromise(SpaceOperation.AddObject, { target: space.db, object: createResult.data.object });
+              }
+              log.info('script created', { result: createResult });
+              if (createResult.data?.object) {
+                await invokePromise(LayoutOperation.Open, {
+                  subject: [Paths.getObjectPathFromObject(createResult.data.object)],
+                });
+              }
+            },
+            [invokePromise],
+          );
+          return <TestingPanel onSpaceCreate={onSpaceCreate} onScriptPluginOpen={onScriptPluginOpen} />;
+        },
+      }),
+    ]);
+  }),
+);

package/src/containers/DebugGraph/DebugGraph.tsx

@@ -0,0 +1,16 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React from 'react';
+
+import { Tree } from '@dxos/devtools';
+import { Graph } from '@dxos/plugin-graph';
+
+export type DebugGraphProps = { graph: Graph.Graph; root: string };
+
+export const DebugGraph = ({ graph, root }: DebugGraphProps) => {
+  return <Tree data={Graph.toJSON(graph, root)} />;
+};
+
+DebugGraph.displayName = 'DebugGraph';

package/src/containers/DebugGraph/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export { DebugGraph as default } from './DebugGraph';

package/src/containers/DevtoolsOverviewContainer/DevtoolsOverviewContainer.tsx

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback, useMemo } from 'react';
+
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { StatsPanel, useStats } from '@dxos/devtools';
+
+export const DevtoolsOverviewContainer = () => {
+  const [stats, refreshStats] = useStats();
+  const surfaceProfilerStats = Surface.useProfilerStats();
+  const surfaceMetrics = Surface.useMetrics();
+  const clearSurfaceProfiler = Surface.useProfilerClear();
+
+  // The panel joins profiler stats with dispatch metrics, so reset must clear both.
+  const handleClearSurfaceProfiler = useCallback(() => {
+    clearSurfaceProfiler?.();
+    Surface.clearMetrics();
+  }, [clearSurfaceProfiler]);
+
+  // Join dispatch metrics onto the render-timing stats (both keyed by `surface/<id>/<role>`).
+  const enrichedStats = useMemo(() => {
+    const byId = new Map(surfaceMetrics.map((metric) => [metric.id, metric]));
+    return surfaceProfilerStats.map((stat) => {
+      const metric = byId.get(stat.id);
+      return metric
+        ? {
+            ...stat,
+            candidates: metric.candidates,
+            truncated: metric.truncated,
+            errors: metric.errors,
+            dataUnstable: metric.dataUnstable,
+          }
+        : stat;
+    });
+  }, [surfaceProfilerStats, surfaceMetrics]);
+
+  return (
+    <StatsPanel
+      stats={stats}
+      surfaceProfilerStats={enrichedStats}
+      onRefresh={refreshStats}
+      onClearSurfaceProfiler={handleClearSurfaceProfiler}
+    >
+      <Surface.Surface type={AppSurface.DevtoolsOverview} />
+    </StatsPanel>
+  );
+};
+
+DevtoolsOverviewContainer.displayName = 'DevtoolsOverviewContainer';

package/src/containers/DevtoolsOverviewContainer/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { DevtoolsOverviewContainer as default } from './DevtoolsOverviewContainer';

package/src/containers/GithubPanel/GithubComponent.stories.tsx

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { GithubComponent } from './GithubComponent';
+
+const DefaultStory = () => (
+  <GithubComponent.Root>
+    <div className='grid grid-rows-[auto_minmax(0,1fr)_auto] overflow-hidden h-full is-full'>
+      <GithubComponent.Header />
+      <GithubComponent.Content />
+      <GithubComponent.StatusBar />
+    </div>
+  </GithubComponent.Root>
+);
+
+const meta = {
+  title: 'plugins/plugin-devtools/containers/GithubComponent',
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'w-(--dx-r1-size)' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/containers/GithubPanel/GithubComponent.tsx

@@ -0,0 +1,192 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type ReactNode, createContext, useContext, useEffect, useState } from 'react';
+
+import { IconButton, ScrollArea, useTranslation } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+
+const DEFAULT_REPO = 'dxos/dxos';
+const DEFAULT_LIMIT = 20;
+
+type GithubUser = {
+  login: string;
+  avatar_url: string;
+  html_url: string;
+};
+
+type GithubPullRequest = {
+  number: number;
+  title: string;
+  html_url: string;
+  merged_at: string | null;
+  user: GithubUser;
+};
+
+type ComponentContextValue = {
+  repo: string;
+  pulls: GithubPullRequest[];
+  unavailable: boolean;
+};
+
+const ComponentContext = createContext<ComponentContextValue | null>(null);
+
+const useComponentContext = () => {
+  const ctx = useContext(ComponentContext);
+  if (!ctx) {
+    throw new Error('GithubComponent.* parts must be rendered inside GithubComponent.Root.');
+  }
+  return ctx;
+};
+
+export type GithubComponentRootProps = {
+  /** `<owner>/<name>`. Defaults to `dxos/dxos`. */
+  repo?: string;
+  /** Maximum number of merged PRs to fetch. */
+  limit?: number;
+  children?: ReactNode;
+};
+
+const Root = ({ repo = DEFAULT_REPO, limit = DEFAULT_LIMIT, children }: GithubComponentRootProps) => {
+  const [pulls, setPulls] = useState<GithubPullRequest[]>([]);
+  const [unavailable, setUnavailable] = useState(false);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    setPulls([]);
+    setUnavailable(false);
+    void (async () => {
+      try {
+        const url = new URL(`https://api.github.com/repos/${repo}/pulls`);
+        url.searchParams.set('state', 'closed');
+        url.searchParams.set('sort', 'updated');
+        url.searchParams.set('direction', 'desc');
+        url.searchParams.set('per_page', String(limit * 2));
+        const response = await fetch(url.toString(), {
+          signal: controller.signal,
+          headers: { Accept: 'application/vnd.github+json' },
+        });
+        if (!response.ok) {
+          setUnavailable(true);
+          return;
+        }
+        const items = (await response.json()) as GithubPullRequest[];
+        setPulls(items.filter((pull) => pull.merged_at !== null).slice(0, limit));
+        setUnavailable(false);
+      } catch {
+        if (controller.signal.aborted) {
+          return;
+        }
+        setPulls([]);
+        setUnavailable(true);
+      }
+    })();
+    return () => controller.abort();
+  }, [repo, limit]);
+
+  return <ComponentContext.Provider value={{ repo, pulls, unavailable }}>{children}</ComponentContext.Provider>;
+};
+
+const Header = () => {
+  const { t } = useTranslation(meta.profile.key);
+  const { repo, pulls, unavailable } = useComponentContext();
+  return (
+    <header className='flex items-center justify-between gap-1 px-4 py-3 bg-modal-surface border-b border-subdued-separator'>
+      <a
+        href={`https://github.com/${repo}`}
+        target='_blank'
+        rel='noopener noreferrer'
+        className='text-sm font-medium truncate'
+      >
+        @{repo}
+      </a>
+      <div className='text-xs text-description'>
+        {unavailable
+          ? t('github-unavailable.message')
+          : pulls.length > 0
+            ? t('recent-prs.label', { count: pulls.length })
+            : t('github-loading.message')}
+      </div>
+    </header>
+  );
+};
+
+const RELATIVE_UNITS: Array<[Intl.RelativeTimeFormatUnit, number]> = [
+  ['year', 60 * 60 * 24 * 365],
+  ['month', 60 * 60 * 24 * 30],
+  ['week', 60 * 60 * 24 * 7],
+  ['day', 60 * 60 * 24],
+  ['hour', 60 * 60],
+  ['minute', 60],
+];
+
+const formatRelative = (iso: string): string => {
+  const formatter = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' });
+  const diffSeconds = (Date.parse(iso) - Date.now()) / 1000;
+  const absDiff = Math.abs(diffSeconds);
+  for (const [unit, secondsInUnit] of RELATIVE_UNITS) {
+    if (absDiff >= secondsInUnit) {
+      return formatter.format(Math.round(diffSeconds / secondsInUnit), unit);
+    }
+  }
+  return formatter.format(Math.round(diffSeconds), 'second');
+};
+
+const PullRow = ({ pull }: { pull: GithubPullRequest }) => (
+  <li>
+    <a
+      href={pull.html_url}
+      target='_blank'
+      rel='noopener noreferrer'
+      className='flex items-start gap-2 px-2 py-1 rounded-sm hover:bg-hover-surface'
+    >
+      <img src={pull.user.avatar_url} alt='' className='w-6 h-6 rounded-full shrink-0 mt-0.5' />
+      <div className='flex flex-col min-w-0 flex-1'>
+        <span className='text-sm truncate'>{pull.title}</span>
+        <span className='text-xs text-description truncate'>
+          #{pull.number} · {pull.user.login} · {pull.merged_at ? formatRelative(pull.merged_at) : ''}
+        </span>
+      </div>
+    </a>
+  </li>
+);
+
+const Content = () => {
+  const { pulls } = useComponentContext();
+  return (
+    <ScrollArea.Root orientation='vertical'>
+      <ScrollArea.Viewport>
+        <ul className='flex flex-col p-1'>
+          {pulls.map((pull) => (
+            <PullRow key={pull.number} pull={pull} />
+          ))}
+        </ul>
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};
+
+const StatusBar = () => {
+  const { t } = useTranslation(meta.profile.key);
+  const { repo } = useComponentContext();
+  return (
+    <IconButton
+      icon='ph--github-logo--regular'
+      label={t('view-on-github.button')}
+      variant='primary'
+      classNames='w-full'
+      onClick={() => {
+        window.open(`https://github.com/${repo}`, '_blank', 'noopener,noreferrer');
+      }}
+    />
+  );
+};
+
+export const GithubComponent = {
+  Root,
+  Header,
+  Content,
+  StatusBar,
+};

package/src/containers/GithubPanel/GithubPanel.tsx

@@ -0,0 +1,19 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { GithubComponent } from './GithubComponent';
+
+export const GithubPanel = () => (
+  <GithubComponent.Root>
+    <div className='h-full grid grid-rows-[auto_minmax(0,1fr)_auto] overflow-hidden h-full is-full'>
+      <GithubComponent.Header />
+      <GithubComponent.Content />
+      <GithubComponent.StatusBar />
+    </div>
+  </GithubComponent.Root>
+);
+
+GithubPanel.displayName = 'GithubPanel';