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

package/src/samples/incident/docs.ts

@@ -0,0 +1,111 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+import { Database } from '@dxos/echo';
+import * as Markdown from '@dxos/plugin-markdown/Markdown';
+
+//
+// The source material: one machine record and four human notes.
+//
+// The log alone gives the technical cause and every time that matters. The notes are the only place
+// the process failures live — who was paged, where the renewal reminder was kept, how support found
+// an engineer — and two of them carry claims the log contradicts. A retro that follows the notes
+// without checking them against the log recommends the wrong things; one that reads only the log
+// finds nothing to recommend at all.
+//
+
+const STATUS_LOG_MD = `# Status log — incident 0516
+
+Exported from the status service. Times are UTC, Saturday 16 May.
+
+| Time | Source | Event |
+| --- | --- | --- |
+| 02:00:04 | edge | TLS handshake failures begin on api.northlight.example — certificate expired 2026-05-16T02:00:00Z |
+| 02:00:30 | edge | Error rate on api.* rises from 0% to 98% |
+| 02:03:11 | alerts | PAGE fired: "api error rate > 50%" — rotation platform-oncall, pager target m.okafor |
+| 02:03:12 | alerts | Page delivered to m.okafor. No acknowledgement. |
+| 02:33:11 | alerts | Page re-sent to m.okafor. No acknowledgement. |
+| 03:31:47 | support | Ticket #4471 opened from customer email (Ferrous Ltd): "API down since about 2am" |
+| 04:41:09 | alerts | Page acknowledged by j.reyes via Slack |
+| 04:52:30 | ops | Incident channel #inc-0516 opened by j.reyes |
+| 05:09:55 | ops | Certificate renewed manually by j.reyes using the shared ACME account |
+| 05:12:18 | edge | TLS handshakes succeeding; error rate on api.* falls from 98% to 0.2% |
+| 05:12:18 | ops | Incident resolved |
+
+No deploys, configuration changes or infrastructure events were recorded between 15 May 12:00 and
+16 May 05:12. Database disk usage held at 41% throughout.
+`;
+
+const NOTE_JAE_MD = `# Notes from Jae Reyes — platform, on call that weekend
+
+I was not paged. I found out when Priya messaged me on Slack a little after half four, and I had
+the cert renewed about half an hour later once I worked out that was what it was.
+
+Afterwards I looked at the pager config. The platform on-call rotation still lists Mira Okafor as
+the target. Mira moved to the data team in March. Nobody updated the rotation when the team
+changed, so for two months every page for our services has gone to someone who is no longer on
+the team.
+
+My guess is something went out on Friday afternoon that broke TLS termination. We should stop
+Friday deploys.
+`;
+
+const NOTE_PRIYA_MD = `# Notes from Priya Nair — support lead
+
+Ferrous emailed at about half three saying the API had been down since two. I opened a ticket and
+then tried to find someone. I did not know who was on call or how to reach the pager, so I messaged
+two people on the platform team who did not answer, and then Jae, who did, at around half four.
+
+There is no written path from support to on-call for weekends. During the week I would ask in the
+platform channel. On Saturday night nobody is reading it. I made three guesses at who to contact
+and the third one was right, and that is the only reason this was three hours and not six.
+`;
+
+const NOTE_DAN_MD = `# Notes from Dan Walsh — platform, renewed the certificate last year
+
+The certificate for api.northlight.example is renewed by hand once a year. I did it on 15 May last
+year. There is no ACME automation for that domain because its DNS is managed by a third party and
+we never finished the delegation work.
+
+The reminder to renew it was a calendar event on Tom's calendar. Tom left in January. When his
+account was closed the event went with it, and nobody had a copy. I only remembered the date
+because Jae asked me on Saturday.
+`;
+
+const NOTE_SAM_MD = `# Notes from Sam Lindqvist — product
+
+I was not online over the weekend, so this is second hand. I heard on Monday that the database
+ran out of disk and that is what took the API down.
+
+Three customers have asked for a summary they can forward internally. They do not need the
+technical detail; they need to know what happened, how long it lasted, and that it will not
+happen again.
+`;
+
+export type DocsResult = {
+  log: Markdown.Document;
+  notes: {
+    jae: Markdown.Document;
+    priya: Markdown.Document;
+    dan: Markdown.Document;
+    sam: Markdown.Document;
+  };
+};
+
+/** The record and the recollections the retro is written from. */
+export const Docs: SampleSpace.Phase<DocsResult> = SampleSpace.phase('docs', {
+  schemas: [Markdown.Document],
+  run: () =>
+    Effect.gen(function* () {
+      const log = yield* Database.add(Markdown.make({ name: 'Status log', content: STATUS_LOG_MD }));
+      const jae = yield* Database.add(Markdown.make({ name: 'Notes — Jae Reyes', content: NOTE_JAE_MD }));
+      const priya = yield* Database.add(Markdown.make({ name: 'Notes — Priya Nair', content: NOTE_PRIYA_MD }));
+      const dan = yield* Database.add(Markdown.make({ name: 'Notes — Dan Walsh', content: NOTE_DAN_MD }));
+      const sam = yield* Database.add(Markdown.make({ name: 'Notes — Sam Lindqvist', content: NOTE_SAM_MD }));
+      return { log, notes: { jae, priya, dan, sam } };
+    }),
+});

