@dxos/plugin-debug 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 → 0.13.0

package/src/samples/worker/tasks.ts

@@ -0,0 +1,119 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { EntityId } from '@dxos/echo/Key';
+import { Actor, Task, TaskSet } from '@dxos/types';
+
+import { daysAgo } from './util.ts';
+
+//
+// Five steps, flat and in order.
+//
+// Flat on purpose: the whole run is one afternoon's work, and a tree would imply stages that can be
+// planned against each other. Everything is `todo` — this is a plan to run, not a project caught
+// mid-flight — and each step depends on the one before it, so a runner working ahead is visibly out
+// of order rather than merely early.
+//
+
+type TaskSeed = {
+  readonly title: string;
+  readonly description: string;
+  readonly estimate?: Task.Estimate;
+  /** Set where the step needs the reader's own hands — here, the one browser consent screen. */
+  readonly assignee?: Actor.Actor;
+};
+
+/**
+ * The reader, as an assignee. A template cannot know who they are, so the actor carries the role and
+ * a label rather than a Person ref — enough for the row to say the step is not the agent's.
+ */
+const USER: Actor.Actor = { role: 'user', name: 'You' };
+
+const STEPS: ReadonlyArray<TaskSeed> = [
+  {
+    title: 'Create a sandbox and install wrangler',
+    description:
+      'One sandbox for the whole run — it keeps its filesystem between commands, so a second one pays for node and wrangler again. `--temporary` needs wrangler 4.102 or later and that wrangler needs Node 22, while the sandbox runs Node 20: install `wrangler@latest` explicitly and run its script under a newer node — `npx --yes node@22 node_modules/wrangler/bin/wrangler.js` — since a plain install resolves to the last version that fits Node 20 and has no flag. Creating one and running commands in it belong to the Sandbox skill.',
+    estimate: 's',
+  },
+  {
+    title: 'Write the Worker',
+    description:
+      "A TypeScript Worker whose fetch handler answers every request with JSON: a greeting and the current UTC time. No router, no dependencies, no build step beyond wrangler's own.",
+    estimate: 'xs',
+  },
+  {
+    title: 'Deploy it with no Cloudflare login',
+    description:
+      '`wrangler deploy --temporary` mints a temporary account and prints a Worker URL and a claim URL; plain `wrangler deploy` refuses non-interactively and demands a token, so the flag is not optional. File the Worker URL on the project. The claim URL is a bearer credential — hand it straight to me and file it nowhere.',
+    estimate: 's',
+  },
+  {
+    title: 'Fetch the deployed URL and check the response',
+    description:
+      'Fetch it and paste the body into the project. A deploy command that exited zero is not evidence that anything is serving.',
+    estimate: 'xs',
+  },
+  {
+    title: 'Claim the temporary Cloudflare account',
+    description:
+      'Yours to do: claiming signs the account into yours, which needs a browser the agent does not have. It comes after the last deploy — an agent with no login cannot update a claimed account, and `--temporary` would mint a second one under a different URL. Do it inside the hour; the account expires with the Worker on it.',
+    estimate: 'xs',
+    assignee: USER,
+  },
+];
+
+export type TasksResult = { taskSet: TaskSet.TaskSet; tasks: Task.Task[] };
+
+/** The five steps, each depending on the one before it. */
+export const Tasks: SampleSpace.Phase<TasksResult> = SampleSpace.phase('tasks', {
+  schemas: [TaskSet.TaskSet, Task.Task],
+  run: () =>
+    Effect.gen(function* () {
+      const taskSet = yield* Database.add(
+        TaskSet.make({
+          name: 'Hello Worker',
+          description: 'From an empty sandbox to a URL that answers.',
+        }),
+      );
+
+      const tasks = STEPS.map((step) =>
+        Task.make({
+          title: step.title,
+          description: step.description,
+          estimate: step.estimate,
+          assignee: step.assignee,
+          status: 'todo',
+          // Task carries no due date; its dates are activity-log lines, so that is where they go.
+          history: [
+            {
+              id: EntityId.random(),
+              date: daysAgo(0),
+              event: 'created' as const,
+              description: 'Filed from the worker template.',
+            },
+          ],
+        }),
+      );
+      yield* SampleSpace.children(taskSet, tasks, (taskSet, refs) => {
+        taskSet.tasks = refs;
+      });
+
+      // Nothing can be deployed before it is written, and nothing claimed before it is deployed.
+      for (const [index, task] of tasks.entries()) {
+        if (index > 0) {
+          const previous = tasks[index - 1];
+          Obj.update(task, (task) => {
+            task.dependsOn = [Ref.make(previous)];
+          });
+        }
+      }
+
+      return { taskSet, tasks };
+    }),
+});

