@dxos/cli-util 0.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+MIT License
+Copyright (c) 2025 DXOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @dxos/cli-util
+
+Shared CLI utilities for DXOS CLI commands and plugins.
+
+This package provides common utilities that can be used by both the CLI and CLI plugins:
+
+- **CommandConfig**: Effect service for CLI command configuration (json, verbose, profile, logLevel)
+- **Print utilities**: Functions for pretty-printing documents with ANSI colors
+- **FormBuilder**: Builder for creating formatted form output
+
+## Usage
+
+```typescript
+import { CommandConfig } from '@dxos/cli-util/services';
+import { print, FormBuilder } from '@dxos/cli-util/util';
+```

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@dxos/cli-util",
+  "version": "0.0.0",
+  "description": "Shared CLI utilities for DXOS CLI commands and plugins",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "node": "./dist/lib/node-esm/index.mjs"
+    },
+    "./testing": {
+      "source": "./src/testing/index.ts",
+      "types": "./dist/types/src/testing/index.d.ts",
+      "node": "./dist/lib/node-esm/testing/index.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@effect/cli": "0.72.1",
+    "@effect/printer": "0.47.0",
+    "@effect/printer-ansi": "0.47.0",
+    "@dxos/client": "0.8.3",
+    "@dxos/effect": "0.8.3",
+    "@dxos/echo": "0.8.3",
+    "@dxos/errors": "0.8.3",
+    "@dxos/log": "0.8.3",
+    "@dxos/functions": "0.8.3",
+    "@dxos/util": "0.8.3",
+    "@dxos/debug": "0.8.3",
+    "@dxos/protocols": "0.8.3"
+  },
+  "devDependencies": {
+    "effect": "3.19.11",
+    "typescript": "^5.9.3",
+    "vitest": "3.2.4"
+  },
+  "peerDependencies": {
+    "effect": "3.19.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './services';
+export * from './util';

package/src/services/command-config.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+export class CommandConfig extends Context.Tag('CommandConfig')<
+  CommandConfig,
+  {
+    json: boolean;
+    verbose: boolean;
+    profile: string;
+    logLevel: string;
+  }
+>() {
+  static isJson: Effect.Effect<boolean, never, CommandConfig> = CommandConfig.pipe(Effect.map((config) => config.json));
+  static isVerbose: Effect.Effect<boolean, never, CommandConfig> = CommandConfig.pipe(
+    Effect.map((config) => config.verbose),
+  );
+
+  static layerTest = Layer.succeed(CommandConfig, {
+    json: true,
+    verbose: false,
+    profile: 'default',
+    logLevel: 'info',
+  });
+}

package/src/services/index.ts

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

package/src/testing/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './test-console';
+export * from './test-layer';

package/src/testing/test-console.ts

@@ -0,0 +1,88 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { inspect } from 'node:util';
+
+import * as Console from 'effect/Console';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+function logToString(...args: any[]): string {
+  return args
+    .map((arg) => {
+      if (typeof arg === 'string') {
+        return arg;
+      }
+
+      return inspect(arg, { colors: false, depth: null });
+    })
+    .join(' ');
+}
+
+class TestConsoleService {
+  private _logs: Array<{ level: string; args: unknown; message: string }> = [];
+
+  readonly console: Console.Console;
+
+  constructor(console: Console.Console) {
+    const pusher =
+      (level: string) =>
+      (...args: readonly any[]) => {
+        this._logs.push({ level, args, message: logToString(...args) });
+      };
+
+    this.console = {
+      ...console,
+      log: (...args: readonly any[]) => Effect.sync(() => pusher('log')(...args)),
+    };
+  }
+
+  get logs() {
+    return [...this._logs];
+  }
+
+  clear() {
+    this._logs.length = 0;
+  }
+}
+
+// TODO(burdon): We could have a single namespace "Testing" with all test utilities.
+export namespace TestConsole {
+  export class TestConsole extends Context.Tag('TestConsole')<TestConsole, TestConsoleService>() {}
+
+  /**
+   * Extract JSON string from log arguments.
+   * Handles both array and string argument formats.
+   */
+  export const extractJsonString = (log: { args: unknown }): string => {
+    if (Array.isArray(log.args) && log.args.length > 0) {
+      return String(log.args[0]);
+    }
+    return log.args as string;
+  };
+
+  /**
+   * Parse JSON from log arguments.
+   * Handles both array and string argument formats.
+   */
+  export const parseJson = <T = unknown>(log: { args: unknown }): T => {
+    const jsonString = extractJsonString(log);
+    return JSON.parse(jsonString) as T;
+  };
+
+  const testConsole = Layer.effect(
+    TestConsole,
+    Effect.gen(function* () {
+      return new TestConsoleService(yield* Effect.console);
+    }),
+  );
+
+  const setConsole = Effect.gen(function* () {
+    const { console } = yield* TestConsole;
+    return Console.setConsole(console);
+  }).pipe(Layer.unwrapEffect);
+
+  export const layer = Layer.provideMerge(setConsole, testConsole);
+}

package/src/testing/test-layer.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Function from 'effect/Function';
+import * as Layer from 'effect/Layer';
+
+import { ClientService, ConfigService } from '@dxos/client';
+
+import { CommandConfig } from '../services';
+
+import { TestConsole } from './test-console';
+
+export const TestLayer = Function.pipe(
+  ClientService.layer,
+  Layer.provideMerge(ConfigService.layerMemory),
+  Layer.provideMerge(TestConsole.layer),
+  Layer.provideMerge(CommandConfig.layerTest),
+);

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

@@ -0,0 +1,157 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { FormBuilder, print } from '@dxos/cli-util';
+import { runAndForwardErrors } from '@dxos/effect';
+
+describe('FormBuilder', () => {
+  it('option', () =>
+    runAndForwardErrors(
+      Effect.gen(function* () {
+        const builder = FormBuilder.make({ title: 'Option Test' }).pipe(
+          FormBuilder.option('some', Option.some('value')),
+          FormBuilder.option('none', Option.none()),
+        );
+
+        const doc = FormBuilder.build(builder);
+        yield* Console.log(print(doc));
+      }),
+    ));
+
+  it('when', () =>
+    runAndForwardErrors(
+      Effect.gen(function* () {
+        const builder = FormBuilder.make({ title: 'When Test' }).pipe(
+          FormBuilder.when(true, FormBuilder.set('included', 'true')),
+          FormBuilder.when(false, FormBuilder.set('excluded', 'false')),
+        );
+
+        const doc = FormBuilder.build(builder);
+        yield* Console.log(print(doc));
+      }),
+    ));
+
+  it('each', () =>
+    runAndForwardErrors(
+      Effect.gen(function* () {
+        const items = ['a', 'b', 'c'];
+        const builder = FormBuilder.make({ title: 'Each Test' }).pipe(
+          FormBuilder.each(items, (item) => FormBuilder.set('item', item)),
+        );
+
+        const doc = FormBuilder.build(builder);
+        yield* Console.log(print(doc));
+      }),
+    ));
+
+  it('build', () =>
+    runAndForwardErrors(
+      Effect.gen(function* () {
+        const builder = FormBuilder.make({ title: 'Test' }).pipe(
+          FormBuilder.set('foo', 100),
+          FormBuilder.set('bar', true),
+        );
+
+        const doc = FormBuilder.build(builder);
+        yield* Console.log(print(doc));
+      }),
+    ));
+
+  it('nest', () =>
+    runAndForwardErrors(
+      Effect.gen(function* () {
+        const nested = FormBuilder.make({ title: 'Nested' }).pipe(
+          FormBuilder.set('nested1', 'value1'),
+          FormBuilder.set('nested2', 42),
+        );
+
+        const builder = FormBuilder.make({ title: 'Parent' }).pipe(
+          FormBuilder.set('top', 'top-level'),
+          FormBuilder.nest('child', nested),
+          FormBuilder.set('bottom', 'bottom-level'),
+        );
+
+        const doc = FormBuilder.build(builder);
+        yield* Console.log(print(doc));
+      }),
+    ));
+
+  it('nestedOption', () =>
+    runAndForwardErrors(
+      Effect.gen(function* () {
+        const nested = FormBuilder.make({ title: 'Nested' }).pipe(FormBuilder.set('key', 'value'));
+
+        const builder = FormBuilder.make({ title: 'Parent' }).pipe(
+          FormBuilder.nestedOption('some', Option.some(nested)),
+          FormBuilder.nestedOption('none', Option.none()),
+        );
+
+        const doc = FormBuilder.build(builder);
+        yield* Console.log(print(doc));
+      }),
+    ));
+
+  it('multi-level nesting', () =>
+    runAndForwardErrors(
+      Effect.gen(function* () {
+        const grandchild = FormBuilder.make({ title: 'Grandchild' }).pipe(
+          FormBuilder.set('grandchild1', 'value1'),
+          FormBuilder.set('grandchild2', 'value2'),
+        );
+
+        const child = FormBuilder.make({ title: 'Child' }).pipe(
+          FormBuilder.set('child1', 'value1'),
+          FormBuilder.nest('grandchild', grandchild),
+          FormBuilder.set('child2', 'value2'),
+        );
+
+        const parent = FormBuilder.make({ title: 'Parent' }).pipe(
+          FormBuilder.set('top', 'top-level'),
+          FormBuilder.nest('child', child),
+          FormBuilder.set('bottom', 'bottom-level'),
+        );
+
+        const doc = FormBuilder.build(parent);
+        yield* Console.log(print(doc));
+      }),
+    ));
+
+  it('pipeable build', () =>
+    runAndForwardErrors(
+      Effect.gen(function* () {
+        const doc = FormBuilder.make({ title: 'Pipeable' }).pipe(
+          FormBuilder.set('foo', 100),
+          FormBuilder.set('bar', true),
+          FormBuilder.build,
+        );
+        yield* Console.log(print(doc));
+      }),
+    ));
+
+  it('dual calling styles', () =>
+    runAndForwardErrors(
+      Effect.gen(function* () {
+        // Curried style (pipe)
+        const builder1 = FormBuilder.make({ title: 'Curried' }).pipe(
+          FormBuilder.set('key1', 'value1'),
+          FormBuilder.option('key2', Option.some('value2')),
+        );
+
+        // Direct style
+        const builder2 = FormBuilder.make({ title: 'Direct' });
+        FormBuilder.set(builder2, 'key1', 'value1');
+        FormBuilder.option(builder2, 'key2', Option.some('value2'));
+
+        const doc1 = FormBuilder.build(builder1);
+        const doc2 = FormBuilder.build(builder2);
+        yield* Console.log('Curried:', print(doc1));
+        yield* Console.log('Direct:', print(doc2));
+      }),
+    ));
+});

package/src/util/form-builder.ts

@@ -0,0 +1,358 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Doc from '@effect/printer/Doc';
+import * as Ansi from '@effect/printer-ansi/Ansi';
+import * as Option from 'effect/Option';
+import * as Pipeable from 'effect/Pipeable';
+
+export type FormBuilderOptions = {
+  title?: string;
+  prefix?: string;
+};
+
+export interface FormBuilder extends Pipeable.Pipeable {
+  readonly entries: ReadonlyArray<{ key: string; value: Doc.Doc<any>; isNested?: boolean }>;
+  readonly title?: string;
+  readonly prefix: string;
+}
+
+class FormBuilderImpl implements FormBuilder {
+  readonly entries: Array<{ key: string; value: Doc.Doc<any>; isNested?: boolean }> = [];
+  readonly title?: string;
+  readonly prefix: string;
+
+  constructor(options: FormBuilderOptions = {}) {
+    this.title = options.title;
+    this.prefix = options.prefix ?? '- ';
+  }
+
+  pipe() {
+    // eslint-disable-next-line prefer-rest-params
+    return Pipeable.pipeArguments(this, arguments);
+  }
+}
+
+/**
+ * Creates a new FormBuilder instance.
+ */
+export const make = (props?: FormBuilderOptions): FormBuilder => new FormBuilderImpl(props);
+
+// Helper to calculate dimensions for formatting
+const calculateDimensions = (entries: ReadonlyArray<{ key: string }>, prefix: string) => {
+  const maxKeyLen = Math.max(0, ...entries.map((entry) => entry.key.length));
+  const targetWidth = prefix.length + maxKeyLen + 2;
+  return { maxKeyLen, targetWidth };
+};
+
+// Helper to build a formatted key line
+const buildKeyLine = (prefix: string, key: string, targetWidth: number) => {
+  // Use fill to pad the key to targetWidth.
+  // Note: We don't add indentation here; indentation is handled by the parent container or nestImpl.
+  return Doc.annotate(Doc.fill(targetWidth)(Doc.text(prefix + key + ': ')), Ansi.blackBright);
+};
+
+// Implementation helper
+const setImpl = <T>(
+  builder: FormBuilder,
+  key: string,
+  value: T,
+  color?: Ansi.Ansi | ((value: T) => Ansi.Ansi),
+): FormBuilder => {
+  if (value !== undefined) {
+    let valueDoc: Doc.Doc<any>;
+    if (typeof value === 'object' && value !== null) {
+      // Assume it's a Doc.Doc
+      valueDoc = value as unknown as Doc.Doc<any>;
+    } else {
+      valueDoc = Doc.text(String(value));
+    }
+
+    if (color) {
+      const ansi = typeof color === 'function' ? color(value as T) : color;
+      valueDoc = Doc.annotate(valueDoc, ansi);
+    }
+
+    (builder as FormBuilderImpl).entries.push({
+      key,
+      value: valueDoc,
+      isNested: false,
+    });
+  }
+  return builder;
+};
+
+/**
+ * Adds a key-value pair to the form.
+ */
+export function set<T>(
+  builder: FormBuilder,
+  key: string,
+  value: T,
+  color?: Ansi.Ansi | ((value: T) => Ansi.Ansi),
+): FormBuilder;
+export function set<T>(
+  key: string,
+  value: T,
+  color?: Ansi.Ansi | ((value: T) => Ansi.Ansi),
+): (builder: FormBuilder) => FormBuilder;
+export function set<T>(
+  builderOrKey: FormBuilder | string,
+  keyOrValue?: string | T,
+  valueOrColor?: T | Ansi.Ansi | ((value: T) => Ansi.Ansi),
+  color?: Ansi.Ansi | ((value: T) => Ansi.Ansi),
+): FormBuilder | ((builder: FormBuilder) => FormBuilder) {
+  if (builderOrKey instanceof FormBuilderImpl) {
+    // Direct: set(builder, key, value, color?)
+    const builder = builderOrKey;
+    const key = keyOrValue as string;
+    const value = valueOrColor as T;
+    return setImpl(builder, key, value, color);
+  } else {
+    // Curried: set(key, value, color?)
+    const key = builderOrKey as string;
+    const value = keyOrValue as T;
+    const color = valueOrColor as Ansi.Ansi | ((value: T) => Ansi.Ansi) | undefined;
+    return (builder: FormBuilder) => setImpl(builder, key, value, color);
+  }
+}
+
+// Implementation helper
+const nestImpl = (parent: FormBuilder, key: string, builder: FormBuilder): FormBuilder => {
+  // Build nested entries without title, directly under the parent field name
+
+  // Create a temporary builder without title to ignore it.
+  const nestedBuilder: FormBuilder = {
+    ...builder,
+    title: undefined,
+    entries: builder.entries,
+  };
+
+  // Build content.
+  let valueDoc = build(nestedBuilder);
+
+  // Indent the content by 2 spaces.
+  // This ensures that when this doc is embedded in the parent, it is visually nested.
+  valueDoc = Doc.indent(valueDoc, 2);
+
+  (parent.entries as Array<{ key: string; value: Doc.Doc<any>; isNested?: boolean }>).push({
+    key,
+    value: valueDoc,
+    isNested: true,
+  });
+  return parent;
+};
+
+/**
+ * Nests another form builder under a key.
+ */
+export function nest(parent: FormBuilder, key: string, builder: FormBuilder): FormBuilder;
+export function nest(key: string, builder: FormBuilder): (parent: FormBuilder) => FormBuilder;
+export function nest(
+  parentOrKey: FormBuilder | string,
+  keyOrBuilder?: string | FormBuilder,
+  builder?: FormBuilder,
+): FormBuilder | ((parent: FormBuilder) => FormBuilder) {
+  if (parentOrKey instanceof FormBuilderImpl) {
+    // Direct: nest(parent, key, builder)
+    const parent = parentOrKey;
+    const key = keyOrBuilder as string;
+    return nestImpl(parent, key, builder!);
+  } else {
+    // Curried: nest(key, builder)
+    const key = parentOrKey as string;
+    const builder = keyOrBuilder as FormBuilder;
+    return (parent: FormBuilder) => nestImpl(parent, key, builder);
+  }
+}
+
+// Implementation helper
+const optionImpl = <T>(
+  builder: FormBuilder,
+  key: string,
+  value: Option.Option<T>,
+  color?: Ansi.Ansi | ((value: T) => Ansi.Ansi),
+): FormBuilder => {
+  if (Option.isSome(value)) {
+    return setImpl(builder, key, value.value, color);
+  }
+  return builder;
+};
+
+/**
+ * Adds an optional value if it exists.
+ */
+export function option<T>(
+  builder: FormBuilder,
+  key: string,
+  value: Option.Option<T>,
+  color?: Ansi.Ansi | ((value: T) => Ansi.Ansi),
+): FormBuilder;
+export function option<T>(
+  key: string,
+  value: Option.Option<T>,
+  color?: Ansi.Ansi | ((value: T) => Ansi.Ansi),
+): (builder: FormBuilder) => FormBuilder;
+export function option<T>(
+  builderOrKey: FormBuilder | string,
+  keyOrValue?: string | Option.Option<T>,
+  valueOrColor?: Option.Option<T> | Ansi.Ansi | ((value: T) => Ansi.Ansi),
+  color?: Ansi.Ansi | ((value: T) => Ansi.Ansi),
+): FormBuilder | ((builder: FormBuilder) => FormBuilder) {
+  if (builderOrKey instanceof FormBuilderImpl) {
+    // Direct: option(builder, key, value, color?)
+    const builder = builderOrKey;
+    const key = keyOrValue as string;
+    const value = valueOrColor as Option.Option<T>;
+    return optionImpl(builder, key, value, color);
+  } else {
+    // Curried: option(key, value, color?)
+    const key = builderOrKey as string;
+    const value = keyOrValue as Option.Option<T>;
+    const color = valueOrColor as Ansi.Ansi | ((value: T) => Ansi.Ansi) | undefined;
+    return (builder: FormBuilder) => optionImpl(builder, key, value, color);
+  }
+}
+
+// Implementation helper
+const nestedOptionImpl = (builder: FormBuilder, key: string, value: Option.Option<FormBuilder>): FormBuilder => {
+  if (Option.isSome(value)) {
+    return nestImpl(builder, key, value.value);
+  }
+  return builder;
+};
+
+/**
+ * Nests an optional form builder if it exists.
+ */
+export function nestedOption(builder: FormBuilder, key: string, value: Option.Option<FormBuilder>): FormBuilder;
+export function nestedOption(key: string, value: Option.Option<FormBuilder>): (builder: FormBuilder) => FormBuilder;
+export function nestedOption(
+  builderOrKey: FormBuilder | string,
+  keyOrValue?: string | Option.Option<FormBuilder>,
+  value?: Option.Option<FormBuilder>,
+): FormBuilder | ((builder: FormBuilder) => FormBuilder) {
+  if (builderOrKey instanceof FormBuilderImpl) {
+    // Direct: nestedOption(builder, key, value)
+    const builder = builderOrKey;
+    const key = keyOrValue as string;
+    return nestedOptionImpl(builder, key, value!);
+  } else {
+    // Curried: nestedOption(key, value)
+    const key = builderOrKey as string;
+    const value = keyOrValue as Option.Option<FormBuilder>;
+    return (builder: FormBuilder) => nestedOptionImpl(builder, key, value);
+  }
+}
+
+// Implementation helper
+const whenImpl = (builder: FormBuilder, condition: any, ...ops: ((b: FormBuilder) => FormBuilder)[]): FormBuilder => {
+  if (condition) {
+    for (const op of ops) {
+      op(builder);
+    }
+  }
+  return builder;
+};
+
+/**
+ * Conditionally executes operations.
+ */
+export function when(builder: FormBuilder, condition: any, ...ops: ((b: FormBuilder) => FormBuilder)[]): FormBuilder;
+export function when(
+  condition: any,
+  ...ops: ((b: FormBuilder) => FormBuilder)[]
+): (builder: FormBuilder) => FormBuilder;
+export function when(
+  builderOrCondition: FormBuilder | any,
+  conditionOrOp?: any | ((b: FormBuilder) => FormBuilder),
+  ...ops: ((b: FormBuilder) => FormBuilder)[]
+): FormBuilder | ((builder: FormBuilder) => FormBuilder) {
+  if (builderOrCondition instanceof FormBuilderImpl) {
+    // Direct: when(builder, condition, ...ops)
+    const builder = builderOrCondition;
+    const condition = conditionOrOp;
+    return whenImpl(builder, condition, ...ops);
+  } else {
+    // Curried: when(condition, ...ops)
+    const condition = builderOrCondition;
+    const allOps = [conditionOrOp, ...ops].filter(
+      (op): op is (b: FormBuilder) => FormBuilder => typeof op === 'function',
+    );
+    return (builder: FormBuilder) => whenImpl(builder, condition, ...allOps);
+  }
+}
+
+// Implementation helper
+const eachImpl = <T>(
+  builder: FormBuilder,
+  items: T[],
+  fn: (item: T) => (b: FormBuilder) => FormBuilder,
+): FormBuilder => {
+  items.forEach((item) => fn(item)(builder));
+  return builder;
+};
+
+/**
+ * Iterates over an array of items.
+ */
+export function each<T>(
+  builder: FormBuilder,
+  items: T[],
+  fn: (item: T) => (b: FormBuilder) => FormBuilder,
+): FormBuilder;
+export function each<T>(
+  items: T[],
+  fn: (item: T) => (b: FormBuilder) => FormBuilder,
+): (builder: FormBuilder) => FormBuilder;
+export function each<T>(
+  builderOrItems: FormBuilder | T[],
+  itemsOrFn?: T[] | ((item: T) => (b: FormBuilder) => FormBuilder),
+  fn?: (item: T) => (b: FormBuilder) => FormBuilder,
+): FormBuilder | ((builder: FormBuilder) => FormBuilder) {
+  if (builderOrItems instanceof FormBuilderImpl) {
+    // Direct: each(builder, items, fn)
+    const builder = builderOrItems;
+    const items = itemsOrFn as T[];
+    return eachImpl(builder, items, fn!);
+  } else {
+    // Curried: each(items, fn)
+    const items = builderOrItems as T[];
+    const fn = itemsOrFn as (item: T) => (b: FormBuilder) => FormBuilder;
+    return (builder: FormBuilder) => eachImpl(builder, items, fn);
+  }
+}
+
+/**
+ * Builds the final document.
+ */
+export const build = (builder: FormBuilder): Doc.Doc<any> => {
+  const { targetWidth } = calculateDimensions(builder.entries, builder.prefix);
+  const entryLines: Doc.Doc<any>[] = [];
+
+  builder.entries.forEach(({ key, value, isNested }) => {
+    const keyLine = buildKeyLine(builder.prefix, key, targetWidth);
+    if (isNested) {
+      // Nested content should start on a new line.
+      // value is already indented by nestImpl, so we just cat with hardLine.
+      entryLines.push(Doc.hcat([keyLine, Doc.hardLine, value]));
+    } else {
+      // Single-line value, combine key and value.
+      // If the value itself is multiline (e.g. from Doc.string with newlines, though Doc handles that specifically),
+      // we might want layout flexibility.
+      // For now, standard behavior:
+      entryLines.push(Doc.hcat([keyLine, value]));
+    }
+  });
+
+  const entriesDoc = Doc.vsep(entryLines);
+
+  if (builder.title) {
+    const titleDoc = Doc.hcat([Doc.annotate(Doc.text(builder.title), Ansi.combine(Ansi.bold, Ansi.cyan))]);
+    // Join title and entries with a single line break, no extra spacing
+    return Doc.cat(titleDoc, Doc.cat(Doc.line, entriesDoc));
+  }
+
+  return entriesDoc;
+};

package/src/util/index.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * as FormBuilder from './form-builder';
+export * from './options';
+export * from './platform';
+export * from './printer';
+export * from './runtime';
+export * from './space';
+export * from './space-format';
+export * from './timeout';

package/src/util/options.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Options from '@effect/cli/Options';
+
+import { Key } from '@dxos/echo';
+
+//
+// Common options.
+// NOTE: Sub-commands should Function.pipe(Options.optional) if required.
+//
+
+export const Common = {
+  functionId: Options.text('function-id').pipe(Options.withDescription('EDGE Function ID.')),
+  spaceId: Options.text('space-id').pipe(Options.withSchema(Key.SpaceId), Options.withDescription('Space ID.')),
+};

package/src/util/platform.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { spawn } from 'node:child_process';
+
+import * as Effect from 'effect/Effect';
+
+/**
+ * Copy text to the system clipboard.
+ * Supports macOS (pbcopy), Windows (clip), and Linux (xclip/xsel).
+ */
+export const copyToClipboard = (text: string): Effect.Effect<void, Error> =>
+  Effect.tryPromise({
+    try: () => {
+      return new Promise<void>((resolve, reject) => {
+        const platform = process.platform;
+        let command: string;
+        let args: string[];
+
+        if (platform === 'darwin') {
+          command = 'pbcopy';
+          args = [];
+        } else if (platform === 'win32') {
+          command = 'clip';
+          args = [];
+        } else {
+          // Linux - try xclip or xsel
+          command = 'xclip';
+          args = ['-selection', 'clipboard'];
+        }
+
+        const proc = spawn(command, args);
+        proc.stdin?.write(text);
+        proc.stdin?.end();
+
+        proc.on('close', (code) => {
+          if (code === 0) {
+            resolve();
+          } else {
+            // Try xsel as fallback on Linux
+            if (platform === 'linux') {
+              const proc2 = spawn('xsel', ['--clipboard', '--input']);
+              proc2.stdin?.write(text);
+              proc2.stdin?.end();
+              proc2.on('close', (code2) => {
+                if (code2 === 0) {
+                  resolve();
+                } else {
+                  reject(new Error('Failed to copy to clipboard'));
+                }
+              });
+              proc2.on('error', reject);
+            } else {
+              reject(new Error('Failed to copy to clipboard'));
+            }
+          }
+        });
+
+        proc.on('error', reject);
+      });
+    },
+    catch: (error) => new Error(`Failed to copy to clipboard: ${error}`),
+  });
+
+/**
+ * Open a URL in the system's default browser.
+ * Supports macOS (open), Windows (start), and Linux (xdg-open).
+ */
+export const openBrowser = (url: string): Effect.Effect<void, Error> =>
+  Effect.tryPromise({
+    try: () => {
+      return new Promise<void>((resolve, reject) => {
+        const platform = process.platform;
+        let command: string;
+        let args: string[];
+
+        if (platform === 'darwin') {
+          command = 'open';
+          args = [url];
+        } else if (platform === 'win32') {
+          command = 'start';
+          args = [url];
+        } else {
+          command = 'xdg-open';
+          args = [url];
+        }
+
+        const proc = spawn(command, args);
+        proc.on('close', (code) => {
+          if (code === 0) {
+            resolve();
+          } else {
+            reject(new Error('Failed to open browser'));
+          }
+        });
+        proc.on('error', reject);
+      });
+    },
+    catch: (error) => new Error(`Failed to open browser: ${error}`),
+  });

package/src/util/printer.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Doc from '@effect/printer/Doc';
+import * as AnsiDoc from '@effect/printer-ansi/AnsiDoc';
+
+/**
+ * Pretty print document.
+ */
+export const print = (doc: Doc.Doc<any>) => AnsiDoc.render(doc, { style: 'pretty' });
+
+/**
+ * Pretty prints a list of documents with ANSI colors.
+ */
+export const printList = (items: Array<Doc.Doc<any>>) =>
+  AnsiDoc.render(Doc.vsep(items.map((item) => Doc.cat(item, Doc.hardLine))), { style: 'pretty' });

package/src/util/runtime.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import type * as Schema from 'effect/Schema';
+
+import { ClientService } from '@dxos/client';
+
+/** @deprecated Migrate to providing types via plugin capabilities. */
+export const withTypes: (...types: Schema.Schema.AnyNoContext[]) => Effect.Effect<void, never, ClientService> = (
+  ...types
+) =>
+  Effect.gen(function* () {
+    const client = yield* ClientService;
+    yield* Effect.promise(() => client.addTypes(types));
+  });

package/src/util/space-format.ts

@@ -0,0 +1,105 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { type Space, SpaceState, type SpaceSyncState } from '@dxos/client/echo';
+
+import * as FormBuilder from './form-builder';
+
+// TODO(wittjosiah): Use @effect/printer.
+export const formatSpace = Effect.fn(function* (space: Space, options = { verbose: false, truncateKeys: false }) {
+  yield* Effect.tryPromise(() => space.waitUntilReady());
+
+  // 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();
+
+  // 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 epoch = pipeline?.currentEpoch?.subject.assertion.number;
+
+  const syncState = aggregateSyncState(yield* Effect.tryPromise(() => space.internal.db.coreDatabase.getSyncState()));
+
+  return {
+    id: space.id,
+    state: SpaceState[space.state.get()],
+    name: space.state.get() === SpaceState.SPACE_READY ? space.properties.name : 'loading...',
+
+    members: space.members.get().length,
+    objects: space.internal.db.coreDatabase.getAllObjectIds().length,
+
+    key: options.truncateKeys ? space.key.truncate() : space.key.toHex(),
+    epoch,
+    startup,
+    automergeRoot: space.internal.data.pipeline?.spaceRootUrl,
+    // appliedEpoch,
+    syncState: `${syncState.count} ${getSyncIndicator(syncState.up, syncState.down)} (${syncState.peers} peers)`,
+  };
+});
+
+const aggregateSyncState = (syncState: SpaceSyncState) => {
+  const peers = Object.keys(syncState.peers ?? {}).length;
+  const missingOnLocal = Math.max(...Object.values(syncState.peers ?? {}).map((peer) => peer.missingOnLocal), 0);
+  const missingOnRemote = Math.max(...Object.values(syncState.peers ?? {}).map((peer) => peer.missingOnRemote), 0);
+  const differentDocuments = Math.max(
+    ...Object.values(syncState.peers ?? {}).map((peer) => peer.differentDocuments),
+    0,
+  );
+
+  return {
+    count: missingOnLocal + missingOnRemote + differentDocuments,
+    peers,
+    up: missingOnRemote > 0 || differentDocuments > 0,
+    down: missingOnLocal > 0 || differentDocuments > 0,
+  };
+};
+
+const getSyncIndicator = (up: boolean, down: boolean) => {
+  if (up) {
+    if (down) {
+      return '⇅';
+    } else {
+      return '↑';
+    }
+  } else {
+    if (down) {
+      return '↓';
+    } else {
+      return '✓';
+    }
+  }
+};
+
+export type FormattedSpace = {
+  id: string;
+  state: string;
+  name: string | undefined;
+  members: number;
+  objects: number;
+  key: string;
+  epoch: any;
+  startup: number | undefined;
+  automergeRoot: string | undefined;
+  syncState: string;
+};
+
+/**
+ * Pretty prints a space with ANSI colors.
+ */
+export const printSpace = (spaceData: FormattedSpace) =>
+  FormBuilder.make({ title: spaceData.name ?? spaceData.id }).pipe(
+    FormBuilder.set('id', spaceData.id),
+    FormBuilder.set('state', spaceData.state),
+    FormBuilder.set('key', spaceData.key),
+    FormBuilder.set('members', spaceData.members),
+    FormBuilder.set('objects', spaceData.objects),
+    FormBuilder.set('epoch', spaceData.epoch ?? '<none>'),
+    FormBuilder.set('startup', spaceData.startup ? `${spaceData.startup}ms` : '<none>'),
+    FormBuilder.set('syncState', spaceData.syncState),
+    FormBuilder.set('automergeRoot', spaceData.automergeRoot ?? '<none>'),
+    FormBuilder.build,
+  );

package/src/util/space.ts

@@ -0,0 +1,143 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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 { ClientService } from '@dxos/client';
+import { type Space } from '@dxos/client/echo';
+import { Database, type Key } from '@dxos/echo';
+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';
+
+export const getSpace = (spaceId: Key.SpaceId): Effect.Effect<Space, SpaceNotFoundError, ClientService> =>
+  Effect.gen(function* () {
+    const client = yield* ClientService;
+    return yield* Option.fromNullable(client.spaces.get(spaceId));
+  }).pipe(Effect.catchTag('NoSuchElementException', () => Effect.fail(new SpaceNotFoundError(spaceId))));
+
+export const spaceIdWithDefault = (spaceId: Option.Option<Key.SpaceId>) =>
+  Effect.gen(function* () {
+    const client = yield* ClientService;
+    yield* Effect.promise(() => client.spaces.waitUntilReady());
+    return Option.getOrElse(spaceId, () => client.spaces.default.id);
+  });
+
+// TODO(wittjosiah): Factor out.
+export const spaceLayer = (
+  spaceId$: Option.Option<Key.SpaceId>,
+  fallbackToDefaultSpace = false,
+): Layer.Layer<Database.Service | QueueService, never, ClientService> => {
+  const getSpace = Effect.fn(function* () {
+    const client = yield* ClientService;
+    yield* Effect.promise(() => client.spaces.waitUntilReady());
+
+    const spaceId = Match.value(fallbackToDefaultSpace).pipe(
+      Match.when(true, () =>
+        spaceId$.pipe(
+          Option.getOrElse(() => client.spaces.default.id),
+          Option.some,
+        ),
+      ),
+      Match.when(false, () => spaceId$),
+      Match.exhaustive,
+    );
+
+    const space = spaceId.pipe(
+      Option.flatMap((id) => Option.fromNullable(client.spaces.get(id))),
+      Option.getOrUndefined,
+    );
+
+    if (space) {
+      yield* Effect.promise(() => space.waitUntilReady());
+    }
+    return space;
+  });
+
+  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 { db: space.db };
+      }),
+      ({ db }) => Effect.promise(() => db.flush({ indexes: true })),
+    ),
+  );
+
+  const queue = Layer.effect(
+    QueueService,
+    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 {
+        queues: space.queues,
+        queue: undefined,
+      };
+    }),
+  );
+
+  return Layer.merge(db, queue);
+};
+
+// TODO(dmaretskyi): There a race condition with edge connection not showing up.
+export const waitForSync = Effect.fn(function* (space: Space) {
+  // TODO(wittjosiah): Find a better way to do this.
+  if (!isBun()) {
+    // Skipping sync to edge when not in bun env as this indicates running a test.
+    return;
+  }
+
+  // TODO(wittjosiah): This should probably be prompted for.
+  if (space.internal.data.edgeReplication !== EdgeReplicationSetting.ENABLED) {
+    yield* Console.log('Edge replication is disabled, enabling...');
+    yield* Effect.promise(() => space.internal.setEdgeReplicationPreference(EdgeReplicationSetting.ENABLED));
+  }
+
+  yield* Effect.promise(() =>
+    space.internal.syncToEdge({
+      onProgress: (state) => log.info('syncing', { state: state ?? 'no connection to edge' }),
+    }),
+  );
+  yield* Console.log('Sync complete');
+});
+
+export const flushAndSync = Effect.fn(function* (opts?: Database.FlushOptions) {
+  yield* Database.Service.flush(opts);
+  const spaceId = yield* Database.Service.spaceId;
+  const space = yield* getSpace(spaceId);
+  yield* waitForSync(space);
+});
+
+// TODO(burdon): Reconcile with @dxos/protocols
+export class SpaceNotFoundError extends BaseError.extend('SpaceNotFoundError', 'Space not found') {
+  constructor(spaceId: string, options?: Omit<BaseErrorOptions, 'context'>) {
+    super({ context: { spaceId }, ...options });
+  }
+}

package/src/util/timeout.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Cause from 'effect/Cause';
+import * as Config from 'effect/Config';
+import type * as ConfigError from 'effect/ConfigError';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+export const withTimeout: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, Cause.TimeoutException | ConfigError.ConfigError | E, R> = Effect.fnUntraced(function* (effect) {
+  const timeout = yield* Config.integer('TIMEOUT').pipe(Config.option);
+  const duration = timeout.pipe(
+    Option.map(Duration.millis),
+    Option.getOrElse(() => Duration.infinity),
+  );
+  return yield* effect.pipe(Effect.timeout(duration));
+});