@dxos/plugin-space 0.8.4-main.c4373fc → 0.8.4-main.c85a9c8dae

package/src/cli/commands/database/stats.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+import * as Options from '@effect/cli/Options';
+import * as Array from 'effect/Array';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Record from 'effect/Record';
+
+import { CommandConfig, Common, printList, spaceLayer } from '@dxos/cli-util';
+import { Obj } from '@dxos/echo';
+import { Database, Filter, Query } from '@dxos/echo';
+
+import { printStats } from './util';
+
+export const stats = Command.make(
+  'stats',
+  {
+    spaceId: Common.spaceId.pipe(Options.optional),
+  },
+  () =>
+    Effect.gen(function* () {
+      const { json } = yield* CommandConfig;
+      const objects = yield* Database.runQuery(Query.select(Filter.everything()));
+      const stats = Function.pipe(
+        objects,
+        Array.groupBy((obj) => Obj.getTypename(obj) ?? '<empty>'),
+        Record.map((objs) => objs.length),
+      );
+
+      if (json) {
+        yield* Console.log(JSON.stringify(stats, null, 2));
+      } else {
+        const formatted = Record.toEntries(stats).map(([typename, count]) => printStats(typename, count));
+        yield* Console.log(printList(formatted));
+      }
+    }),
+).pipe(
+  Command.withDescription('Query objects.'),
+  Command.provide(({ spaceId }) => spaceLayer(spaceId, true)),
+);

package/src/cli/commands/database/util.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { FormBuilder } from '@dxos/cli-util';
+import { Entity } from '@dxos/echo';
+
+/**
+ * Pretty prints an object with ANSI colors.
+ */
+export const printObject = (obj: Entity.Unknown) => {
+  const typename = Entity.getTypename(obj) ?? '<unknown>';
+
+  // TODO(wittjosiah): Obj.getSchema and thus Obj.getLabel are coming back undefined for some reason.
+  return FormBuilder.make({ title: Entity.getLabel(obj) ?? typename }).pipe(
+    FormBuilder.set('id', obj.id),
+    FormBuilder.set('typename', typename),
+    FormBuilder.build,
+  );
+};
+
+/**
+ * Pretty prints object stats with ANSI colors.
+ */
+export const printStats = (typename: string, count: number) =>
+  FormBuilder.make({ title: typename }).pipe(FormBuilder.set('count', count), FormBuilder.build);
+
+/**
+ * Pretty prints object removal result with ANSI colors.
+ */
+export const printObjectRemoved = (count: number) =>
+  FormBuilder.make({ title: 'Objects removed' }).pipe(FormBuilder.set('count', count), FormBuilder.build);

package/src/cli/commands/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './database';
+export * from './queue';
+export * from './space';

package/src/cli/commands/queue/index.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+
+import { query } from './query';
+
+export const queue = Command.make('queue').pipe(
+  Command.withDescription('Manage queues.'),
+  Command.withSubcommands([query]),
+);

package/src/cli/commands/queue/query.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+import * as Options from '@effect/cli/Options';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { CommandConfig, printList } from '@dxos/cli-util';
+import { ClientService } from '@dxos/client';
+import { type Queue } from '@dxos/client/echo';
+import { DXN } from '@dxos/keys';
+
+import { printQueueObject } from './util';
+
+// TODO(dmaretskyi): Extract
+const DXNSchema = Schema.String.pipe(
+  Schema.transform(Schema.instanceOf(DXN), {
+    decode: (value: string) => DXN.parse(value),
+    encode: (value: DXN) => value.toString(),
+  }),
+);
+
+export const query = Command.make(
+  'query',
+  {
+    dxn: Options.text('dxn').pipe(Options.withDescription('DXN of the queue.'), Options.withSchema(DXNSchema)),
+  },
+  Effect.fnUntraced(function* ({ dxn }) {
+    const { json } = yield* CommandConfig;
+    const client = yield* ClientService;
+    const queue = (yield* Effect.promise(() => client.graph.createRefResolver({}).resolve(dxn))) as Queue<any>;
+    const objects = yield* Effect.promise(() => queue.queryObjects());
+
+    if (json) {
+      yield* Console.log(JSON.stringify(objects, null, 2));
+    } else {
+      // TODO(wittjosiah): Interactive table of results.
+      const formatted = objects.map(printQueueObject);
+      yield* Console.log(printList(formatted));
+    }
+  }),
+).pipe(Command.withDescription('Query objects in a queue.'));