package/src/samples/worker/util.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+
+/** Stable reference date so regenerations are reproducible. Override with NOW=2026-05-20 env. */
+export const REFERENCE = process.env.NOW ? new Date(process.env.NOW) : new Date('2026-05-20T15:00:00Z');
+
+/**
+ * Bound to the same reference the definition declares, so the pure content builders can date their
+ * objects without every one of them being an effect.
+ */
+export const clock = SampleSpace.makeClock(REFERENCE);
+
+/** ISO timestamp that many days before {@link REFERENCE}, at an optional UTC hour of that day. */
+export const daysAgo = clock.daysAgo;

package/src/stories/SpaceTemplates.stories.tsx

@@ -0,0 +1,105 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { ClientPlugin, initializeIdentity } from '@dxos/plugin-client/testing';
+import * as ProgressPlugin from '@dxos/plugin-progress/ProgressPlugin';
+import { SpacePlugin } from '@dxos/plugin-space/testing';
+import * as CorePlugins from '@dxos/plugin-testing/CorePlugins';
+import * as StorybookPlugin from '@dxos/plugin-testing/StorybookPlugin';
+import { useSpaces } from '@dxos/react-client/echo';
+import { Loading, withLayout } from '@dxos/react-ui/testing';
+
+import { DebugSpaceObjectsPanel, SpaceGenerator } from '#containers';
+import { translations } from '#translations';
+
+import * as DebugPlugin from '../DebugPlugin.ts';
+
+/**
+ * Picking a space template and watching it land.
+ */
+const DefaultStory = () => {
+  const [space] = useSpaces();
+  if (!space) {
+    return <Loading />;
+  }
+
+  return (
+    <div className='dx-expand grid grid-cols-2 divide-x divide-separator'>
+      <SpaceGenerator space={space} />
+      <DebugSpaceObjectsPanel space={space} attendableId={space.id} />
+    </div>
+  );
+};
+
+/** Applies a template by label, then waits for the object tree to show something it built. */
+const applyTemplate = async (canvasElement: HTMLElement, label: string, expected: string) => {
+  const canvas = within(canvasElement);
+  // The contributing plugins activate on mount, so the row appears asynchronously.
+  const create = await canvas.findByRole('button', { name: `Create ${label}` }, { timeout: 20_000 });
+  await userEvent.click(create);
+  // `getAllByText`: a template may name two objects the same (Tidepool's task set and its
+  // project are both "Offline sync v2"), and `getByText` throws on more than one match.
+  await waitFor(() => expect(canvas.getAllByText(expected).length).toBeGreaterThan(0), { timeout: 30_000 });
+  // The first object appears long before the world is finished, and the row disables itself for as
+  // long as the generator runs: returning here left writes in flight, and teardown closed the
+  // client's RPC endpoint under them.
+  await waitFor(() => expect(create).toBeEnabled(), { timeout: 30_000 });
+};
+
+const meta = {
+  title: 'plugins/plugin-debug/stories/SpaceTemplates',
+  render: DefaultStory,
+  decorators: [
+    withLayout({ layout: 'fullscreen' }),
+    withPluginManager(() => ({
+      plugins: [
+        ...CorePlugins.make(),
+        StorybookPlugin.make({}),
+        ProgressPlugin.make(),
+        ClientPlugin.make({
+          onClientInitialized: ({ client }) =>
+            Effect.gen(function* () {
+              yield* initializeIdentity(client);
+            }),
+        }),
+        // Contributes the operation handlers the generators invoke (e.g. `SpaceOperation.AddType`).
+        SpacePlugin({}),
+        // This plugin contributes the space templates, and the panel below is rendered directly
+        // rather than through a surface — so without the plugin in the list nothing ever activates
+        // the module that registers them and the picker stays empty.
+        DebugPlugin.make(),
+      ],
+    })),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    controls: { disable: true },
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** Empty space plus the picker — click a template to fill it. */
+export const Default: Story = {};
+
+export const Tidepool: Story = {
+  play: async ({ canvasElement }) => {
+    await applyTemplate(canvasElement, 'Tidepool — Offline sync v2', 'Offline sync v2');
+  },
+};
+
+export const Northwind: Story = {
+  play: async ({ canvasElement }) => {
+    await applyTemplate(canvasElement, 'Northwind Sales', 'Sales pipeline');
+  },
+};

package/src/testing/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './stub-tools-plugin.tsx';
+export * from './stub-drawer-plugin.ts';

package/src/testing/stub-drawer-plugin.ts

@@ -0,0 +1,65 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { useSyncExternalStore } from 'react';
+
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import * as Plugin from '@dxos/app-framework/Plugin';
+import * as LayoutOperation from '@dxos/app-toolkit/LayoutOperation';
+import * as Operation from '@dxos/compute/Operation';
+import * as OperationHandlerSet from '@dxos/compute/OperationHandlerSet';
+import { DXN } from '@dxos/echo';
+import type * as Main from '@dxos/react-ui/Main';
+
+//
+// Drawer state, as the deck would own it: the stub handler below writes it and a story's frame reads it.
+//
+
+let drawerState: Main.DrawerState = 'open';
+const listeners = new Set<() => void>();
+
+export const getDrawerState = (): Main.DrawerState => drawerState;
+
+export const setDrawerState = (next: Main.DrawerState) => {
+  drawerState = next;
+  listeners.forEach((listener) => listener());
+};
+
+export const useDrawerState = (): Main.DrawerState =>
+  useSyncExternalStore(
+    (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    () => drawerState,
+  );
+
+/** Stands in for the deck's layout handler, so the panel's toggle, close and float controls move the drawer. */
+export const StubDrawerPlugin = Plugin.define(
+  Plugin.makeMeta({ key: DXN.make('org.dxos.plugin.debug.story.stubDrawer'), name: 'Drawer (stub)' }),
+).pipe(
+  Plugin.addModule(
+    Capability.inlineModule('stub-drawer-operations', { provides: [Capabilities.OperationHandler] }, () =>
+      Effect.succeed([
+        Capability.contribute(
+          Capabilities.OperationHandler,
+          OperationHandlerSet.make(
+            Operation.withHandler(LayoutOperation.UpdateDrawer, ({ state }) =>
+              Effect.sync(() => {
+                if (state === 'toggle') {
+                  setDrawerState(drawerState === 'open' ? 'closed' : 'open');
+                } else if (state) {
+                  setDrawerState(state);
+                }
+              }),
+            ),
+          ),
+        ),
+      ]),
+    ),
+  ),
+  Plugin.make,
+);

package/src/testing/stub-tools-plugin.tsx

@@ -0,0 +1,95 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import * as Plugin from '@dxos/app-framework/Plugin';
+import * as Surface from '@dxos/app-framework/Surface';
+import * as AppGraphBuilder from '@dxos/app-graph/AppGraphBuilder';
+import * as AppGraphNode from '@dxos/app-graph/AppGraphNode';
+import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
+import * as AppNodeMatcher from '@dxos/app-toolkit/AppNodeMatcher';
+import * as AppSurface from '@dxos/app-toolkit/AppSurface';
+import { DXN } from '@dxos/echo';
+import * as GraphNodeMatcher from '@dxos/graph/GraphNodeMatcher';
+
+import { DebugSurface } from '#types';
+
+export const STUB_TOOLS_BRANCH = 'tools';
+
+const STUB_TOOLS_TYPE = 'stub-tools';
+
+/** Node data (and article text) of the stub pages, so a play test can select one and read it back. */
+export const STUB_TOOL_PAGES = [
+  { id: 'alpha', data: 'stub-tool.alpha', label: 'Alpha tool' },
+  { id: 'beta', data: 'stub-tool.beta', label: 'Beta tool' },
+] as const;
+
+const stubGraphBuilder = Capability.inlineModule(
+  'stub-tools-graph',
+  { provides: [AppCapabilities.AppGraphBuilder] },
+  Effect.fnUntraced(function* () {
+    const extensions = yield* Effect.all([
+      AppGraphBuilder.createExtension({
+        id: 'stubTools',
+        match: AppNodeMatcher.whenDebugGroup,
+        connector: () =>
+          Effect.succeed([
+            AppGraphNode.make({
+              id: STUB_TOOLS_BRANCH,
+              type: STUB_TOOLS_TYPE,
+              data: null,
+              // A branch before its children are loaded, so the row shows its chevron on first paint.
+              properties: { label: 'Tools', icon: 'ph--wrench--regular', role: 'branch', position: 2 },
+            }),
+          ]),
+      }),
+      // The pages hang off the branch by a connector of their own, as a real tool plugin's do, so
+      // they only exist once the branch is expanded — the case a restored selection has to survive.
+      AppGraphBuilder.createExtension({
+        id: 'stubToolPages',
+        match: GraphNodeMatcher.whenNodeType(STUB_TOOLS_TYPE),
+        connector: () =>
+          Effect.succeed(
+            STUB_TOOL_PAGES.map((page, index) =>
+              AppGraphNode.make({
+                id: page.id,
+                type: 'stub-tool',
+                data: page.data,
+                properties: { label: page.label, icon: 'ph--flask--regular', position: index },
+              }),
+            ),
+          ),
+      }),
+    ]);
+    return [Capability.contribute(AppCapabilities.AppGraphBuilder, extensions.flat())];
+  }),
+);
+
+const stubSurfaces = Capability.inlineModule('stub-tools-surfaces', { provides: [Capabilities.ReactSurface] }, () =>
+  Effect.succeed([
+    Capability.contribute(
+      Capabilities.ReactSurface,
+      STUB_TOOL_PAGES.map((page) =>
+        Surface.create({
+          id: `stubTool.${page.id}`,
+          filter: AppSurface.literal(DebugSurface.Page, page.data),
+          component: () => <div data-testid={`stubTool.${page.id}`}>{page.label}</div>,
+        }),
+      ),
+    ),
+  ]),
+);
+
+/**
+ * Stands in for devtools in stories: a `tools` branch under the hidden debug category holding two
+ * pages whose articles are their labels, so the debug panel's tree has a branch to toggle and a
+ * page to select without the real plugin's client and space.
+ */
+export const StubToolsPlugin = Plugin.define(
+  Plugin.makeMeta({ key: DXN.make('org.dxos.plugin.debug.story.stubTools'), name: 'Stub tools' }),
+).pipe(Plugin.addModule(stubGraphBuilder), Plugin.addModule(stubSurfaces), Plugin.make);

package/src/translations.ts

@@ -2,8 +2,8 @@
 // Copyright 2026 DXOS.org
 //
 
-import { type Resource } from '@dxos/react-ui';
 import { translations as logPanelTranslations } from '@dxos/react-ui-debug/translations';
+import type * as Theme from '@dxos/react-ui/Theme';
 
 import { meta } from '#meta';
 
@@ -16,10 +16,20 @@ export const translations = [
         'plugin.name': 'Debug',
         'debug.label': 'Debug',
         'generate-objects.label': 'Generate Objects',
+        'create-space-from-template.label': 'Create space from template: {{label}}',
         'space-objects.label': 'Database',
-        'open-debug-panel.label': 'Show Debug',
-        'logs.label': 'Logs',
-        'open-logs.label': 'Show logs',
+        'open-debug-panel.label': 'Show debug panel',
+        'console.tab.label': 'Console',
+        'logs.tab.label': 'Logs',
+        'debug-panel.title': 'Debug',
+        'debug-panel.empty.label': 'Select a tool',
+        'debug-panel.tree.label': 'Debug tools',
+        'debug-port-status.running.label': 'Agent debug port is open — show debug panel',
+        'dock-panel.label': 'Dock panel',
+        'float-panel.label': 'Float panel',
+        'close-panel.label': 'Close',
+        'console.clear.label': 'Clear log',
+        'console.copy.label': 'Copy last result',
 
         'remove-all-objects.confirm.description': 'Remove all objects from this space? This cannot be undone.',
         'remove-all-objects.error.title': 'Failed to remove objects.',
@@ -74,9 +84,8 @@ export const translations = [
         'settings.debug-port.session.label': 'Session id',
         'settings.debug-port.session.description':
           'Pass to composer-recovery.js --session. A new id is issued on every restart.',
-        'settings.debug-port.copy-session.label': 'Copy session id.',
         'settings.debug-port.log.label': 'Debug port log',
       },
     },
   },
-] as const satisfies Resource[];
+] as const satisfies Theme.Resource[];