package/src/samples/incident/project.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+import * as Instructions from '@dxos/compute/Instructions';
+import * as Project from '@dxos/compute/Project';
+import { Database, Ref } from '@dxos/echo';
+
+import { type DocsResult } from './docs.ts';
+import { type TasksResult } from './tasks.ts';
+
+export type ProjectInput = { docs: DocsResult; tasks: TasksResult };
+
+export type ProjectResult = { project: Project.Project; instructions: Instructions.Instructions };
+
+const INSTRUCTIONS = `You are writing the retrospective for incident 0516, when the public API was down for just over \
+three hours on a Saturday morning.
+
+The status log is the record of what happened and when. The notes are what people remember, and \
+memory disagrees with the log in places. Where they disagree, the log wins, and the retrospective \
+says so rather than quietly picking one. A claim that appears in a note but nowhere in the log is a \
+claim, not a finding.
+
+Keep it blameless. Name the systems and the gaps, not the people at fault; the people in the notes \
+are the ones who will fix it.
+
+File every document you write as an artifact on this project rather than leaving it in the chat, and \
+turn every recommendation into a task on this project with an owner drawn from the people in the notes.`;
+
+/** The retro as a project: the record and the notes as its artifacts, the four steps as its tasks. */
+export const ProjectPhase: SampleSpace.Phase<ProjectResult, ProjectInput> = SampleSpace.phase('project', {
+  schemas: [Project.Project, Instructions.Instructions],
+  run: ({ docs, tasks }: ProjectInput) =>
+    Effect.gen(function* () {
+      const sources = [docs.log, docs.notes.jae, docs.notes.priya, docs.notes.dan, docs.notes.sam];
+      const instructions = yield* Database.add(
+        Instructions.make({
+          name: 'Incident 0516 retrospective',
+          text: INSTRUCTIONS,
+          objects: [...sources.map((doc) => Ref.make(doc)), Ref.make(tasks.taskSet)],
+        }),
+      );
+
+      const project = yield* Database.add(
+        Project.make({
+          name: 'Incident 0516 retrospective',
+          description:
+            'The API certificate expired on a Saturday morning and nobody was paged for two and a half hours. Work out why, and what to change.',
+          status: 'active',
+          instructions: Ref.make(instructions),
+          taskSet: Ref.make(tasks.taskSet),
+          artifacts: sources.map((doc) => Ref.make(doc)),
+        }),
+      );
+
+      return { project, instructions };
+    }),
+});

package/src/samples/incident/tasks.ts

