ctxpkg 0.0.1

package/src/cli/cli.utils.ts

@@ -0,0 +1,122 @@
+import chalk from 'chalk';
+
+/**
+ * Format a header with decorative borders
+ */
+const formatHeader = (text: string) => {
+  console.log();
+  console.log(chalk.bold.cyan(`━━━ ${text} ━━━`));
+  console.log();
+};
+
+/**
+ * Format a success message with checkmark
+ */
+const formatSuccess = (text: string) => {
+  console.log(chalk.green('✔'), text);
+};
+
+/**
+ * Format an error message with X mark
+ */
+const formatError = (text: string) => {
+  console.log(chalk.red('✖'), text);
+};
+
+/**
+ * Format an info message with info icon
+ */
+const formatInfo = (text: string) => {
+  console.log(chalk.blue('ℹ'), text);
+};
+
+/**
+ * Format a warning message
+ */
+const formatWarning = (text: string) => {
+  console.log(chalk.yellow('⚠'), text);
+};
+
+/**
+ * Format a key-value pair
+ */
+const formatKeyValue = (key: string, value: unknown, keyWidth?: number) => {
+  const keyStr = keyWidth ? key.padEnd(keyWidth) : key;
+  console.log(chalk.dim('  ') + chalk.white(keyStr) + chalk.dim(' │ ') + chalk.cyan(String(value)));
+};
+
+/**
+ * Format a table header
+ */
+const formatTableHeader = (columns: { name: string; width: number }[]) => {
+  const header = columns.map((col) => chalk.bold(col.name.padEnd(col.width))).join(chalk.dim(' │ '));
+  const separator = columns.map((col) => '─'.repeat(col.width)).join(chalk.dim('─┼─'));
+
+  console.log(chalk.dim('  ') + header);
+  console.log(chalk.dim('  ') + separator);
+};
+
+/**
+ * Format a table row
+ */
+const formatTableRow = (values: { value: string; width: number; color?: typeof chalk }[]) => {
+  const row = values
+    .map((val) => {
+      const color = val.color || chalk.white;
+      return color(val.value.padEnd(val.width));
+    })
+    .join(chalk.dim(' │ '));
+
+  console.log(chalk.dim('  ') + row);
+};
+
+/**
+ * Wrap an async action with error handling
+ */
+const withErrorHandling = <T extends unknown[]>(
+  action: (...args: T) => Promise<void>,
+): ((...args: T) => Promise<void>) => {
+  return async (...args: T) => {
+    try {
+      await action(...args);
+    } catch (error) {
+      formatError(error instanceof Error ? error.message : String(error));
+      process.exitCode = 1;
+    }
+  };
+};
+
+/**
+ * Flatten an object into dot-notation keys
+ */
+const flattenObject = (obj: Record<string, unknown>, prefix = ''): Record<string, unknown> => {
+  const result: Record<string, unknown> = {};
+
+  for (const key of Object.keys(obj)) {
+    const value = obj[key];
+    const newKey = prefix ? `${prefix}.${key}` : key;
+
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      Object.assign(result, flattenObject(value as Record<string, unknown>, newKey));
+    } else {
+      result[newKey] = value;
+    }
+  }
+
+  return result;
+};
+
+export {
+  formatHeader,
+  formatSuccess,
+  formatError,
+  formatInfo,
+  formatWarning,
+  formatKeyValue,
+  formatTableHeader,
+  formatTableRow,
+  withErrorHandling,
+  flattenObject,
+};
+
+export { chalk };

package/src/client/AGENTS.md