package/src/types/Debug.ts

@@ -2,14 +2,14 @@
 // Copyright 2023 DXOS.org
 //
 
-import type * as Atom from 'effect/unstable/reactivity/Atom';
+import type * as Atom from 'effect/reactivity/Atom';
 
 import * as Capability from '@dxos/app-framework/Capability';
 import { type IdbLogStore } from '@dxos/log-store-idb';
 
 import { meta } from '#meta';
 
-import * as Settings from './Settings';
+import * as Settings from './Settings.ts';
 
 export type DebugPluginOptions = {
   /** Shared persistent log store for capturing and downloading logs. */

package/src/types/DebugNodes.ts

@@ -4,6 +4,8 @@
 
 // @import-as-namespace
 
+import * as GraphNode from '@dxos/graph/GraphNode';
+
 import { meta } from '#meta';
 
 /** Extracts the last dot-separated segment of a namespaced ID string for use as a node segment id. */
@@ -11,8 +13,26 @@ export const nodeId = (fullId: string): string => fullId.split('.').at(-1) ?? ''
 
 const debugId = meta.profile.key;
 
-/** Top-level Debug node (sibling of DevTools under the SYSTEM navtree group). */
+/** Top-level Debug node, under the debug category. */
 export const id = `${debugId}.debug`;
 
 /** Discriminator for the space-generator article surface (`node.data.type`). */
 export const SpaceType = `${debugId}.space`;
+
+/** Qualified id of the hidden debug category, the root of the debug panel's tree. */
+export const DEBUG_ROOT_ID = `${GraphNode.RootId}/debug`;
+
+/** Qualified id of the Debug node, which hosts the panel's own pages. */
+export const DEBUG_NODE_ID = `${DEBUG_ROOT_ID}/${nodeId(id)}`;
+
+/** Node data of the Effect-CLI console page. */
+export const Console = `${debugId}.console`;
+
+/** Qualified id of the console page: what a pristine panel opens on. */
+export const CONSOLE_NODE_ID = `${DEBUG_NODE_ID}/${nodeId(Console)}`;
+
+/** Node data of the log viewer page. */
+export const Logs = `${debugId}.logs`;
+
+/** Qualified id of the log viewer page. */
+export const LOGS_NODE_ID = `${DEBUG_NODE_ID}/${nodeId(Logs)}`;