@@ -0,0 +1,101 @@
+//
+// 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 { Task, TaskSet } from '@dxos/types';
+
+import { daysAgo } from './util.ts';
+
+//
+// The retro as four pieces of work, in the order they depend on each other. Every one is `todo`:
+// this space is a job to delegate, not a retro caught half-written.
+//
+// Each task names one deliverable and where it goes, so the check on a finished task is whether
+// that thing exists in that place — not whether the chat said it did.
+//
+
+type TaskSeed = {
+  readonly title: string;
+  readonly description: string;
+  readonly estimate?: Task.Estimate;
+};
+
+const STEPS: ReadonlyArray<TaskSeed> = [
+  {
+    title: 'Reconstruct the timeline',
+    description:
+      'One document on this project named "Timeline": what happened and when, from the status log. Where a note disagrees with the log, follow the log and record the disagreement.',
+    estimate: 's',
+  },
+  {
+    title: 'Write the retrospective',
+    description:
+      'One document on this project named "Retrospective": what broke, why it went undetected for as long as it did, and what would have prevented or caught it. Ground every claim in the log or a named note.',
+    estimate: 'm',
+  },
+  {
+    title: 'File the action items',
+    description:
+      'One task on this project per recommendation in the retrospective, each assigned to one of the people in the notes. Tasks, not a list in the document.',
+    estimate: 's',
+  },
+  {
+    title: 'Draft the customer notice',
+    description:
+      'One document on this project named "Customer notice": what happened and for how long, in plain language a customer can forward. No internal names, systems or people.',
+    estimate: 's',
+  },
+];
+
+export type TasksResult = { taskSet: TaskSet.TaskSet; tasks: Task.Task[] };
+
+/** The four 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: 'Incident 0516 retrospective',
+          description: 'From the log and the notes to a filed retro.',
+        }),
+      );
+
+      const tasks = STEPS.map((step) =>
+        Task.make({
+          title: step.title,
+          description: step.description,
+          estimate: step.estimate,
+          status: 'todo',
+          history: [
+            {
+              id: EntityId.random(),
+              date: daysAgo(0),
+              event: 'created' as const,
+              description: 'Filed from the incident template.',
+            },
+          ],
+        }),
+      );
+      yield* SampleSpace.children(taskSet, tasks, (taskSet, refs) => {
+        taskSet.tasks = refs;
+      });
+
+      // The retro needs the timeline, the action items need the retro, the notice needs both.
+      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/incident/util.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+
+/**
+ * The Monday after the incident, when the retro is written. Stable so regenerations are
+ * reproducible; override with NOW=2026-05-18 env.
+ */
+export const REFERENCE = process.env.NOW ? new Date(process.env.NOW) : new Date('2026-05-18T09:00:00Z');
+
+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;
+
+/** The people in the notes, as task owners. The names are the only identity a template can give them. */
+export const CAST = {
+  jae: { role: 'user', name: 'Jae Reyes' },
+  priya: { role: 'user', name: 'Priya Nair' },
+  dan: { role: 'user', name: 'Dan Walsh' },
+  sam: { role: 'user', name: 'Sam Lindqvist' },
+} as const;

package/src/samples/index.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * as IncidentSpace from './incident/IncidentSpace.ts';
+export * as PipelineSpace from './crm/PipelineSpace.ts';
+export * as ReviewSpace from './review/ReviewSpace.ts';
+export * as StockfishSpace from './stockfish/StockfishSpace.ts';
+export * as TidepoolSpace from './tidepool/TidepoolSpace.ts';
+export * as WeatherSpace from './weather/WeatherSpace.ts';
+export * as WorkerSpace from './worker/WorkerSpace.ts';

package/src/samples/review/ReviewSpace.test.ts

@@ -0,0 +1,89 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { buildArchive, histogram } from '@dxos/app-toolkit/testing';
+import * as EffectEx from '@dxos/effect/EffectEx';
+
+import * as ReviewSpace from './ReviewSpace.ts';
+
+// A 1×1 PNG, so the build needs no network and every image resolves inline.
+const PIXEL = Uint8Array.from(
+  atob('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII='),
+  (char) => char.charCodeAt(0),
+);
+
+type ArchiveObject = {
+  '@type'?: string;
+  'id': string;
+  'title'?: string;
+  'status'?: string;
+  'state'?: string;
+  'artifacts'?: unknown[];
+  'data'?: { _tag?: string };
+};
+
+const build = async (loadAsset: ReviewSpace.Options['loadAsset']) => {
+  const { json } = await EffectEx.runPromise(buildArchive(ReviewSpace.make({ loadAsset })));
+  const objects: ArchiveObject[] = JSON.parse(json).objects;
+  const ofType = (typename: string) => objects.filter((object) => object['@type']?.includes(typename));
+  return { json, objects, ofType };
+};
+
+/**
+ * The template is built on demand rather than committed, so this asserts its shape in place of a
+ * fixture: if a schema it seeds changes incompatibly, the build fails here.
+ */
+describe('Review template', () => {
+  test('builds one project with tasks, pull requests and media', { timeout: 120_000 }, async ({ expect }) => {
+    const { json } = await build(async () => PIXEL);
+    const counts = histogram(json);
+    const countOf = (typename: string) =>
+      Object.entries(counts)
+        .filter(([type]) => type.includes(typename))
+        .reduce((total, [, count]) => total + count, 0);
+
+    expect(countOf('type.project')).toBe(1);
+    expect(countOf('type.taskSet')).toBe(1);
+    expect(countOf('type.task:')).toBe(7);
+    expect(countOf('type.pullRequest')).toBe(5);
+    expect(countOf('type.file')).toBe(4);
+    expect(countOf('type.video')).toBe(3);
+  });
+
+  test(
+    'finished tasks carry merged PRs with media; tasks in review carry open PRs',
+    { timeout: 120_000 },
+    async ({ expect }) => {
+      const { ofType } = await build(async () => PIXEL);
+      const refersTo = (task: ArchiveObject, objects: ArchiveObject[]) =>
+        objects.filter((object) => JSON.stringify(task.artifacts ?? []).includes(object.id));
+
+      const pullRequests = ofType('type.pullRequest');
+      const media = [...ofType('type.file'), ...ofType('type.video')];
+      const tasks = ofType('type.task:');
+
+      const done = tasks.filter((task) => task.status === 'done');
+      expect(done).toHaveLength(3);
+      for (const task of done) {
+        expect(refersTo(task, pullRequests).map((pullRequest) => pullRequest.state)).toEqual(['merged']);
+        expect(refersTo(task, media).length).toBeGreaterThan(0);
+      }
+
+      const review = tasks.filter((task) => task.status === 'review');
+      expect(review).toHaveLength(2);
+      for (const task of review) {
+        expect(refersTo(task, pullRequests).map((pullRequest) => pullRequest.state)).toEqual(['open']);
+      }
+    },
+  );
+
+  test('keeps an unreachable image as an external blob naming its source', { timeout: 120_000 }, async ({ expect }) => {
+    const { ofType } = await build(async () => undefined);
+    const blobs = ofType('type.blob');
+    expect(blobs).toHaveLength(4);
+    expect(blobs.every((blob) => blob.data?._tag === 'external')).toBe(true);
+  });
+});

