ctxpkg 0.0.1

package/src/daemon/daemon.ts

@@ -0,0 +1,205 @@
+import { createServer, type Server } from 'node:http';
+import { mkdir, rm, writeFile, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { WebSocketServer, WebSocket } from 'ws';
+
+import { getSocketPath, getPidFile, getIdleTimeout } from './daemon.config.ts';
+import type { DaemonOptions, DaemonStatus } from './daemon.schemas.ts';
+
+import { Backend } from '#root/backend/backend.ts';
+import { destroy } from '#root/utils/utils.services.ts';
+
+class Daemon {
+  #backend: Backend;
+  #httpServer: Server | null = null;
+  #wsServer: WebSocketServer | null = null;
+  #connections = new Set<WebSocket>();
+  #idleTimer: ReturnType<typeof setTimeout> | null = null;
+  #startTime = 0;
+  #socketPath: string;
+  #pidFile: string;
+  #idleTimeout: number;
+  #isShuttingDown = false;
+
+  constructor(options?: DaemonOptions) {
+    this.#socketPath = options?.socketPath ?? getSocketPath();
+    this.#pidFile = options?.pidFile ?? getPidFile();
+    this.#idleTimeout = options?.idleTimeout ?? getIdleTimeout();
+    this.#backend = new Backend();
+  }
+
+  async start(): Promise<void> {
+    // Ensure data directory exists
+    await mkdir(dirname(this.#socketPath), { recursive: true });
+
+    // Remove existing socket file if present
+    try {
+      await rm(this.#socketPath, { force: true });
+    } catch {
+      // Ignore errors
+    }
+
+    // Write PID file
+    await writeFile(this.#pidFile, String(process.pid));
+
+    // Create HTTP server listening on Unix socket
+    this.#httpServer = createServer();
+
+    // Create WebSocket server attached to HTTP server
+    this.#wsServer = new WebSocketServer({ server: this.#httpServer });
+    this.#startTime = Date.now();
+
+    this.#wsServer.on('connection', (socket) => {
+      this.#handleConnection(socket);
+    });
+
+    this.#wsServer.on('error', (error) => {
+      console.error('[daemon] WebSocket server error:', error);
+    });
+
+    this.#httpServer.on('error', (error) => {
+      console.error('[daemon] HTTP server error:', error);
+    });
+
+    // Start listening on Unix socket
+    await new Promise<void>((resolve, reject) => {
+      this.#httpServer?.listen(this.#socketPath, () => {
+        resolve();
+      });
+      this.#httpServer?.on('error', reject);
+    });
+
+    // Start idle timer if no connections
+    this.#resetIdleTimer();
+
+    // Handle shutdown signals
+    process.on('SIGTERM', () => this.stop());
+    process.on('SIGINT', () => this.stop());
+
+    console.log(`[daemon] Started on ${this.#socketPath} (PID: ${process.pid})`);
+  }
+
+  #handleConnection(socket: WebSocket): void {
+    this.#connections.add(socket);
+    this.#backend.setConnectionCount(this.#connections.size);
+    this.#clearIdleTimer();
+
+    console.log(`[daemon] Client connected (${this.#connections.size} total)`);
+
+    socket.on('message', async (data) => {
+      try {
+        const request = JSON.parse(data.toString());
+        const response = await this.#backend.handleRequest(request);
+        socket.send(JSON.stringify(response));
+      } catch (error) {
+        const errorResponse = {
+          id: 'unknown',
+          error: {
+            code: -32700,
+            message: error instanceof Error ? error.message : 'Parse error',
+          },
+        };
+        socket.send(JSON.stringify(errorResponse));
+      }
+    });
+
+    socket.on('close', () => {
+      this.#connections.delete(socket);
+      this.#backend.setConnectionCount(this.#connections.size);
+      console.log(`[daemon] Client disconnected (${this.#connections.size} remaining)`);
+
+      if (this.#connections.size === 0) {
+        this.#resetIdleTimer();
+      }
+    });
+
+    socket.on('error', (error) => {
+      console.error('[daemon] Socket error:', error);
+      this.#connections.delete(socket);
+      this.#backend.setConnectionCount(this.#connections.size);
+    });
+  }
+
+  #resetIdleTimer(): void {
+    this.#clearIdleTimer();
+
+    if (this.#idleTimeout > 0 && this.#connections.size === 0) {
+      console.log(`[daemon] Starting idle timer (${this.#idleTimeout / 1000}s)`);
+      this.#idleTimer = setTimeout(() => {
+        console.log('[daemon] Idle timeout reached, shutting down');
+        this.stop();
+      }, this.#idleTimeout);
+    }
+  }
+
+  #clearIdleTimer(): void {
+    if (this.#idleTimer) {
+      clearTimeout(this.#idleTimer);
+      this.#idleTimer = null;
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (this.#isShuttingDown) return;
+    this.#isShuttingDown = true;
+
+    console.log('[daemon] Shutting down...');
+
+    this.#clearIdleTimer();
+
+    // Close all WebSocket connections
+    for (const socket of this.#connections) {
+      socket.close(1000, 'Server shutting down');
+    }
+    this.#connections.clear();
+
+    // Close WebSocket server
+    const wsServer = this.#wsServer;
+    if (wsServer) {
+      await new Promise<void>((resolve) => {
+        wsServer.close(() => resolve());
+      });
+      this.#wsServer = null;
+    }
+
+    // Close HTTP server
+    const httpServer = this.#httpServer;
+    if (httpServer) {
+      await new Promise<void>((resolve) => {
+        httpServer.close(() => resolve());
+      });
+      this.#httpServer = null;
+    }
+
+    // Cleanup backend
+    await this.#backend[destroy]();
+
+    // Remove socket and PID files
+    try {
+      await unlink(this.#socketPath);
+    } catch {
+      // Ignore
+    }
+    try {
+      await unlink(this.#pidFile);
+    } catch {
+      // Ignore
+    }
+
+    console.log('[daemon] Stopped');
+    process.exit(0);
+  }
+
+  getStatus(): DaemonStatus {
+    return {
+      running: this.#httpServer !== null,
+      socketPath: this.#socketPath,
+      pid: process.pid,
+      uptime: Date.now() - this.#startTime,
+      connections: this.#connections.size,
+    };
+  }
+}
+
+export { Daemon };

package/src/database/AGENTS.md

@@ -0,0 +1,211 @@
+# Database — Agent Guidelines
+
+This document describes the database module architecture for AI agents working on this codebase.
+
+## Overview
+
+The database module provides SQLite storage with vector search capabilities using [sqlite-vec](https://github.com/asg017/sqlite-vec). It uses [Knex](https://knexjs.org/) for query building and migrations. The database stores collection metadata, reference documents, and vector embeddings for semantic search.
+
+## File Structure
+
+```
+src/database/
+├── database.ts              # DatabaseService class
+└── migrations/
+    ├── migrations.ts        # Migration source (collects all migrations)
+    ├── migrations.types.ts  # Migration type definition
+    └── migrations.001-init.ts  # Initial schema
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    DatabaseService                          │
+│                                                             │
+│  getInstance() → lazy init, singleton pattern               │
+│       │                                                     │
+│       ▼                                                     │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                    Knex                             │    │
+│  │              (query builder)                        │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                   │
+│  ┌──────────────────────▼──────────────────────────────┐    │
+│  │              better-sqlite3                         │    │
+│  │         (SQLite driver for Node.js)                 │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                   │
+│  ┌──────────────────────▼──────────────────────────────┐    │
+│  │                sqlite-vec                           │    │
+│  │      (vector extension, loaded via afterCreate)     │    │
+│  └─────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Schema
+
+### `collections`
+
+Tracks synced collection packages:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | string (PK) | Collection ID (`pkg:{url}`) |
+| `url` | text | Manifest URL |
+| `name` | string? | Package name from manifest |
+| `version` | string? | Package version from manifest |
+| `description` | text? | Package description from manifest |
+| `manifest_hash` | string? | SHA-256 of manifest |
+| `last_sync_at` | string? | ISO timestamp of last sync |
+| `created_at` | string | ISO timestamp |
+| `updated_at` | string | ISO timestamp |
+
+### `reference_documents`
+
+Stores full document content:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `collection` | string (PK) | Collection ID |
+| `id` | string (PK) | Document ID (e.g., file path) |
+| `hash` | string | SHA-256 of content (change detection) |
+| `content` | text | Full document content |
+
+### `reference_document_chunks`
+
+Stores document chunks with embeddings:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | string (PK) | UUID |
+| `collection` | string | Collection ID |
+| `document` | string | Parent document ID |
+| `content` | text | Chunk text (~500 chars) |
+| `embedding` | vector(1024) | Vector embedding |
+
+## Usage
+
+### Getting Database Instance
+
+```typescript
+import { DatabaseService, tableNames } from '#root/database/database.ts';
+
+const databaseService = services.get(DatabaseService);
+const db = await databaseService.getInstance();
+
+// Query using Knex
+const docs = await db(tableNames.referenceDocuments)
+  .where({ collection: 'my-collection' })
+  .select('*');
+```
+
+### Vector Search
+
+sqlite-vec provides `vec_distance_L2()` for Euclidean distance:
+
+```typescript
+const results = await db(tableNames.referenceDocumentChunks)
+  .select('*', db.raw('vec_distance_L2(?, embedding) as distance', [JSON.stringify(queryVector)]))
+  .orderBy('distance', 'asc')
+  .limit(10);
+```
+
+### Table Names
+
+Always use `tableNames` constant for consistency:
+
+```typescript
+import { tableNames } from '#root/database/database.ts';
+
+tableNames.collections           // 'collections'
+tableNames.referenceDocuments    // 'reference_documents'
+tableNames.referenceDocumentChunks  // 'reference_documentchunks'
+```
+
+## Adding Migrations
+
+### 1. Create Migration File
+
+```typescript
+// migrations/migrations.002-add-feature.ts
+import type { Migration } from './migrations.types.ts';
+
+const addFeature: Migration = {
+  name: 'add-feature',
+  up: async (knex) => {
+    await knex.schema.alterTable('some_table', (table) => {
+      table.string('new_column').nullable();
+    });
+  },
+  down: async (knex) => {
+    await knex.schema.alterTable('some_table', (table) => {
+      table.dropColumn('new_column');
+    });
+  },
+};
+
+export { addFeature };
+```
+
+### 2. Register Migration
+
+In `migrations/migrations.ts`:
+
+```typescript
+import { init } from './migrations.001-init.ts';
+import { addFeature } from './migrations.002-add-feature.ts';
+
+const migrations: Migration[] = [init, addFeature];
+```
+
+### 3. Update Table Names (if adding tables)
+
+Export new table names from the migration file and re-export from `migrations.ts`.
+
+## Key Patterns
+
+### Singleton Initialization
+
+Database is lazily initialized on first `getInstance()` call:
+
+```typescript
+public getInstance = async () => {
+  if (!this.#instance) {
+    this.#instance = this.#setup();
+  }
+  return await this.#instance;
+};
+```
+
+### sqlite-vec Loading
+
+The extension is loaded via Knex pool's `afterCreate` hook:
+
+```typescript
+pool: {
+  afterCreate: (conn: Db, done: (err: unknown, conn: Db) => void) => {
+    sqliteVec.load(conn);
+    done(null, conn);
+  },
+},
+```
+
+### Vector Storage
+
+Embeddings are stored as JSON strings and parsed by sqlite-vec:
+
+```typescript
+// Insert
+await db(tableNames.referenceDocumentChunks).insert({
+  embedding: JSON.stringify(vectorArray),
+  // ...
+});
+
+// Query
+db.raw('vec_distance_L2(?, embedding)', [JSON.stringify(queryVector)])
+```
+
+## Configuration
+
+Database path is configured via `database.path` (default: `~/.ai-assist/data.db`).

package/src/database/database.ts

@@ -0,0 +1,64 @@
+import { mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import knex, { type Knex } from 'knex';
+import type { Db } from 'sqlite-vec';
+
+import { migrationSource } from './migrations/migrations.ts';
+
+import { config } from '#root/config/config.ts';
+import { destroy } from '#root/utils/utils.services.ts';
+
+class DatabaseService {
+  #instance?: Promise<Knex>;
+
+  #setup = async () => {
+    const sqliteVec = await import('sqlite-vec');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const dbPath = (config as any).get('database.path') as string;
+
+    // Ensure directory exists
+    const dbDir = dirname(dbPath);
+    if (!existsSync(dbDir)) {
+      mkdirSync(dbDir, { recursive: true });
+    }
+
+    const db = knex({
+      client: 'better-sqlite3',
+      connection: {
+        filename: dbPath,
+      },
+      useNullAsDefault: true,
+      pool: {
+        afterCreate: (conn: Db, done: (err: unknown, conn: Db) => void) => {
+          sqliteVec.load(conn);
+          done(null, conn);
+        },
+      },
+    });
+
+    await db.migrate.latest({
+      migrationSource,
+    });
+
+    return db;
+  };
+
+  public getInstance = async () => {
+    if (!this.#instance) {
+      this.#instance = this.#setup();
+    }
+    return await this.#instance;
+  };
+
+  [destroy] = async () => {
+    if (!this.#instance) {
+      return;
+    }
+    const database = await this.#instance;
+    await database.destroy();
+  };
+}
+
+export { tableNames } from './migrations/migrations.ts';
+export { DatabaseService };

package/src/database/migrations/migrations.001-init.ts

@@ -0,0 +1,56 @@
+import type { Migration } from './migrations.types.ts';
+
+const tableNames = {
+  collections: 'collections',
+  referenceDocuments: 'reference_documents',
+  referenceDocumentChunks: 'reference_documentchunks',
+};
+
+const init: Migration = {
+  name: 'init',
+  up: async (knex) => {
+    await knex.schema.createTable(tableNames.collections, (table) => {
+      table.string('id').primary();
+      table.text('url').notNullable();
+
+      // manifest metadata
+      table.string('name').nullable();
+      table.string('version').nullable();
+      table.text('description').nullable();
+      table.string('manifest_hash').nullable();
+
+      // sync state
+      table.string('last_sync_at').nullable();
+
+      table.string('created_at').notNullable();
+      table.string('updated_at').notNullable();
+    });
+
+    await knex.schema.createTable(tableNames.referenceDocuments, (table) => {
+      table.string('collection').notNullable();
+      table.string('id').notNullable().index();
+      table.string('hash').notNullable().index();
+      table.text('content').notNullable();
+
+      table.primary(['collection', 'id']);
+    });
+
+    await knex.schema.createTable(tableNames.referenceDocumentChunks, (table) => {
+      table.string('id').primary();
+      table.string('document').notNullable();
+      table.string('collection').notNullable();
+      table.text('content').notNullable();
+      table.specificType('embedding', 'vector(1024)').notNullable();
+
+      table.index(['collection']);
+      table.index(['collection', 'document']);
+    });
+  },
+  down: async (knex) => {
+    await knex.schema.dropTable(tableNames.referenceDocumentChunks);
+    await knex.schema.dropTable(tableNames.referenceDocuments);
+    await knex.schema.dropTable(tableNames.collections);
+  },
+};
+
+export { init, tableNames };

package/src/database/migrations/migrations.002-fts5.ts

@@ -0,0 +1,32 @@
+import type { Migration } from './migrations.types.ts';
+
+const ftsTableNames = {
+  referenceDocumentChunksFts: 'reference_documentchunks_fts',
+};
+
+/**
+ * Migration to add FTS5 virtual table for hybrid search.
+ * This enables keyword-based search alongside vector similarity search.
+ */
+const fts5: Migration = {
+  name: 'fts5',
+  up: async (knex) => {
+    // Create FTS5 virtual table for full-text search on chunks
+    // We use content="" to create a contentless FTS table (external content)
+    // This means we manage the content ourselves and just use FTS for indexing
+    await knex.raw(`
+      CREATE VIRTUAL TABLE ${ftsTableNames.referenceDocumentChunksFts} USING fts5(
+        id,
+        collection,
+        document,
+        content,
+        tokenize='porter unicode61'
+      )
+    `);
+  },
+  down: async (knex) => {
+    await knex.raw(`DROP TABLE IF EXISTS ${ftsTableNames.referenceDocumentChunksFts}`);
+  },
+};
+
+export { fts5, ftsTableNames };

package/src/database/migrations/migrations.ts

@@ -0,0 +1,20 @@
+import type { Knex } from 'knex';
+
+import type { Migration } from './migrations.types.ts';
+import { init, tableNames as initTableNames } from './migrations.001-init.ts';
+import { fts5, ftsTableNames } from './migrations.002-fts5.ts';
+
+const migrations: Migration[] = [init, fts5];
+
+const migrationSource: Knex.MigrationSource<Migration> = {
+  getMigration: async (migration) => migration,
+  getMigrationName: (migration) => migration.name,
+  getMigrations: async () => migrations,
+};
+
+const tableNames = {
+  ...initTableNames,
+  ...ftsTableNames,
+};
+
+export { tableNames, migrationSource };

package/src/database/migrations/migrations.types.ts

@@ -0,0 +1,9 @@
+import type { Knex } from 'knex';
+
+type Migration = {
+  name: string;
+  up: (knex: Knex) => Promise<void>;
+  down: (knex: Knex) => Promise<void>;
+};
+
+export type { Migration };