@@ -0,0 +1,135 @@
+# Client — Agent Guidelines
+
+This document describes the client module architecture for AI agents working on this codebase.
+
+## Overview
+
+The client module provides a type-safe interface for communicating with the backend service. It supports multiple connection modes through an adapter pattern, allowing the same API to work in-process, via Unix socket (daemon), or over WebSocket.
+
+## File Structure
+
+| File | Purpose |
+|------|---------|
+| `client.ts` | `BackendClient` class and `createClient()` factory |
+| `client.adapters.ts` | Connection adapters (Direct, Daemon, WebSocket) |
+| `client.types.ts` | Connection modes and client options types |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     BackendClient                           │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │              Service Proxies (via Proxy)             │   │
+│  │   .documents.search()   →  "documents.search"        │   │
+│  │   .collections.sync()   →  "collections.sync"        │   │
+│  │   .system.ping()        →  "system.ping"             │   │
+│  └──────────────────────┬───────────────────────────────┘   │
+│                         │                                   │
+│  ┌──────────────────────▼───────────────────────────────┐   │
+│  │                  ClientAdapter                       │   │
+│  │   connect() | disconnect() | request() | isConnected │   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+                          │
+          ┌───────────────┼───────────────┐
+          ▼               ▼               ▼
+   ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+   │   Direct    │ │   Daemon    │ │  WebSocket  │
+   │  (in-proc)  │ │ (Unix sock) │ │  (remote)   │
+   └─────────────┘ └─────────────┘ └─────────────┘
+```
+
+## Connection Modes
+
+| Mode | Adapter | Use Case |
+|------|---------|----------|
+| `direct` | `DirectAdapter` | In-process backend, no daemon needed |
+| `daemon` | `DaemonAdapter` | Connect to local daemon via Unix socket |
+| `websocket` | `WebSocketAdapter` | Connect to remote server |
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { createClient } from '#root/client/client.ts';
+
+// Direct mode (in-process)
+const client = await createClient({ mode: 'direct' });
+
+// Daemon mode (Unix socket)
+const client = await createClient({ 
+  mode: 'daemon',
+  socketPath: '/tmp/ctxpkg.sock',  // optional
+  autoStartDaemon: true,           // optional, default true
+});
+
+// WebSocket mode
+const client = await createClient({ 
+  mode: 'websocket',
+  url: 'ws://localhost:8080',
+});
+
+// Use type-safe API
+const results = await client.documents.search({ query: 'foo' });
+await client.disconnect();
+```
+
+### Service Proxies
+
+The client uses `Proxy` to convert method calls into RPC requests:
+
+```typescript
+client.documents.search({ query: 'foo' })
+// → adapter.request('documents.search', { query: 'foo' })
+```
+
+This provides full type safety — methods and parameters are typed from `BackendAPI`.
+
+## Adding a New Adapter
+
+1. Implement the `ClientAdapter` interface:
+
+```typescript
+class MyAdapter implements ClientAdapter {
+  async connect(): Promise<void> { /* ... */ }
+  async disconnect(): Promise<void> { /* ... */ }
+  isConnected(): boolean { /* ... */ }
+  async request(method: string, params?: unknown): Promise<unknown> { /* ... */ }
+}
+```
+
+2. Add a new connection mode in `client.types.ts`:
+
+```typescript
+export type ConnectionMode = 'direct' | 'daemon' | 'websocket' | 'mymode';
+```
+
+3. Handle it in `BackendClient` constructor in `client.ts`.
+
+## Key Patterns
+
+### Request/Response Handling
+
+Adapters must:
+- Generate unique request IDs (use `randomUUID()`)
+- Track pending requests for async response matching
+- Handle timeouts and connection errors
+- Parse responses and throw on errors
+
+### Error Handling
+
+Errors from the backend include a `code` property matching `ErrorCodes`:
+
+```typescript
+try {
+  await client.documents.search({ query: 'foo' });
+} catch (error) {
+  if (error.code === ErrorCodes.Timeout) { /* ... */ }
+}
+```
+
+### Daemon Auto-Start
+
+`DaemonAdapter` uses `DaemonManager` to auto-start the daemon if not running. This is controlled by the `autoStartDaemon` option.

package/src/client/client.adapters.ts

