@dxos/plugin-client 0.8.4-main.ae835ea → 0.8.4-main.bc2380dfbc

package/src/commands/halo/credential/list/list.ts

@@ -0,0 +1,115 @@
+//
+// 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 Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { CommandConfig, Common, FormBuilder, getSpace, printList } from '@dxos/cli-util';
+import { ClientService } from '@dxos/client';
+import type { Credential } from '@dxos/client/halo';
+import { type Key } from '@dxos/echo';
+
+const mapCredentials = (credentials: Credential[]) => {
+  return credentials.map((credential) => ({
+    id: credential.id?.toHex() ?? '<unknown>',
+    issuer: credential.issuer?.toHex() ?? '<unknown>',
+    subject: credential.subject?.id?.toHex() ?? '<unknown>',
+    type: credential.subject.assertion['@type'],
+    assertion: credential.subject.assertion,
+  }));
+};
+
+const printCredential = (credential: Credential) => {
+  const type = credential.subject.assertion['@type'] ?? '<unknown>';
+  return FormBuilder.make({ title: type }).pipe(
+    FormBuilder.option('id', Option.fromNullable(credential.id?.truncate())),
+    FormBuilder.option('issuer', Option.fromNullable(credential.issuer?.truncate())),
+    FormBuilder.option('subject', Option.fromNullable(credential.subject?.id?.truncate())),
+    FormBuilder.build,
+  );
+};
+
+export const handler = Effect.fn(function* ({
+  type,
+  spaceId,
+  timeout,
+  delay,
+}: {
+  type: Option.Option<string>;
+  spaceId: Option.Option<Key.SpaceId>;
+  timeout: number;
+  delay: number;
+}) {
+  const { json } = yield* CommandConfig;
+  const client = yield* ClientService;
+  let credentials: Credential[];
+
+  if (Option.isSome(spaceId)) {
+    // If space ID was provided, get credentials from that space.
+    const space = yield* getSpace(spaceId.value);
+    credentials = yield* Effect.tryPromise(() => space.internal.getCredentials());
+  } else {
+    // Get credentials from HALO
+    const identity = client.halo.identity;
+    if (!identity) {
+      if (json) {
+        yield* Console.log(JSON.stringify({ error: 'Profile not initialized' }, null, 2));
+      } else {
+        yield* Console.log('Profile not initialized.');
+      }
+      return;
+    }
+
+    // Wait for at least one credential
+    const latch = yield* Effect.makeLatch();
+    const subscription = client.halo.credentials.subscribe((creds) => {
+      if (creds.length > 0) {
+        Effect.runSync(latch.open);
+      }
+    });
+
+    yield* latch.await.pipe(
+      Effect.timeout(Duration.millis(timeout)),
+      Effect.catchAll(() => Effect.void),
+      Effect.ensuring(
+        Effect.sync(() => {
+          subscription.unsubscribe();
+        }),
+      ),
+    );
+
+    // Wait a bit more to ensure all credentials are loaded
+    yield* Effect.sleep(Duration.millis(delay));
+
+    credentials = client.halo.queryCredentials({ type: Option.getOrUndefined(type) });
+  }
+
+  if (json) {
+    yield* Console.log(JSON.stringify(mapCredentials(credentials), null, 2));
+  } else {
+    const formatted = credentials.map(printCredential);
+    yield* Console.log(printList(formatted));
+  }
+});
+
+export const list = Command.make(
+  'list',
+  {
+    type: Options.text('type').pipe(Options.withDescription('Filter by credential type.'), Options.optional),
+    spaceId: Common.spaceId.pipe(Options.withDescription('Space ID to show credentials from.'), Options.optional),
+    timeout: Options.integer('timeout').pipe(
+      Options.withDescription('Time in milliseconds to wait for at least one credential before listing.'),
+      Options.withDefault(500),
+    ),
+    delay: Options.integer('delay').pipe(
+      Options.withDescription('Delay in milliseconds before listing.'),
+      Options.withDefault(250),
+    ),
+  },
+  handler,
+).pipe(Command.withDescription('List HALO credentials.'));

