ctxpkg 0.0.1

package/src/config/config.ts

@@ -0,0 +1,118 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+
+import convict from 'convict';
+import envPaths from 'env-paths';
+
+const paths = envPaths('ctxpkg', { suffix: '' });
+const configPath = join(paths.config, 'config.json');
+
+// Use ~/.ctxpkg for runtime files to avoid spaces in path (ws library URL encoding issue)
+const runtimeDir = join(homedir(), '.ctxpkg');
+
+const config = convict({
+  database: {
+    path: {
+      doc: 'Path to the SQLite database file',
+      format: String,
+      default: join(paths.data, 'database.sqlite'),
+      env: 'CTXPKG_DATABASE_PATH',
+    },
+  },
+  llm: {
+    provider: {
+      doc: 'OpenAI-compatible API base URL',
+      format: String,
+      default: 'https://api.openai.com/v1',
+      env: 'CTXPKG_LLM_PROVIDER',
+    },
+    model: {
+      doc: 'Model identifier to use for agent reasoning',
+      format: String,
+      default: 'gpt-4o-mini',
+      env: 'CTXPKG_LLM_MODEL',
+    },
+    apiKey: {
+      doc: 'API key for the LLM provider',
+      format: String,
+      default: '',
+      env: 'CTXPKG_LLM_API_KEY',
+      sensitive: true,
+    },
+    temperature: {
+      doc: 'Temperature for LLM responses (0-2)',
+      format: Number,
+      default: 0,
+      env: 'CTXPKG_LLM_TEMPERATURE',
+    },
+    maxTokens: {
+      doc: 'Maximum tokens for LLM responses',
+      format: 'nat',
+      default: 4096,
+      env: 'CTXPKG_LLM_MAX_TOKENS',
+    },
+  },
+  daemon: {
+    socketPath: {
+      doc: 'Path to the daemon Unix socket file',
+      format: String,
+      default: join(runtimeDir, 'daemon.sock'),
+      env: 'CTXPKG_SOCKET_PATH',
+    },
+    pidFile: {
+      doc: 'Path to the daemon PID file',
+      format: String,
+      default: join(runtimeDir, 'daemon.pid'),
+      env: 'CTXPKG_PID_FILE',
+    },
+    idleTimeout: {
+      doc: 'Idle timeout in milliseconds before daemon shuts down (0 to disable)',
+      format: 'nat',
+      default: 0,
+      env: 'CTXPKG_IDLE_TIMEOUT',
+    },
+    autoStart: {
+      doc: 'Automatically start daemon when CLI commands need it',
+      format: Boolean,
+      default: true,
+      env: 'CTXPKG_AUTO_START',
+    },
+  },
+  project: {
+    configFile: {
+      doc: 'Filename for project configuration file',
+      format: String,
+      default: 'context.json',
+      env: 'CTXPKG_PROJECT_CONFIG_FILE',
+    },
+  },
+  global: {
+    configFile: {
+      doc: 'Path to global collections config file',
+      format: String,
+      default: join(paths.config, 'global-context.json'),
+      env: 'CTXPKG_GLOBAL_CONFIG_FILE',
+    },
+  },
+});
+
+// Ensure config directory exists for future writes, but don't fail if we can't read yet
+if (existsSync(configPath)) {
+  try {
+    config.loadFile(configPath);
+  } catch (e) {
+    console.warn(`Failed to load config from ${configPath}:`, e);
+  }
+}
+
+config.validate({ allowed: 'strict' });
+
+export { config, configPath };
+
+export const saveConfig = () => {
+  if (!existsSync(paths.config)) {
+    mkdirSync(paths.config, { recursive: true });
+  }
+  writeFileSync(configPath, JSON.stringify(config.get(), null, 2));
+};

package/src/daemon/AGENTS.md

