@dxos/cli-util 0.8.4-main.fcfe5033a5 → 0.8.4-staging.60fe92afc8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/cli-util",
-  "version": "0.8.4-main.fcfe5033a5",
+  "version": "0.8.4-staging.60fe92afc8",
   "description": "Shared CLI utilities for DXOS CLI commands and plugins",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": false,
   "type": "module",
@@ -30,27 +30,29 @@
     "src"
   ],
   "dependencies": {
-    "@effect/cli": "0.73.2",
-    "@effect/printer": "0.47.0",
-    "@effect/printer-ansi": "0.47.0",
-    "@dxos/app-toolkit": "0.8.4-main.fcfe5033a5",
-    "@dxos/echo": "0.8.4-main.fcfe5033a5",
-    "@dxos/debug": "0.8.4-main.fcfe5033a5",
-    "@dxos/client": "0.8.4-main.fcfe5033a5",
-    "@dxos/effect": "0.8.4-main.fcfe5033a5",
-    "@dxos/functions": "0.8.4-main.fcfe5033a5",
-    "@dxos/errors": "0.8.4-main.fcfe5033a5",
-    "@dxos/log": "0.8.4-main.fcfe5033a5",
-    "@dxos/protocols": "0.8.4-main.fcfe5033a5",
-    "@dxos/util": "0.8.4-main.fcfe5033a5"
+    "@effect/cli": "0.75.2",
+    "@effect/printer": "0.49.0",
+    "@effect/printer-ansi": "0.49.0",
+    "@dxos/app-toolkit": "0.8.4-staging.60fe92afc8",
+    "@dxos/client": "0.8.4-staging.60fe92afc8",
+    "@dxos/compute": "0.8.4-staging.60fe92afc8",
+    "@dxos/debug": "0.8.4-staging.60fe92afc8",
+    "@dxos/echo-client": "0.8.4-staging.60fe92afc8",
+    "@dxos/effect": "0.8.4-staging.60fe92afc8",
+    "@dxos/echo": "0.8.4-staging.60fe92afc8",
+    "@dxos/errors": "0.8.4-staging.60fe92afc8",
+    "@dxos/log": "0.8.4-staging.60fe92afc8",
+    "@dxos/functions": "0.8.4-staging.60fe92afc8",
+    "@dxos/protocols": "0.8.4-staging.60fe92afc8",
+    "@dxos/util": "0.8.4-staging.60fe92afc8"
   },
   "devDependencies": {
-    "effect": "3.20.0",
+    "effect": "3.21.3",
     "typescript": "^6.0.3",
-    "vitest": "3.2.4"
+    "vitest": "4.1.7"
   },
   "peerDependencies": {
-    "effect": "3.20.0"
+    "effect": "3.21.3"
   },
   "publishConfig": {
     "access": "public"

package/src/util/form-builder.test.ts

@@ -8,11 +8,11 @@ import * as Effect from 'effect/Effect';
 import * as Option from 'effect/Option';
 
 import { FormBuilder, print } from '@dxos/cli-util';
-import { runAndForwardErrors } from '@dxos/effect';
+import { EffectEx } from '@dxos/effect';
 
 describe('FormBuilder', () => {
   it('option', () =>
-    runAndForwardErrors(
+    EffectEx.runAndForwardErrors(
       Effect.gen(function* () {
         const builder = FormBuilder.make({ title: 'Option Test' }).pipe(
           FormBuilder.option('some', Option.some('value')),
@@ -25,7 +25,7 @@ describe('FormBuilder', () => {
     ));
 
   it('when', () =>
-    runAndForwardErrors(
+    EffectEx.runAndForwardErrors(
       Effect.gen(function* () {
         const builder = FormBuilder.make({ title: 'When Test' }).pipe(
           FormBuilder.when(true, FormBuilder.set('included', 'true')),
@@ -38,7 +38,7 @@ describe('FormBuilder', () => {
     ));
 
   it('each', () =>
-    runAndForwardErrors(
+    EffectEx.runAndForwardErrors(
       Effect.gen(function* () {
         const items = ['a', 'b', 'c'];
         const builder = FormBuilder.make({ title: 'Each Test' }).pipe(
@@ -51,7 +51,7 @@ describe('FormBuilder', () => {
     ));
 
   it('build', () =>
-    runAndForwardErrors(
+    EffectEx.runAndForwardErrors(
       Effect.gen(function* () {
         const builder = FormBuilder.make({ title: 'Test' }).pipe(
           FormBuilder.set('foo', 100),
@@ -64,7 +64,7 @@ describe('FormBuilder', () => {
     ));
 
   it('nest', () =>
-    runAndForwardErrors(
+    EffectEx.runAndForwardErrors(
       Effect.gen(function* () {
         const nested = FormBuilder.make({ title: 'Nested' }).pipe(
           FormBuilder.set('nested1', 'value1'),
@@ -83,7 +83,7 @@ describe('FormBuilder', () => {
     ));
 
   it('nestedOption', () =>
-    runAndForwardErrors(
+    EffectEx.runAndForwardErrors(
       Effect.gen(function* () {
         const nested = FormBuilder.make({ title: 'Nested' }).pipe(FormBuilder.set('key', 'value'));
 
@@ -98,7 +98,7 @@ describe('FormBuilder', () => {
     ));
 
   it('multi-level nesting', () =>
-    runAndForwardErrors(
+    EffectEx.runAndForwardErrors(
       Effect.gen(function* () {
         const grandchild = FormBuilder.make({ title: 'Grandchild' }).pipe(
           FormBuilder.set('grandchild1', 'value1'),
@@ -123,7 +123,7 @@ describe('FormBuilder', () => {
     ));
 
   it('pipeable build', () =>
-    runAndForwardErrors(
+    EffectEx.runAndForwardErrors(
       Effect.gen(function* () {
         const doc = FormBuilder.make({ title: 'Pipeable' }).pipe(
           FormBuilder.set('foo', 100),
@@ -135,7 +135,7 @@ describe('FormBuilder', () => {
     ));
 
   it('dual calling styles', () =>
-    runAndForwardErrors(
+    EffectEx.runAndForwardErrors(
       Effect.gen(function* () {
         // Curried style (pipe)
         const builder1 = FormBuilder.make({ title: 'Curried' }).pipe(

package/src/util/space-format.ts

@@ -2,40 +2,114 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Duration from 'effect/Duration';
 import * as Effect from 'effect/Effect';
 
 import { type Space, SpaceState, type SpaceSyncState } from '@dxos/client/echo';
 
 import * as FormBuilder from './form-builder';
 
+export type FormatSpaceOptions = {
+  verbose?: boolean;
+  truncateKeys?: boolean;
+  /**
+   * If set, wait up to this many seconds for the space to reach
+   * `SPACE_READY` before reading its fields. If unset, read whatever state
+   * is available right now — much safer for `space list` etc., where a
+   * single stuck space would otherwise hang the entire command.
+   */
+  waitSeconds?: number;
+};
+
+const DEFAULT_OPTIONS: Required<FormatSpaceOptions> = {
+  verbose: false,
+  truncateKeys: false,
+  waitSeconds: 0,
+};
+
+/**
+ * Per-async-read internal timeout. Some `space.internal.*` getters do
+ * filesystem / network IO and can themselves hang on a partially-loaded
+ * space; cap each one so the command can never be held hostage by SDK
+ * internals.
+ */
+const READ_TIMEOUT_SECONDS = 2;
+
+const tryWithFallback = <T>(label: string, run: () => Promise<T>, fallback: T) =>
+  Effect.tryPromise(run).pipe(
+    Effect.timeoutFail({
+      duration: Duration.seconds(READ_TIMEOUT_SECONDS),
+      onTimeout: () => new Error(`${label} timed out`),
+    }),
+    Effect.catchAll(() => Effect.succeed(fallback)),
+  );
+
+const tryWithFallbackSync = <T>(read: () => T, fallback: T): T => {
+  try {
+    return read();
+  } catch {
+    return fallback;
+  }
+};
+
 // TODO(wittjosiah): Use @effect/printer.
-export const formatSpace = Effect.fn(function* (space: Space, options = { verbose: false, truncateKeys: false }) {
-  yield* Effect.tryPromise(() => space.waitUntilReady());
+export const formatSpace = Effect.fn(function* (space: Space, options: FormatSpaceOptions = {}) {
+  const { waitSeconds } = { ...DEFAULT_OPTIONS, ...options };
+
+  // Opt-in wait. Defaults to NO wait so a single stuck space can't hang
+  // an enumeration command (e.g. `dx space list`).
+  if (waitSeconds > 0) {
+    yield* Effect.tryPromise(() => space.waitUntilReady()).pipe(
+      Effect.timeoutFail({
+        duration: Duration.seconds(waitSeconds),
+        onTimeout: () => new Error('waitUntilReady timed out'),
+      }),
+      Effect.catchAll(() => Effect.void),
+    );
+  }
+
+  const state = tryWithFallbackSync(() => space.state.get(), SpaceState.SPACE_INITIALIZING);
+  const ready = state === SpaceState.SPACE_READY;
 
   // TODO(burdon): Factor out.
   // TODO(burdon): Agent needs to restart before `ready` is available.
-  const { open, ready } = space.internal.data.metrics ?? {};
-  const startup = open && ready && ready.getTime() - open.getTime();
+  const metrics = tryWithFallbackSync(
+    () => space.internal.data.metrics,
+    undefined as { open?: Date; ready?: Date } | undefined,
+  );
+  const startup = metrics?.open && metrics?.ready ? metrics.ready.getTime() - metrics.open.getTime() : undefined;
 
   // TODO(burdon): Get feeds from client-services if verbose (factor out from devtools/diagnostics).
   // const host = client.services.services.DevtoolsHost!;
-  const pipeline = space.internal.data.pipeline;
+  const pipeline = tryWithFallbackSync(() => space.internal.data.pipeline, undefined);
   const epoch = pipeline?.currentEpoch?.subject.assertion.number;
 
-  const syncState = aggregateSyncState(yield* Effect.tryPromise(() => space.internal.db.coreDatabase.getSyncState()));
+  // The sync-state read does IO; cap it so a stuck space can't hang the
+  // command. Falls back to a "no peers" placeholder.
+  const syncStateRaw = yield* tryWithFallback('getSyncState', () => space.internal.db.getSyncState(), {
+    peers: {},
+  } as SpaceSyncState);
+  const syncState = aggregateSyncState(syncStateRaw);
+
+  const name = ready ? tryWithFallbackSync(() => space.properties.name, undefined) : 'loading...';
+  const members = tryWithFallbackSync(() => space.members.get().length, 0);
+  const objects = tryWithFallbackSync(() => space.internal.db.getAllObjectIds().length, 0);
+  const key = options.truncateKeys
+    ? tryWithFallbackSync(() => space.key.truncate(), '')
+    : tryWithFallbackSync(() => space.key.toHex(), '');
 
   return {
     id: space.id,
-    state: SpaceState[space.state.get()],
-    name: space.state.get() === SpaceState.SPACE_READY ? space.properties.name : 'loading...',
+    state: SpaceState[state],
+    name,
 
-    members: space.members.get().length,
-    objects: space.internal.db.coreDatabase.getAllObjectIds().length,
+    members,
+    objects,
 
-    key: options.truncateKeys ? space.key.truncate() : space.key.toHex(),
+    key,
     epoch,
     startup,
-    automergeRoot: space.internal.data.pipeline?.spaceRootUrl,
+    automergeRoot: pipeline?.spaceRootUrl,
     // appliedEpoch,
     syncState: `${syncState.count} ${getSyncIndicator(syncState.up, syncState.down)} (${syncState.peers} peers)`,
   };

package/src/util/space.ts

@@ -5,15 +5,14 @@
 import * as Console from 'effect/Console';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
-import * as Match from 'effect/Match';
 import * as Option from 'effect/Option';
 
 import { getPersonalSpace } from '@dxos/app-toolkit';
 import { ClientService } from '@dxos/client';
 import { type Space } from '@dxos/client/echo';
-import { Database, type Key } from '@dxos/echo';
+import { Database, Feed, type Key } from '@dxos/echo';
+import { createFeedServiceLayer } from '@dxos/echo-client';
 import { BaseError, type BaseErrorOptions } from '@dxos/errors';
-import { QueueService } from '@dxos/functions';
 import { log } from '@dxos/log';
 import { EdgeReplicationSetting } from '@dxos/protocols/proto/dxos/echo/metadata';
 import { isBun } from '@dxos/util';
@@ -40,20 +39,29 @@ export const spaceIdWithDefault = (spaceId: Option.Option<Key.SpaceId>) =>
 export const spaceLayer = (
   spaceId$: Option.Option<Key.SpaceId>,
   fallbackToPersonalSpace = false,
-): Layer.Layer<Database.Service | QueueService, never, ClientService> => {
+): Layer.Layer<Database.Service | Feed.FeedService, never, ClientService> => {
   const getSpace = Effect.fn(function* () {
     const client = yield* ClientService;
 
-    const spaceId = Match.value(fallbackToPersonalSpace).pipe(
-      Match.when(true, () => spaceId$.pipe(Option.orElse(() => Option.fromNullable(getPersonalSpace(client)?.id)))),
-      Match.when(false, () => spaceId$),
-      Match.exhaustive,
-    );
+    // Resolution order when fallbackToPersonalSpace is true:
+    //   1. the explicit spaceId arg (if provided);
+    //   2. the space tagged `org.dxos.space.personal`;
+    //   3. the first available space.
+    // This keeps profiles created outside composer-app (which is what creates
+    // the personal-space tag on identity creation) usable — the alternative
+    // is a "Space not found" throw deep inside CredentialsService.
+    const resolveSpace = () => {
+      if (!fallbackToPersonalSpace) {
+        return spaceId$.pipe(Option.flatMap((id) => Option.fromNullable(client.spaces.get(id))));
+      }
+      return spaceId$.pipe(
+        Option.flatMap((id) => Option.fromNullable(client.spaces.get(id))),
+        Option.orElse(() => Option.fromNullable(getPersonalSpace(client))),
+        Option.orElse(() => Option.fromNullable(client.spaces.get()[0])),
+      );
+    };
 
-    const space = spaceId.pipe(
-      Option.flatMap((id) => Option.fromNullable(client.spaces.get(id))),
-      Option.getOrUndefined,
-    );
+    const space = resolveSpace().pipe(Option.getOrUndefined);
 
     if (space) {
       yield* Effect.promise(() => space.waitUntilReady());
@@ -61,49 +69,41 @@ export const spaceLayer = (
     return space;
   });
 
+  // When no space can be resolved we install a stub whose `db` getter throws
+  // on access — preserves the existing semantics for commands that *do* need
+  // a db — but the release callback must NOT touch `db` or it will throw
+  // during teardown (e.g. after a command emits a friendly error and
+  // returns early). A shared sentinel object short-circuits the release.
+  const NO_DB_STUB = {
+    get db(): Database.Database {
+      throw new Error('Space not found');
+    },
+  };
   const db = Layer.scoped(
     Database.Service,
     Effect.acquireRelease(
       Effect.gen(function* () {
         const space = yield* getSpace();
         if (!space) {
-          return {
-            get db(): Database.Database {
-              throw new Error('Space not found');
-            },
-          };
+          return NO_DB_STUB;
         }
         return { db: space.db };
       }),
-      ({ db }) => Effect.promise(() => db.flush()),
+      (holder) => (holder === NO_DB_STUB ? Effect.void : Effect.promise(() => holder.db.flush())),
     ),
   );
 
-  const queue = Layer.effect(
-    QueueService,
+  const feed = Layer.unwrapEffect(
     Effect.gen(function* () {
       const space = yield* getSpace();
       if (!space) {
-        return {
-          queues: {
-            get: (_dxn) => {
-              throw new Error('Queues not available');
-            },
-            create: () => {
-              throw new Error('Queues not available');
-            },
-          },
-          queue: undefined,
-        };
+        return Feed.notAvailable;
       }
-      return {
-        queues: space.queues,
-        queue: undefined,
-      };
+      return createFeedServiceLayer(space.queues);
     }),
   );
 
-  return Layer.merge(db, queue);
+  return Layer.merge(db, feed);
 };
 
 // TODO(dmaretskyi): There a race condition with edge connection not showing up.