package/src/commands/halo/identity/identity.test.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { TestConsole, TestLayer } from '@dxos/cli-util/testing';
+import { ClientService } from '@dxos/client';
+import { runAndForwardErrors } from '@dxos/effect';
+
+import { handler } from './identity';
+
+describe('halo identity', () => {
+  it('should log if identity is not initialized', () =>
+    Effect.gen(function* () {
+      yield* handler();
+      const logger = yield* TestConsole.TestConsole;
+      const logs = logger.logs;
+      expect(logs).toHaveLength(1);
+      expect(TestConsole.extractJsonString(logs[0])).toEqual(
+        JSON.stringify({ error: 'Identity not initialized' }, null, 2),
+      );
+    }).pipe(Effect.provide(TestLayer), Effect.scoped, runAndForwardErrors));
+
+  it('should print identity if initialized', () =>
+    Effect.gen(function* () {
+      const client = yield* ClientService;
+      yield* Effect.tryPromise(() => client.halo.createIdentity({ displayName: 'Test' }));
+      yield* handler();
+      const logger = yield* TestConsole.TestConsole;
+      const logs = logger.logs;
+      expect(logs).toHaveLength(1);
+      const parsedIdentity = TestConsole.parseJson(logs[0]);
+      expect(parsedIdentity).toEqual({
+        identityKey: client.halo.identity.get()?.identityKey.toHex(),
+        displayName: client.halo.identity.get()?.profile?.displayName,
+      });
+    }).pipe(Effect.provide(TestLayer), Effect.scoped, runAndForwardErrors));
+});

package/src/commands/halo/identity/identity.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+
+import { CommandConfig } from '@dxos/cli-util';
+import { print } from '@dxos/cli-util';
+import { ClientService } from '@dxos/client';
+
+import { printIdentity } from '../util';
+
+export const handler = Effect.fn(function* () {
+  const { json } = yield* CommandConfig;
+  const client = yield* ClientService;
+  const identity = client.halo.identity.get();
+  if (!identity) {
+    if (json) {
+      yield* Console.log(JSON.stringify({ error: 'Identity not initialized' }, null, 2));
+    } else {
+      yield* Console.log('Identity not initialized.');
+    }
+  } else {
+    if (json) {
+      yield* Console.log(
+        JSON.stringify(
+          {
+            identityKey: identity.identityKey.toHex(),
+            displayName: identity.profile?.displayName,
+          },
+          null,
+          2,
+        ),
+      );
+    } else {
+      yield* Console.log(print(printIdentity(identity)));
+    }
+  }
+});
+
+export const identity = Command.make('identity', {}, handler).pipe(
+  Command.withDescription('Get the current identity.'),
+);

package/src/commands/halo/identity/index.ts

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

package/src/commands/halo/index.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+
+import { create } from './create';
+import { credential } from './credential';
+import { identity } from './identity';
+// TODO(wittjosiah): Omitted currently due to p2p networking not working in bun.
+// import { join } from './join';
+import { keys } from './keys';
+import { recover } from './recover';
+import { seed } from './seed';
+// import { share } from './share';
+import { update } from './update';
+
+export const halo: Command.Command<any, any, any, any> = Command.make('halo').pipe(
+  Command.withDescription('Manage HALO identity.'),
+  Command.withSubcommands([create, credential, identity, keys, recover, seed, update]),
+);

package/src/commands/halo/join/index.ts

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

package/src/commands/halo/join/join.test.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+
+describe('halo join', () => {
+  // TODO(wittjosiah): Need to be able to test prompts.
+  it.todo('should accept an invitation code');
+});

package/src/commands/halo/join/join.ts