@@ -0,0 +1,279 @@
+import { randomUUID } from 'node:crypto';
+
+import { WebSocket } from 'ws';
+
+import type { Request, Response } from '#root/backend/backend.protocol.ts';
+import { ErrorCodes } from '#root/backend/backend.protocol.ts';
+import { Backend } from '#root/backend/backend.ts';
+import { DaemonManager } from '#root/daemon/daemon.manager.ts';
+import { destroy } from '#root/utils/utils.services.ts';
+
+type ClientAdapter = {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+  request(method: string, params?: unknown): Promise<unknown>;
+};
+
+// Direct adapter - instantiates backend in-process
+class DirectAdapter implements ClientAdapter {
+  #backend: Backend | null = null;
+
+  async connect(): Promise<void> {
+    this.#backend = new Backend();
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.#backend) {
+      await this.#backend[destroy]();
+      this.#backend = null;
+    }
+  }
+
+  isConnected(): boolean {
+    return this.#backend !== null;
+  }
+
+  async request(method: string, params?: unknown): Promise<unknown> {
+    if (!this.#backend) {
+      throw new Error('Not connected');
+    }
+
+    const request: Request = {
+      id: randomUUID(),
+      method,
+      params,
+    };
+
+    const response = await this.#backend.handleRequest(request);
+    return this.#handleResponse(response);
+  }
+
+  #handleResponse(response: Response): unknown {
+    if (response.error) {
+      const error = new Error(response.error.message);
+      (error as Error & { code: number }).code = response.error.code;
+      throw error;
+    }
+    return response.result;
+  }
+}
+
+// Daemon adapter - connects via Unix socket
+class DaemonAdapter implements ClientAdapter {
+  #manager: DaemonManager;
+  #socket: WebSocket | null = null;
+  #pendingRequests = new Map<string, { resolve: (value: unknown) => void; reject: (error: Error) => void }>();
+  #timeout: number;
+
+  constructor(options?: { socketPath?: string; autoStart?: boolean; timeout?: number }) {
+    this.#manager = new DaemonManager({
+      socketPath: options?.socketPath,
+      autoStart: options?.autoStart ?? true,
+    });
+    this.#timeout = options?.timeout ?? 30000;
+  }
+
+  async connect(): Promise<void> {
+    await this.#manager.ensureRunning();
+
+    const socketPath = this.#manager.getSocketPath();
+    // Connect to Unix socket - ws library uses this format: ws+unix:///path/to/socket
+    const socket = new WebSocket(`ws+unix://${socketPath}:/.`);
+    this.#socket = socket;
+
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('Connection timeout'));
+      }, 5000);
+
+      socket.on('open', () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+
+      socket.on('error', (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      });
+    });
+
+    socket.on('message', (data) => {
+      try {
+        const response: Response = JSON.parse(data.toString());
+        const pending = this.#pendingRequests.get(response.id);
+        if (pending) {
+          this.#pendingRequests.delete(response.id);
+          if (response.error) {
+            const error = new Error(response.error.message);
+            (error as Error & { code: number }).code = response.error.code;
+            pending.reject(error);
+          } else {
+            pending.resolve(response.result);
+          }
+        }
+      } catch (error) {
+        console.error('[client] Failed to parse response:', error);
+      }
+    });
+
+    socket.on('close', () => {
+      // Reject all pending requests
+      for (const [id, pending] of this.#pendingRequests) {
+        pending.reject(new Error('Connection closed'));
+        this.#pendingRequests.delete(id);
+      }
+      this.#socket = null;
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.#socket) {
+      this.#socket.close();
+      this.#socket = null;
+    }
+  }
+
+  isConnected(): boolean {
+    return this.#socket !== null && this.#socket.readyState === WebSocket.OPEN;
+  }
+
+  async request(method: string, params?: unknown): Promise<unknown> {
+    const socket = this.#socket;
+    if (!socket || socket.readyState !== WebSocket.OPEN) {
+      throw new Error('Not connected');
+    }
+
+    const id = randomUUID();
+    const request: Request = { id, method, params };
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.#pendingRequests.delete(id);
+        const error = new Error('Request timeout');
+        (error as Error & { code: number }).code = ErrorCodes.Timeout;
+        reject(error);
+      }, this.#timeout);
+
+      this.#pendingRequests.set(id, {
+        resolve: (value) => {
+          clearTimeout(timeout);
+          resolve(value);
+        },
+        reject: (err) => {
+          clearTimeout(timeout);
+          reject(err);
+        },
+      });
+
+      socket.send(JSON.stringify(request));
+    });
+  }
+}
+
+// WebSocket adapter - connects via remote WebSocket
+class WebSocketAdapter implements ClientAdapter {
+  #url: string;
+  #socket: WebSocket | null = null;
+  #pendingRequests = new Map<string, { resolve: (value: unknown) => void; reject: (error: Error) => void }>();
+  #timeout: number;
+
+  constructor(url: string, options?: { timeout?: number }) {
+    this.#url = url;
+    this.#timeout = options?.timeout ?? 30000;
+  }
+
+  async connect(): Promise<void> {
+    const socket = new WebSocket(this.#url);
+    this.#socket = socket;
+
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('Connection timeout'));
+      }, 5000);
+
+      socket.on('open', () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+
+      socket.on('error', (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      });
+    });
+
+    socket.on('message', (data) => {
+      try {
+        const response: Response = JSON.parse(data.toString());
+        const pending = this.#pendingRequests.get(response.id);
+        if (pending) {
+          this.#pendingRequests.delete(response.id);
+          if (response.error) {
+            const error = new Error(response.error.message);
+            (error as Error & { code: number }).code = response.error.code;
+            pending.reject(error);
+          } else {
+            pending.resolve(response.result);
+          }
+        }
+      } catch (error) {
+        console.error('[client] Failed to parse response:', error);
+      }
+    });
+
+    socket.on('close', () => {
+      for (const [id, pending] of this.#pendingRequests) {
+        pending.reject(new Error('Connection closed'));
+        this.#pendingRequests.delete(id);
+      }
+      this.#socket = null;
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.#socket) {
+      this.#socket.close();
+      this.#socket = null;
+    }
+  }
+
+  isConnected(): boolean {
+    return this.#socket !== null && this.#socket.readyState === WebSocket.OPEN;
+  }
+
+  async request(method: string, params?: unknown): Promise<unknown> {
+    const socket = this.#socket;
+    if (!socket || socket.readyState !== WebSocket.OPEN) {
+      throw new Error('Not connected');
+    }
+
+    const id = randomUUID();
+    const request: Request = { id, method, params };
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.#pendingRequests.delete(id);
+        const error = new Error('Request timeout');
+        (error as Error & { code: number }).code = ErrorCodes.Timeout;
+        reject(error);
+      }, this.#timeout);
+
+      this.#pendingRequests.set(id, {
+        resolve: (value) => {
+          clearTimeout(timeout);
+          resolve(value);
+        },
+        reject: (err) => {
+          clearTimeout(timeout);
+          reject(err);
+        },
+      });
+
+      socket.send(JSON.stringify(request));
+    });
+  }
+}
+
+export type { ClientAdapter };
+export { DirectAdapter, DaemonAdapter, WebSocketAdapter };