package/src/cli/commands/queue/util.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { FormBuilder } from '@dxos/cli-util';
+import { Entity } from '@dxos/echo';
+
+/**
+ * Pretty prints a queue object with ANSI colors.
+ */
+export const printQueueObject = (obj: Entity.Any) => {
+  const typename = Entity.getTypename(obj) ?? '<unknown>';
+
+  return FormBuilder.make({ title: typename }).pipe(
+    FormBuilder.set('id', obj.id),
+    FormBuilder.set('typename', typename),
+    FormBuilder.build,
+  );
+};

package/src/cli/commands/space/close/close.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+import * as Options from '@effect/cli/Options';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+
+import { CommandConfig, Common, getSpace, waitForSync } from '@dxos/cli-util';
+import { ClientService } from '@dxos/client';
+import { type Key } from '@dxos/echo';
+
+export const handler = ({ spaceId }: { spaceId: Key.SpaceId }) =>
+  Effect.gen(function* () {
+    const { json } = yield* CommandConfig;
+    const client = yield* ClientService;
+
+    const space = yield* getSpace(spaceId);
+
+    // Flush and sync before closing
+    yield* Effect.tryPromise(() => space.db.flush({ indexes: true }));
+    yield* waitForSync(space);
+
+    yield* Effect.tryPromise(() => space.close());
+
+    if (json) {
+      yield* Console.log(JSON.stringify({ success: true, spaceId }, null, 2));
+    } else {
+      yield* Console.log(`Space ${spaceId} closed successfully.`);
+    }
+  });
+
+export const close = Command.make(
+  'close',
+  {
+    spaceId: Common.spaceId.pipe(Options.withDescription('Space ID to close.')),
+  },
+  handler,
+).pipe(Command.withDescription('Close a space.'));

package/src/cli/commands/space/close/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './close';

package/src/cli/commands/space/create/create.test.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { TestConsole, TestLayer } from '@dxos/cli-util/testing';
+import { ClientService } from '@dxos/client';
+import { runAndForwardErrors } from '@dxos/effect';
+
+import { handler } from './create';
+
+describe('space create', () => {
+  it('should create a space without a name', () =>
+    Effect.gen(function* () {
+      const client = yield* ClientService;
+      yield* Effect.tryPromise(() => client.halo.createIdentity());
+      const logger = yield* TestConsole.TestConsole;
+      // Catch timeout errors from sync, but still check output
+      yield* handler({ name: Option.none() }).pipe(Effect.catchAll(() => Effect.void));
+      const logs = logger.logs;
+      // Find the JSON output (should be logged before sync)
+      // log.args is an array, so we need to check the first element
+      const jsonLog = logs.find((log) => {
+        if (log.level === 'log' && Array.isArray(log.args) && log.args.length > 0) {
+          const firstArg = String(log.args[0]);
+          return firstArg.trim().startsWith('{');
+        }
+        return false;
+      });
+      expect(jsonLog).toBeDefined();
+      if (jsonLog && Array.isArray(jsonLog.args) && jsonLog.args.length > 0) {
+        const parsed = JSON.parse(String(jsonLog.args[0]));
+        expect(parsed).toHaveProperty('key');
+        expect(typeof parsed.key).toBe('string');
+        // name might be undefined and omitted from JSON, which is fine
+      }
+      expect(client.spaces.get().length).toBeGreaterThan(0);
+    }).pipe(Effect.provide(TestLayer), Effect.scoped, runAndForwardErrors));
+
+  it('should create a space with a name', () =>
+    Effect.gen(function* () {
+      const client = yield* ClientService;
+      yield* Effect.tryPromise(() => client.halo.createIdentity());
+      const logger = yield* TestConsole.TestConsole;
+      // Catch timeout errors from sync, but still check output
+      yield* handler({ name: Option.some('Test Space') }).pipe(Effect.catchAll(() => Effect.void));
+      const logs = logger.logs;
+      // Find the JSON output (should be logged before sync)
+      // log.args is an array, so we need to check the first element
+      const jsonLog = logs.find((log) => {
+        if (log.level === 'log' && Array.isArray(log.args) && log.args.length > 0) {
+          const firstArg = String(log.args[0]);
+          return firstArg.trim().startsWith('{');
+        }
+        return false;
+      });
+      expect(jsonLog).toBeDefined();
+      if (jsonLog && Array.isArray(jsonLog.args) && jsonLog.args.length > 0) {
+        const parsed = JSON.parse(String(jsonLog.args[0]));
+        expect(parsed).toHaveProperty('key');
+        expect(parsed).toHaveProperty('name', 'Test Space');
+      }
+    }).pipe(Effect.provide(TestLayer), Effect.scoped, runAndForwardErrors));
+});