@@ -0,0 +1,87 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Args from '@effect/cli/Args';
+import * as Command from '@effect/cli/Command';
+import * as Prompt from '@effect/cli/Prompt';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import * as Match from 'effect/Match';
+
+import { CommandConfig, print } from '@dxos/cli-util';
+import { type Client, ClientService } from '@dxos/client';
+import { type AuthenticatingInvitationObservable, Invitation, InvitationEncoder } from '@dxos/client/invitations';
+import { invariant } from '@dxos/invariant';
+
+import { printIdentity } from '../util';
+
+export const join = Command.make(
+  'join',
+  {
+    invitationCode: Args.text({ name: 'invitationCode' }).pipe(Args.withDescription('The invitation code.')),
+  },
+  Effect.fn(function* ({ invitationCode }) {
+    const { json } = yield* CommandConfig;
+    const client = yield* ClientService;
+    // TODO(wittjosiah): How to surface this error to the user cleanly?
+    invariant(!client.halo.identity.get(), 'Identity already exists');
+
+    const identity = yield* sendInvitation({ client, invitationCode });
+    if (!identity) {
+      if (json) {
+        yield* Console.log(JSON.stringify({ error: 'Failed to join identity' }, null, 2));
+      } else {
+        yield* Console.log('Failed to join identity');
+      }
+      return;
+    }
+
+    if (json) {
+      yield* Console.log(
+        JSON.stringify(
+          {
+            identityKey: identity.identityKey.toHex(),
+            displayName: identity.profile?.displayName,
+          },
+          null,
+          2,
+        ),
+      );
+    } else {
+      yield* Console.log(print(printIdentity(identity)));
+    }
+  }),
+).pipe(Command.withDescription('Join an existing identity using an invitation code.'));
+
+const sendInvitation = Effect.fn(function* ({
+  client,
+  invitationCode: encoded,
+}: {
+  client: Client;
+  invitationCode: string;
+}) {
+  if (encoded.startsWith('http') || encoded.startsWith('socket')) {
+    const searchProps = new URL(encoded).searchParams;
+    encoded = searchProps.get('deviceInvitationCode') ?? encoded;
+  }
+
+  const invitationCode = InvitationEncoder.decode(encoded);
+  const invitation = client.halo.join(invitationCode);
+  yield* waitForState(invitation, Invitation.State.READY_FOR_AUTHENTICATION);
+
+  const authCode = yield* Prompt.text({ message: 'Enter the authentication code' }).pipe(Prompt.run);
+  yield* Effect.tryPromise(() => invitation.authenticate(authCode));
+  yield* waitForState(invitation, Invitation.State.SUCCESS);
+  return client.halo.identity.get();
+});
+
+const waitForState = (invitation: AuthenticatingInvitationObservable, state: Invitation.State) =>
+  Effect.gen(function* () {
+    const latch = yield* Effect.makeLatch();
+    const subscription = invitation.subscribe((invitation) => {
+      Match.value(invitation.state).pipe(Match.when(state, () => Effect.runSync(latch.open)));
+    });
+    yield* latch.await;
+    subscription.unsubscribe();
+  });

package/src/commands/halo/keys/index.ts

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

package/src/commands/halo/keys/keys.test.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { TestConsole, TestLayer } from '@dxos/cli-util/testing';
+import { ClientService } from '@dxos/client';
+import { runAndForwardErrors } from '@dxos/effect';
+
+import { handler } from './keys';
+
+describe('halo keys', () => {
+  it('should show HALO keys', () =>
+    Effect.gen(function* () {
+      const client = yield* ClientService;
+      yield* Effect.tryPromise(() => client.halo.createIdentity());
+      yield* handler();
+      const logger = yield* TestConsole.TestConsole;
+      const logs = logger.logs;
+      expect(logs).toHaveLength(1);
+      const parsed = TestConsole.parseJson<{ identityKey?: string; deviceKey?: string }>(logs[0]);
+      expect(parsed).toHaveProperty('identityKey');
+      expect(parsed).toHaveProperty('deviceKey');
+      expect(parsed.identityKey).toBe(client.halo.identity.get()?.identityKey.toHex());
+      expect(parsed.deviceKey).toBe(client.halo.device?.deviceKey.toHex());
+    }).pipe(Effect.provide(TestLayer), Effect.scoped, runAndForwardErrors));
+});