package/src/client/client.ts

@@ -0,0 +1,86 @@
+import type { ClientOptions, BackendAPI } from './client.types.ts';
+import { DirectAdapter, DaemonAdapter, WebSocketAdapter, type ClientAdapter } from './client.adapters.ts';
+
+// Create a proxy that converts method calls to RPC requests
+const createServiceProxy = <T extends keyof BackendAPI>(adapter: ClientAdapter, serviceName: T): BackendAPI[T] => {
+  const target = {} as Record<string, unknown>;
+  return new Proxy(target, {
+    get(_target, methodName: string) {
+      return async (params?: unknown) => {
+        const method = `${serviceName}.${methodName}`;
+        return adapter.request(method, params ?? {});
+      };
+    },
+  }) as BackendAPI[T];
+};
+
+class BackendClient implements BackendAPI {
+  #adapter: ClientAdapter;
+  #connected = false;
+
+  // Type-safe service proxies
+  readonly documents: BackendAPI['documents'];
+  readonly collections: BackendAPI['collections'];
+  readonly system: BackendAPI['system'];
+
+  constructor(options: ClientOptions) {
+    // Create appropriate adapter
+    switch (options.mode) {
+      case 'direct':
+        this.#adapter = new DirectAdapter();
+        break;
+      case 'daemon':
+        this.#adapter = new DaemonAdapter({
+          socketPath: options.socketPath,
+          autoStart: options.autoStartDaemon,
+          timeout: options.timeout,
+        });
+        break;
+      case 'websocket':
+        if (!options.url) {
+          throw new Error('WebSocket URL is required for websocket mode');
+        }
+        this.#adapter = new WebSocketAdapter(options.url, {
+          timeout: options.timeout,
+        });
+        break;
+      default:
+        throw new Error(`Unknown connection mode: ${options.mode}`);
+    }
+
+    // Create type-safe service proxies
+    this.documents = createServiceProxy(this.#adapter, 'documents');
+    this.collections = createServiceProxy(this.#adapter, 'collections');
+    this.system = createServiceProxy(this.#adapter, 'system');
+  }
+
+  async connect(): Promise<void> {
+    await this.#adapter.connect();
+    this.#connected = true;
+  }
+
+  async disconnect(): Promise<void> {
+    await this.#adapter.disconnect();
+    this.#connected = false;
+  }
+
+  isConnected(): boolean {
+    return this.#connected && this.#adapter.isConnected();
+  }
+
+  // Generic request method for advanced usage
+  async request<T>(method: string, params?: unknown): Promise<T> {
+    return this.#adapter.request(method, params) as Promise<T>;
+  }
+}
+
+// Factory function for creating a client with auto-detection
+const createClient = async (options?: Partial<ClientOptions>): Promise<BackendClient> => {
+  const mode = options?.mode ?? 'direct';
+  const client = new BackendClient({ mode, ...options } as ClientOptions);
+  await client.connect();
+  return client;
+};
+
+export { BackendClient, createClient };
+export type { ClientOptions, BackendAPI };

package/src/client/client.types.ts

@@ -0,0 +1,17 @@
+// Re-export backend API types for client use
+export type { BackendAPI, GetBackendAPIResponse, GetBackendAPIParams } from '#root/backend/backend.types.ts';
+
+// Connection modes
+export type ConnectionMode = 'direct' | 'daemon' | 'websocket';
+
+// Client options
+export type ClientOptions = {
+  mode: ConnectionMode;
+  // For 'websocket' mode
+  url?: string;
+  // For 'daemon' mode
+  socketPath?: string;
+  autoStartDaemon?: boolean;
+  // Common options
+  timeout?: number;
+};