package/src/samples/review/ReviewSpace.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Effect from 'effect/Effect';
+
+import type * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+
+import { type AssetLoader, fetchAsset, makeMedia } from './assets.ts';
+import { REFERENCE } from './util.ts';
+import { Work } from './work.ts';
+
+export const TEMPLATE_ID = 'org.dxos.plugin-debug.template.review';
+
+export type Options = {
+  /** Where screenshot bytes come from; defaults to fetching the pinned PR URLs. */
+  readonly loadAsset?: AssetLoader;
+};
+
+/**
+ * A review queue: one project whose finished tasks carry the merged dxos/dxos pull requests that
+ * delivered them, with the screenshots and demo recordings attached to those PRs, and whose tasks in
+ * review carry the PRs still open.
+ */
+export const make = ({ loadAsset = fetchAsset }: Options = {}) => {
+  const phases = { media: makeMedia(loadAsset), work: Work };
+  return SampleSpace.make({
+    space: { name: 'Composer — Review queue', icon: 'medal-military', hue: 'green' },
+    reference: REFERENCE,
+    phases,
+    build: (phases) =>
+      Effect.gen(function* () {
+        const media = yield* phases.media();
+        return yield* phases.work(media);
+      }),
+  });
+};
+
+export const makeTemplate = (options?: Options): AppCapabilities.SpaceTemplate =>
+  SampleSpace.makeTemplate({
+    id: TEMPLATE_ID,
+    description: 'A project with tasks carrying real dxos pull requests, their screenshots and demo videos.',
+    definition: make(options),
+  });

package/src/samples/review/assets.ts