package/src/cli/commands/space/create/create.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+import * as Options from '@effect/cli/Options';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { CommandConfig } from '@dxos/cli-util';
+import { print, waitForSync } from '@dxos/cli-util';
+import { FormBuilder } from '@dxos/cli-util';
+import { ClientService } from '@dxos/client';
+import { Obj } from '@dxos/echo';
+
+export const handler = Effect.fn(function* ({ name }: { name: Option.Option<string> }) {
+  const { json } = yield* CommandConfig;
+  const client = yield* ClientService;
+
+  const space = yield* Effect.tryPromise(() => client.spaces.create());
+  yield* Effect.tryPromise(() => space.waitUntilReady());
+
+  if (Option.isSome(name)) {
+    Obj.change(space.properties, (p) => {
+      p.name = Option.getOrUndefined(name);
+    });
+  }
+
+  // Output first, then flush and sync
+  if (json) {
+    yield* Console.log(
+      JSON.stringify(
+        {
+          key: space.key.toHex(),
+          ...(space.properties.name ? { name: space.properties.name } : {}),
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    const builder = FormBuilder.make({ title: 'Created Space' }).pipe(
+      FormBuilder.set('key', space.key.truncate()),
+      FormBuilder.set('name', space.properties.name ?? '<none>'),
+    );
+    yield* Console.log(print(FormBuilder.build(builder)));
+  }
+
+  // Flush and sync before completion
+  yield* Effect.tryPromise(() => space.db.flush({ indexes: true }));
+  yield* waitForSync(space);
+});
+
+export const create = Command.make(
+  'create',
+  {
+    name: Options.text('name').pipe(Options.withDescription('The name of the space.'), Options.optional),
+  },
+  handler,
+).pipe(Command.withDescription('Create a new space.'));

package/src/cli/commands/space/create/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './create';

package/src/cli/commands/space/index.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+
+import { close } from './close';
+import { create } from './create';
+import { info } from './info';
+import { join } from './join';
+import { list } from './list';
+import { members } from './members';
+import { open } from './open';
+import { schema } from './schema';
+import { share } from './share';
+import { sync } from './sync';
+
+export const space = Command.make('space').pipe(
+  Command.withDescription('Manage ECHO spaces.'),
+  Command.withSubcommands([close, create, info, join, list, members, open, schema, share, sync]),
+);

package/src/cli/commands/space/info/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './info';

package/src/cli/commands/space/info/info.test.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { TestConsole, TestLayer } from '@dxos/cli-util/testing';
+import { ClientService } from '@dxos/client';
+import { runAndForwardErrors } from '@dxos/effect';
+
+import { handler } from './info';
+
+describe('space info', () => {
+  it('should show space info', () =>
+    Effect.gen(function* () {
+      const client = yield* ClientService;
+      yield* Effect.tryPromise(() => client.halo.createIdentity());
+      const space = yield* Effect.tryPromise(() => client.spaces.create());
+      yield* Effect.tryPromise(() => space.waitUntilReady());
+      yield* handler({ spaceId: Option.some(space.id) });
+      const logger = yield* TestConsole.TestConsole;
+      const logs = logger.logs;
+      expect(logs).toHaveLength(1);
+      const parsed = TestConsole.parseJson<{ id: string; state: string; key: string }>(logs[0]);
+      expect(parsed).toHaveProperty('id');
+      expect(parsed).toHaveProperty('state');
+      expect(parsed).toHaveProperty('key');
+      expect(parsed.id).toBe(space.id);
+    }).pipe(Effect.provide(TestLayer), Effect.scoped, runAndForwardErrors));
+
+  it('should show default space info when spaceId is not provided', () =>
+    Effect.gen(function* () {
+      const client = yield* ClientService;
+      yield* Effect.tryPromise(() => client.halo.createIdentity());
+      yield* Effect.tryPromise(() => client.spaces.waitUntilReady());
+      yield* handler({ spaceId: Option.none() });
+      const logger = yield* TestConsole.TestConsole;
+      const logs = logger.logs;
+      expect(logs).toHaveLength(1);
+      const parsed = TestConsole.parseJson<{ id: string; state: string; key: string }>(logs[0]);
+      expect(parsed).toHaveProperty('id');
+      expect(parsed).toHaveProperty('state');
+      expect(parsed).toHaveProperty('key');
+    }).pipe(Effect.provide(TestLayer), Effect.scoped, runAndForwardErrors));
+});

package/src/cli/commands/space/info/info.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+import * as Options from '@effect/cli/Options';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import type * as Option from 'effect/Option';
+
+import { CommandConfig, Common, formatSpace, getSpace, print, printSpace, spaceIdWithDefault } from '@dxos/cli-util';
+import { ClientService } from '@dxos/client';
+import { type Key } from '@dxos/echo';
+
+export const handler = Effect.fn(function* ({ spaceId }: { spaceId: Option.Option<string> }) {
+  const { json } = yield* CommandConfig;
+  const client = yield* ClientService;
+
+  const resolvedSpaceId = yield* spaceIdWithDefault(spaceId as Option.Option<Key.SpaceId>);
+  const space = yield* getSpace(resolvedSpaceId);
+
+  const formatted = yield* formatSpace(space);
+
+  if (json) {
+    yield* Console.log(JSON.stringify(formatted, null, 2));
+  } else {
+    yield* Console.log(print(printSpace(formatted)));
+  }
+});
+
+export const info = Command.make(
+  'info',
+  {
+    spaceId: Common.spaceId.pipe(Options.optional),
+  },
+  handler,
+).pipe(Command.withDescription('Show space info.'));

package/src/cli/commands/space/join/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './join';

package/src/cli/commands/space/join/join.ts

@@ -0,0 +1,122 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Args from '@effect/cli/Args';
+import * as Command from '@effect/cli/Command';
+import * as Options from '@effect/cli/Options';
+import * as Prompt from '@effect/cli/Prompt';
+import * as Console from 'effect/Console';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { CommandConfig } from '@dxos/cli-util';
+import { print, waitForSync } from '@dxos/cli-util';
+import { FormBuilder } from '@dxos/cli-util';
+import { ClientService } from '@dxos/client';
+
+import { acceptInvitation } from './util';
+
+export const handler = Effect.fn(function* ({
+  invitationCode,
+  authCode,
+}: {
+  invitationCode: string;
+  authCode: Option.Option<string>;
+}) {
+  const { json } = yield* CommandConfig;
+  const client = yield* ClientService;
+
+  let encoded = invitationCode;
+  if (encoded.startsWith('http') || encoded.startsWith('socket')) {
+    const searchProps = new URL(encoded).searchParams;
+    encoded = searchProps.get('spaceInvitationCode') ?? encoded;
+  }
+
+  const invitation = yield* acceptInvitation({
+    observable: client.spaces.join(encoded),
+    callbacks: {
+      onReadyForAuth: (invitation) => {
+        if (Option.isSome(authCode)) {
+          return Effect.succeed(Option.getOrUndefined(authCode) ?? undefined) as Effect.Effect<
+            string | void,
+            never,
+            never
+          >;
+        }
+        return Prompt.text({ message: 'Enter the authentication code' })
+          .pipe(Prompt.run)
+          .pipe(Effect.mapError(() => undefined as never))
+          .pipe(Effect.catchAll(() => Effect.succeed(undefined))) as Effect.Effect<string | void, never, never>;
+      },
+    },
+  });
+
+  // Wait for space to be available with retry logic
+  const spaceKey = invitation.spaceKey;
+  if (!spaceKey) {
+    if (json) {
+      yield* Console.log(JSON.stringify({ error: 'No space key in invitation' }, null, 2));
+    } else {
+      yield* Console.log('No space key in invitation.');
+    }
+    return;
+  }
+
+  let space = client.spaces.get(spaceKey);
+  if (!space) {
+    // Retry up to 5 times with increasing delays
+    const maxRetries = 5;
+    const retryDelays = [0.5, 1, 1.5, 2, 2.5].map((s) => Duration.seconds(s));
+    for (let i = 0; i < maxRetries; i++) {
+      yield* Effect.sleep(retryDelays[i]);
+      space = client.spaces.get(spaceKey);
+      if (space) {
+        break;
+      }
+    }
+  }
+
+  if (!space) {
+    if (json) {
+      yield* Console.log(JSON.stringify({ error: 'Space not found after joining' }, null, 2));
+    } else {
+      yield* Console.log('Space not found after joining.');
+    }
+    return;
+  }
+
+  // Flush and sync after joining
+  yield* Effect.tryPromise(() => space.db.flush({ indexes: true }));
+  yield* waitForSync(space);
+
+  if (json) {
+    yield* Console.log(
+      JSON.stringify(
+        {
+          spaceId: space.id,
+          state: space.state.get(),
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    const builder = FormBuilder.make({ title: 'Joined Space' }).pipe(
+      FormBuilder.set('spaceId', space.id),
+      FormBuilder.set('key', space.key.truncate()),
+      FormBuilder.set('name', space.properties.name ?? '<none>'),
+    );
+    yield* Console.log(print(FormBuilder.build(builder)));
+  }
+});
+
+export const join = Command.make(
+  'join',
+  {
+    invitationCode: Args.text({ name: 'invitationCode' }).pipe(Args.withDescription('The invitation code.')),
+    authCode: Options.text('authCode').pipe(Options.withDescription('The authentication code.'), Options.optional),
+  },
+  handler,
+).pipe(Command.withDescription('Join a space via invitation.'));

package/src/cli/commands/space/join/util.ts

@@ -0,0 +1,82 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Queue from 'effect/Queue';
+
+import { type AuthenticatingInvitationObservable, Invitation } from '@dxos/client/invitations';
+import { runAndForwardErrors } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { AlreadyJoinedError } from '@dxos/protocols';
+
+type AcceptInvitationProps = {
+  observable: AuthenticatingInvitationObservable;
+  callbacks?: {
+    onConnecting?: (invitation: Invitation) => Effect.Effect<void>;
+    onReadyForAuth?: (invitation: Invitation) => Effect.Effect<string | void, never, never>;
+    onSuccess?: (invitation: Invitation) => Effect.Effect<void>;
+  };
+};
+
+/**
+ * Accept an invitation and handle authentication flow.
+ * Ported from cli-base to Effect-based approach.
+ */
+export const acceptInvitation = ({ observable, callbacks }: AcceptInvitationProps): Effect.Effect<Invitation, Error> =>
+  Effect.gen(function* () {
+    const doneQueue = yield* Queue.unbounded<Invitation>();
+
+    const runCallback = (effect: Effect.Effect<void> | undefined) => {
+      if (effect) {
+        runAndForwardErrors(effect).catch(() => {
+          // Ignore callback errors
+        });
+      }
+    };
+
+    const subscription = observable.subscribe(
+      (invitation) => {
+        switch (invitation.state) {
+          case Invitation.State.CONNECTING: {
+            runCallback(callbacks?.onConnecting?.(invitation));
+            break;
+          }
+
+          case Invitation.State.READY_FOR_AUTHENTICATION: {
+            if (invitation.authMethod === Invitation.AuthMethod.SHARED_SECRET) {
+              const callbackEffect = callbacks?.onReadyForAuth?.(invitation) ?? Effect.succeed(undefined);
+              Effect.gen(function* () {
+                const callbackResult = yield* callbackEffect;
+                const code = invitation.authCode ?? callbackResult;
+                invariant(code, 'No code provided');
+                yield* Effect.tryPromise(() => observable.authenticate(code));
+              })
+                .pipe(runAndForwardErrors)
+                .catch(() => {
+                  // Error handling
+                });
+            }
+            break;
+          }
+
+          case Invitation.State.SUCCESS: {
+            runCallback(callbacks?.onSuccess?.(invitation));
+            runAndForwardErrors(Queue.offer(doneQueue, invitation)).catch(() => {});
+            break;
+          }
+        }
+      },
+      (err) => {
+        if (err instanceof AlreadyJoinedError) {
+          runAndForwardErrors(Queue.offer(doneQueue, observable.get())).catch(() => {});
+          return;
+        }
+        throw err;
+      },
+    );
+
+    const invitation = yield* Queue.take(doneQueue);
+    subscription.unsubscribe();
+    return invitation;
+  });