package/src/commands/halo/keys/keys.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+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 { FormBuilder, print } from '@dxos/cli-util';
+import { ClientService } from '@dxos/client';
+
+export const handler = Effect.fn(function* () {
+  const { json } = yield* CommandConfig;
+  const client = yield* ClientService;
+  const identity = client.halo.identity.get();
+  const device = client.halo.device;
+
+  if (json) {
+    yield* Console.log(
+      JSON.stringify(
+        {
+          identityKey: identity?.identityKey.toHex(),
+          deviceKey: device?.deviceKey.toHex(),
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    const builder = FormBuilder.make({ title: 'HALO Keys' }).pipe(
+      FormBuilder.option('identityKey', Option.fromNullable(identity?.identityKey.truncate())),
+      FormBuilder.option('deviceKey', Option.fromNullable(device?.deviceKey.truncate())),
+    );
+    yield* Console.log(print(FormBuilder.build(builder)));
+  }
+});
+
+export const keys = Command.make('keys', {}, handler).pipe(Command.withDescription('Show HALO keys.'));

package/src/commands/halo/recover/index.ts

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

package/src/commands/halo/recover/recover.test.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+
+describe('halo recover', () => {
+  // TODO(wittjosiah): Need to be able to test recovery flow.
+  it.todo('should recover identity with recovery code');
+});

package/src/commands/halo/recover/recover.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Args from '@effect/cli/Args';
+import * as Command from '@effect/cli/Command';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+
+import { CommandConfig, print } from '@dxos/cli-util';
+import { ClientService } from '@dxos/client';
+import { invariant } from '@dxos/invariant';
+
+import { printIdentity } from '../util';
+
+export const recover = Command.make(
+  'recover',
+  {
+    recoveryCode: Args.text({ name: 'recoveryCode' }).pipe(Args.withDescription('The recovery code seed phrase.')),
+  },
+  Effect.fn(function* ({ recoveryCode }) {
+    const { json } = yield* CommandConfig;
+    const client = yield* ClientService;
+    // TODO(wittjosiah): How to surface this error to the user cleanly?
+    invariant(!client.halo.identity.get(), 'Identity already exists');
+
+    const identity = yield* Effect.tryPromise(() => client.halo.recoverIdentity({ recoveryCode }));
+    if (json) {
+      yield* Console.log(
+        JSON.stringify(
+          {
+            identityKey: identity.identityKey.toHex(),
+            displayName: identity.profile?.displayName,
+          },
+          null,
+          2,
+        ),
+      );
+    } else {
+      yield* Console.log('Identity recovered successfully');
+      yield* Console.log(print(printIdentity(identity)));
+    }
+  }),
+).pipe(Command.withDescription('Recover an existing identity using a recovery code.'));

package/src/commands/halo/seed/index.ts

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

package/src/commands/halo/seed/seed.ts

@@ -0,0 +1,36 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+
+import { CommandConfig } from '@dxos/cli-util';
+import { ClientService } from '@dxos/client';
+
+export const handler = Effect.fn(function* () {
+  const { json } = yield* CommandConfig;
+  const client = yield* ClientService;
+  const identityService = client.services.services.IdentityService;
+  if (!identityService) {
+    if (json) {
+      yield* Console.log(JSON.stringify({ error: 'IdentityService not found' }, null, 2));
+    } else {
+      yield* Console.log('IdentityService not found.');
+    }
+    return;
+  }
+
+  const result = yield* Effect.tryPromise(() => identityService.createRecoveryCredential({}));
+
+  if (json) {
+    yield* Console.log(JSON.stringify({ recoveryCode: result.recoveryCode }, null, 2));
+  } else {
+    yield* Console.log(result.recoveryCode);
+  }
+});
+
+export const seed = Command.make('seed', {}, handler).pipe(
+  Command.withDescription('Generate a seedphrase that can be used for identity recovery.'),
+);

package/src/commands/halo/share/index.ts

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

package/src/commands/halo/share/share.ts

@@ -0,0 +1,97 @@
+//
+// 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, copyToClipboard, openBrowser, print } from '@dxos/cli-util';
+import { FormBuilder } from '@dxos/cli-util';
+import { ClientService } from '@dxos/client';
+import { Invitation, InvitationEncoder, hostInvitation } from '@dxos/client/invitations';
+
+export const handler = Effect.fn(function* ({
+  lifetime,
+  open,
+  host,
+}: {
+  lifetime: number;
+  open: boolean;
+  host: string;
+}) {
+  const { json } = yield* CommandConfig;
+  const client = yield* ClientService;
+
+  // Always use persistent and delegated (auth required) due to P2P limitations
+  const observable = client.halo.share({
+    authMethod: Invitation.AuthMethod.SHARED_SECRET,
+    persistent: true,
+    lifetime,
+  });
+
+  const invitation = yield* hostInvitation({
+    observable,
+    callbacks: {
+      onConnecting: (invitation) =>
+        Effect.gen(function* () {
+          const invitationCode = InvitationEncoder.encode(invitation);
+          const authCode = invitation.authCode!;
+
+          // Copy auth code to clipboard
+          yield* copyToClipboard(authCode).pipe(Effect.catchAll(() => Effect.void));
+
+          if (!json) {
+            yield* Console.log(`\nSecret: ${authCode} (copied to clipboard)\n`);
+          }
+
+          if (open) {
+            const url = new URL(host);
+            url.searchParams.append('deviceInvitationCode', invitationCode);
+            yield* openBrowser(url.toString()).pipe(Effect.catchAll(() => Effect.void));
+          } else if (!json) {
+            yield* Console.log(`\nInvitation: ${invitationCode}\n`);
+          }
+        }),
+    },
+    waitForSuccess: true,
+  });
+
+  if (json) {
+    yield* Console.log(
+      JSON.stringify(
+        {
+          invitationCode: InvitationEncoder.encode(invitation),
+          authCode: invitation.authCode,
+          state: Invitation.State[invitation.state],
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    const builder = FormBuilder.make({ title: 'HALO Invitation' }).pipe(
+      FormBuilder.set('invitationCode', InvitationEncoder.encode(invitation)),
+      FormBuilder.set('authCode', invitation.authCode ?? '<none>'),
+      FormBuilder.set('state', Invitation.State[invitation.state]),
+    );
+    yield* Console.log(print(FormBuilder.build(builder)));
+  }
+});
+
+export const share = Command.make(
+  'share',
+  {
+    lifetime: Options.integer('lifetime').pipe(
+      Options.withDescription('Lifetime of the invitation in seconds.'),
+      Options.withDefault(12 * 60 * 60), // 12 hours - HALO invitations are typically shorter-lived
+    ),
+    open: Options.boolean('open', { ifPresent: true }).pipe(Options.withDescription('Open browser with invitation.')),
+    host: Options.text('host').pipe(
+      Options.withDescription('Application Host URL.'),
+      Options.withDefault('https://composer.space'),
+    ),
+  },
+  handler,
+).pipe(Command.withDescription('Create HALO (device) invitation.'));

package/src/commands/halo/update/index.ts

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

package/src/commands/halo/update/update.test.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { TestConsole, TestLayer } from '@dxos/cli-util/testing';
+import { ClientService } from '@dxos/client';
+import { runAndForwardErrors } from '@dxos/effect';
+
+import { handler } from './update';
+
+describe('halo update', () => {
+  it('should update identity display name', () =>
+    Effect.gen(function* () {
+      const client = yield* ClientService;
+      yield* Effect.tryPromise(() => client.halo.createIdentity());
+      yield* handler({ displayName: 'Updated Name' });
+      const logger = yield* TestConsole.TestConsole;
+      const logs = logger.logs;
+      expect(logs).toHaveLength(1);
+      const parsed = TestConsole.parseJson<{ identityKey: string; displayName: string }>(logs[0]);
+      expect(parsed).toHaveProperty('identityKey');
+      expect(parsed).toHaveProperty('displayName', 'Updated Name');
+      expect(parsed.identityKey).toBe(client.halo.identity.get()?.identityKey.toHex());
+    }).pipe(Effect.provide(TestLayer), Effect.scoped, runAndForwardErrors));
+});