@@ -0,0 +1,123 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+import { Blob, Database, Ref } from '@dxos/echo';
+import { log } from '@dxos/log';
+import { File, Video } from '@dxos/types';
+
+//
+// Media procured from dxos/dxos pull requests: the screenshots and demo recordings their authors
+// linked from the PR body. Screenshots are SHA-pinned `raw.githubusercontent.com` URLs, so they
+// survive the source branch being deleted and are served with `Access-Control-Allow-Origin: *`.
+//
+
+/** Resolves a URL to its bytes; `undefined` when unreachable. Injected so a headless build needs no network. */
+export type AssetLoader = (url: string) => Promise<Uint8Array | undefined>;
+
+/** Fetches over HTTP, treating any failure as unavailable so an offline apply still produces the space. */
+export const fetchAsset: AssetLoader = async (url) => {
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      log.warn('sample asset unavailable', { url, status: response.status });
+      return undefined;
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  } catch (error) {
+    log.warn('sample asset unavailable', { url, error });
+    return undefined;
+  }
+};
+
+const R2 = 'https://pub-39066a86073446d7b77b1c157b660bb5.r2.dev/demos';
+
+export type ImageKey = 'railBefore' | 'railAfter' | 'oauthIdle' | 'oauthPending';
+
+const IMAGE_SEEDS: ReadonlyArray<SampleSpace.Seed<ImageKey, { name: string; url: string }>> = [
+  {
+    key: 'railBefore',
+    name: 'l0-rail-before.png',
+    url: 'https://raw.githubusercontent.com/dxos/dxos/97e185d31046b60ee0e130bdc86553de98f356f8/.pr-assets/l0-before.png',
+  },
+  {
+    key: 'railAfter',
+    name: 'l0-rail-after.png',
+    url: 'https://raw.githubusercontent.com/dxos/dxos/97e185d31046b60ee0e130bdc86553de98f356f8/.pr-assets/l0-after.png',
+  },
+  {
+    key: 'oauthIdle',
+    name: 'oauth-idle.png',
+    url: 'https://raw.githubusercontent.com/dxos/dxos/f186f44ee72b4c4b7508b4f3f6a97f3957704c84/packages/plugins/plugin-onboarding/assets/oauth-idle.png',
+  },
+  {
+    key: 'oauthPending',
+    name: 'oauth-pending.png',
+    url: 'https://raw.githubusercontent.com/dxos/dxos/f186f44ee72b4c4b7508b4f3f6a97f3957704c84/packages/plugins/plugin-onboarding/assets/oauth-pending.png',
+  },
+];
+
+export type VideoKey = 'toastCountdown' | 'haloLogin' | 'archify';
+
+// Recordings stay URL-based `Video` objects: the R2 bucket sends no CORS header, so the bytes cannot
+// be read into a blob from the browser, while the player embeds the URL directly.
+const VIDEO_SEEDS: ReadonlyArray<SampleSpace.Seed<VideoKey, { name: string; url: string; description: string }>> = [
+  {
+    key: 'toastCountdown',
+    name: 'Toast countdown demo',
+    url: `${R2}/2026-09-04-toast-countdown/toast-countdown.webm`,
+    description: 'A toast counting down its remaining time in a bar, pausing on hover (dxos/dxos#12954).',
+  },
+  {
+    key: 'haloLogin',
+    name: 'Switch identity in place — login',
+    url: `${R2}/2026-09-23-halo-in-place-identity/halo-login.webm`,
+    description: 'Logging in to another identity without a reset and reload (dxos/dxos#13336).',
+  },
+  {
+    key: 'archify',
+    name: 'Archify diagrams demo',
+    url: `${R2}/2026-09-04-plugin-archify/archify-final.webm`,
+    description: 'Generating an architecture diagram of a package with Archify (dxos/dxos#12952).',
+  },
+];
+
+export type MediaResult = {
+  images: Record<ImageKey, File.File>;
+  videos: Record<VideoKey, Video.Video>;
+};
+
+/**
+ * Images become `File`s whose blob holds the bytes inline, which every client can render without a
+ * storage backend. An image the loader cannot reach keeps its source URL as an external blob, so the
+ * space is still complete and the file says where it came from.
+ */
+export const makeMedia = (loadAsset: AssetLoader): SampleSpace.Phase<MediaResult> =>
+  SampleSpace.phase('media', {
+    schemas: [File.File, Blob.Blob, Video.Video],
+    run: () =>
+      Effect.gen(function* () {
+        const images = yield* SampleSpace.seed(IMAGE_SEEDS, (seed) =>
+          Effect.gen(function* () {
+            const bytes = yield* Effect.promise(() => loadAsset(seed.url));
+            const blob = yield* Database.add(
+              Blob.make({
+                type: 'image/png',
+                size: bytes?.byteLength ?? 0,
+                data: bytes ? Blob.inlineData(bytes) : Blob.externalData(seed.url),
+              }),
+            );
+            return yield* Database.add(File.make({ name: seed.name, data: Ref.make(blob) }));
+          }),
+        );
+
+        const videos = yield* SampleSpace.seed(VIDEO_SEEDS, (seed) =>
+          Database.add(Video.make({ name: seed.name, url: seed.url, description: seed.description })),
+        );
+
+        return { images, videos };
+      }),
+  });

package/src/samples/review/util.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+
+/** Stable reference date so regenerations are reproducible. */
+export const REFERENCE = new Date('2026-09-24T15:00:00Z');
+
+export const { daysAgo } = SampleSpace.makeClock(REFERENCE);