@@ -0,0 +1,168 @@
+# Daemon — Agent Guidelines
+
+This document describes the daemon module architecture for AI agents working on this codebase.
+
+## Overview
+
+The daemon module provides a background process that hosts the Backend service. It listens on a Unix socket, accepts WebSocket connections, and routes JSON-RPC requests to the Backend. The daemon supports idle timeout for automatic shutdown and can be auto-started on demand.
+
+## File Structure
+
+| File | Purpose |
+|------|---------|
+| `daemon.ts` | `Daemon` class — server lifecycle, connections, idle timeout |
+| `daemon.manager.ts` | `DaemonManager` — start/stop/status from external processes |
+| `daemon.config.ts` | Config accessors (socket path, PID file, timeouts) |
+| `daemon.schemas.ts` | Zod schemas for `DaemonStatus` and `DaemonOptions` |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         Daemon                              │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                   HTTP Server                       │    │
+│  │              (Unix socket listener)                 │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                   │
+│  ┌──────────────────────▼──────────────────────────────┐    │
+│  │                WebSocket Server                     │    │
+│  │         (handles client connections)                │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                   │
+│           ┌─────────────┼─────────────┐                     │
+│           ▼             ▼             ▼                     │
+│      [Client 1]    [Client 2]    [Client N]                 │
+│           │             │             │                     │
+│           └─────────────┼─────────────┘                     │
+│                         ▼                                   │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │                    Backend                           │   │
+│  │              (request handling)                      │   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│                    DaemonManager                            │
+│  (runs in CLI/client process, controls daemon externally)   │
+│                                                             │
+│  isRunning() → ping via socket                              │
+│  start()     → spawn detached process                       │
+│  stop()      → send system.shutdown                         │
+│  getStatus() → query system.status                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Daemon Lifecycle
+
+### Startup
+
+1. Create data directory if needed
+2. Remove stale socket file
+3. Write PID file
+4. Create HTTP server on Unix socket
+5. Attach WebSocket server
+6. Start idle timer (if no connections)
+7. Register signal handlers (SIGTERM, SIGINT)
+
+### Connections
+
+- Each WebSocket connection is tracked
+- Messages are parsed as JSON and routed to `Backend.handleRequest()`
+- Responses are sent back as JSON
+- Connection count is updated on connect/disconnect
+
+### Idle Timeout
+
+- Timer starts when connection count reaches 0
+- Default: 5 minutes (configurable via `daemon.idleTimeout`)
+- Set to 0 to disable auto-shutdown
+- Timer is cleared when a client connects
+
+### Shutdown
+
+1. Clear idle timer
+2. Close all WebSocket connections
+3. Close WebSocket server
+4. Close HTTP server
+5. Cleanup Backend resources
+6. Remove socket and PID files
+7. Exit process
+
+## DaemonManager
+
+Used by CLI and client to control the daemon:
+
+```typescript
+const manager = new DaemonManager();
+
+// Check if running
+if (await manager.isRunning()) {
+  console.log('Daemon is running');
+}
+
+// Start (spawns detached process)
+await manager.start();
+
+// Stop (sends shutdown command)
+await manager.stop();
+
+// Get status
+const status = await manager.getStatus();
+// { running, socketPath, pid, uptime, connections }
+```
+
+### Auto-Start
+
+`DaemonManager.ensureRunning()` will start the daemon if not running (when `autoStart` is enabled). This is used by `DaemonAdapter` in the client.
+
+## Configuration
+
+Accessed via `daemon.config.ts`:
+
+| Config Key | Default | Description |
+|------------|---------|-------------|
+| `daemon.socketPath` | `~/.ai-assist/daemon.sock` | Unix socket path |
+| `daemon.pidFile` | `~/.ai-assist/daemon.pid` | PID file path |
+| `daemon.idleTimeout` | `300000` (5 min) | Idle shutdown timeout (ms), 0 to disable |
+| `daemon.autoStart` | `true` | Auto-start daemon when client connects |
+
+## Entry Point
+
+The daemon is started via `bin/daemon.js`:
+
+```typescript
+import { Daemon } from '#root/daemon/daemon.ts';
+
+const daemon = new Daemon();
+await daemon.start();
+```
+
+This script is spawned as a detached process by `DaemonManager.start()`.
+
+## Key Patterns
+
+### Process Management
+
+- PID file tracks the daemon process
+- Detached spawn ensures daemon outlives parent
+- Socket file existence + ping confirms daemon is alive
+
+### Graceful Shutdown
+
+Always handle shutdown signals:
+
+```typescript
+process.on('SIGTERM', () => daemon.stop());
+process.on('SIGINT', () => daemon.stop());
+```
+
+### Client Connection Format
+
+Clients connect via WebSocket to the Unix socket:
+
+```typescript
+const socket = new WebSocket(`ws+unix://${socketPath}:/.`);
+```
+
+This is handled by the `ws` library's Unix socket support.

package/src/daemon/daemon.config.ts

@@ -0,0 +1,23 @@
+import { config } from '#root/config/config.ts';
+
+const getSocketPath = (): string => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (config as any).get('daemon.socketPath') as string;
+};
+
+const getPidFile = (): string => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (config as any).get('daemon.pidFile') as string;
+};
+
+const getIdleTimeout = (): number => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (config as any).get('daemon.idleTimeout') as number;
+};
+
+const getAutoStart = (): boolean => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (config as any).get('daemon.autoStart') as boolean;
+};
+
+export { getSocketPath, getPidFile, getIdleTimeout, getAutoStart };

package/src/daemon/daemon.manager.ts

@@ -0,0 +1,215 @@
+import { spawn } from 'node:child_process';
+import { access, readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { WebSocket } from 'ws';
+
+import { getSocketPath, getPidFile, getAutoStart } from './daemon.config.ts';
+import type { DaemonStatus } from './daemon.schemas.ts';
+
+type DaemonManagerOptions = {
+  socketPath?: string;
+  pidFile?: string;
+  autoStart?: boolean;
+  startTimeout?: number;
+};
+
+class DaemonManager {
+  #socketPath: string;
+  #pidFile: string;
+  #autoStart: boolean;
+  #startTimeout: number;
+
+  constructor(options?: DaemonManagerOptions) {
+    this.#socketPath = options?.socketPath ?? getSocketPath();
+    this.#pidFile = options?.pidFile ?? getPidFile();
+    this.#autoStart = options?.autoStart ?? getAutoStart();
+    this.#startTimeout = options?.startTimeout ?? 30000;
+  }
+
+  getSocketPath(): string {
+    return this.#socketPath;
+  }
+
+  async isRunning(): Promise<boolean> {
+    // Check if socket file exists
+    try {
+      await access(this.#socketPath);
+    } catch {
+      return false;
+    }
+
+    // Try to connect and ping
+    return new Promise((resolve) => {
+      const socket = new WebSocket(`ws+unix://${this.#socketPath}:/.`);
+      const timeout = setTimeout(() => {
+        socket.close();
+        resolve(false);
+      }, 2000);
+
+      socket.on('open', () => {
+        // Send ping request
+        socket.send(JSON.stringify({ id: 'ping', method: 'system.ping', params: {} }));
+      });
+
+      socket.on('message', (data) => {
+        clearTimeout(timeout);
+        try {
+          const response = JSON.parse(data.toString());
+          socket.close();
+          resolve(response.result?.pong === true);
+        } catch {
+          socket.close();
+          resolve(false);
+        }
+      });
+
+      socket.on('error', () => {
+        clearTimeout(timeout);
+        resolve(false);
+      });
+    });
+  }
+
+  async ensureRunning(): Promise<void> {
+    if (await this.isRunning()) {
+      return;
+    }
+
+    if (!this.#autoStart) {
+      throw new Error('Daemon is not running and autoStart is disabled');
+    }
+
+    await this.start();
+  }
+
+  async start(): Promise<void> {
+    if (await this.isRunning()) {
+      return;
+    }
+
+    // Find the daemon entry point
+    const currentFile = fileURLToPath(import.meta.url);
+    const projectRoot = dirname(dirname(dirname(currentFile)));
+    const daemonScript = join(projectRoot, 'bin', 'daemon.js');
+
+    // Spawn detached daemon process
+    const child = spawn(process.execPath, [daemonScript], {
+      detached: true,
+      stdio: 'ignore',
+      env: {
+        ...process.env,
+        AI_ASSIST_DAEMON: '1',
+      },
+    });
+
+    child.unref();
+
+    // Wait for socket to become available
+    await this.#waitForSocket();
+  }
+
+  async #waitForSocket(): Promise<void> {
+    const startTime = Date.now();
+    const pollInterval = 100;
+
+    while (Date.now() - startTime < this.#startTimeout) {
+      if (await this.isRunning()) {
+        return;
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+
+    throw new Error(`Daemon failed to start within ${this.#startTimeout}ms`);
+  }
+
+  async stop(): Promise<void> {
+    if (!(await this.isRunning())) {
+      return;
+    }
+
+    // Send shutdown command
+    return new Promise((resolve, reject) => {
+      const socket = new WebSocket(`ws+unix://${this.#socketPath}:/.`);
+      const timeout = setTimeout(() => {
+        socket.close();
+        reject(new Error('Shutdown request timed out'));
+      }, 5000);
+
+      socket.on('open', () => {
+        socket.send(JSON.stringify({ id: 'shutdown', method: 'system.shutdown', params: {} }));
+      });
+
+      socket.on('message', () => {
+        clearTimeout(timeout);
+        socket.close();
+        resolve();
+      });
+
+      socket.on('error', (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      });
+
+      socket.on('close', () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+    });
+  }
+
+  async getStatus(): Promise<DaemonStatus | null> {
+    if (!(await this.isRunning())) {
+      return null;
+    }
+
+    return new Promise((resolve) => {
+      const socket = new WebSocket(`ws+unix://${this.#socketPath}:/.`);
+      const timeout = setTimeout(() => {
+        socket.close();
+        resolve(null);
+      }, 2000);
+
+      socket.on('open', () => {
+        socket.send(JSON.stringify({ id: 'status', method: 'system.status', params: {} }));
+      });
+
+      socket.on('message', async (data) => {
+        clearTimeout(timeout);
+        try {
+          const response = JSON.parse(data.toString());
+          socket.close();
+
+          // Read PID from file
+          let pid = 0;
+          try {
+            const pidContent = await readFile(this.#pidFile, 'utf8');
+            pid = parseInt(pidContent, 10);
+          } catch {
+            // Ignore
+          }
+
+          resolve({
+            running: true,
+            socketPath: this.#socketPath,
+            pid,
+            uptime: response.result?.uptime ?? 0,
+            connections: response.result?.connections ?? 0,
+          });
+        } catch {
+          socket.close();
+          resolve(null);
+        }
+      });
+
+      socket.on('error', () => {
+        clearTimeout(timeout);
+        resolve(null);
+      });
+    });
+  }
+}
+
+export { DaemonManager };
+export type { DaemonManagerOptions };

package/src/daemon/daemon.schemas.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+const daemonStatusSchema = z.object({
+  running: z.boolean(),
+  socketPath: z.string(),
+  pid: z.number(),
+  uptime: z.number(),
+  connections: z.number(),
+});
+
+type DaemonStatus = z.infer<typeof daemonStatusSchema>;
+
+const daemonOptionsSchema = z.object({
+  socketPath: z.string().optional(),
+  idleTimeout: z.number().default(300000), // 5 minutes
+  pidFile: z.string().optional(),
+});
+
+type DaemonOptions = z.infer<typeof daemonOptionsSchema>;
+
+export type { DaemonStatus, DaemonOptions };
+export { daemonStatusSchema, daemonOptionsSchema };