@timmeck/brain-core 1.0.0

package/dist/utils/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,MAAM,OAAO,aAAiD,SAAQ,YAAY;IAChF,IAAI,CAA6B,KAAQ,EAAE,IAAU;QACnD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,EAAE,CAA6B,KAAQ,EAAE,QAA8B;QACrE,OAAO,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,IAAI,CAA6B,KAAQ,EAAE,QAA8B;QACvE,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED,GAAG,CAA6B,KAAQ,EAAE,QAA8B;QACtE,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACpC,CAAC;CACF"}

package/dist/utils/hash.d.ts

@@ -0,0 +1 @@
+export declare function sha256(input: string): string;

package/dist/utils/hash.js

@@ -0,0 +1,5 @@
+import { createHash } from 'node:crypto';
+export function sha256(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+//# sourceMappingURL=hash.js.map

package/dist/utils/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,UAAU,MAAM,CAAC,KAAa;IAClC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,16 @@
+import winston from 'winston';
+export interface LoggerOptions {
+    level?: string;
+    file?: string;
+    maxSize?: number;
+    maxFiles?: number;
+    /** Environment variable name for log level override (e.g. 'BRAIN_LOG_LEVEL') */
+    envVar?: string;
+    /** Default log filename when no file is specified (e.g. 'brain.log') */
+    defaultFilename?: string;
+    /** Data directory to place the log file in */
+    dataDir?: string;
+}
+export declare function createLogger(opts?: LoggerOptions): winston.Logger;
+export declare function getLogger(): winston.Logger;
+export declare function resetLogger(): void;

package/dist/utils/logger.js

@@ -0,0 +1,43 @@
+import winston from 'winston';
+import path from 'node:path';
+const { combine, timestamp, printf, colorize } = winston.format;
+const logFormat = printf(({ level, message, timestamp, ...meta }) => {
+    const metaStr = Object.keys(meta).length ? ` ${JSON.stringify(meta)}` : '';
+    return `${timestamp} [${level}]${metaStr} ${message}`;
+});
+let loggerInstance = null;
+export function createLogger(opts) {
+    if (loggerInstance)
+        return loggerInstance;
+    const envVar = opts?.envVar ?? 'BRAIN_LOG_LEVEL';
+    const defaultFilename = opts?.defaultFilename ?? 'brain.log';
+    const level = opts?.level ?? process.env[envVar] ?? 'info';
+    const logFile = opts?.file ?? (opts?.dataDir ? path.join(opts.dataDir, defaultFilename) : defaultFilename);
+    const maxSize = opts?.maxSize ?? 10 * 1024 * 1024; // 10MB
+    const maxFiles = opts?.maxFiles ?? 3;
+    const transports = [
+        new winston.transports.File({
+            filename: logFile,
+            maxsize: maxSize,
+            maxFiles,
+            format: combine(timestamp(), logFormat),
+        }),
+    ];
+    if (process.env['NODE_ENV'] !== 'production') {
+        transports.push(new winston.transports.Console({
+            format: combine(colorize(), timestamp(), logFormat),
+        }));
+    }
+    loggerInstance = winston.createLogger({ level, transports });
+    return loggerInstance;
+}
+export function getLogger() {
+    if (!loggerInstance) {
+        return createLogger();
+    }
+    return loggerInstance;
+}
+export function resetLogger() {
+    loggerInstance = null;
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;AAEhE,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE;IAClE,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3E,OAAO,GAAG,SAAS,KAAK,KAAK,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;AACxD,CAAC,CAAC,CAAC;AAEH,IAAI,cAAc,GAA0B,IAAI,CAAC;AAejD,MAAM,UAAU,YAAY,CAAC,IAAoB;IAC/C,IAAI,cAAc;QAAE,OAAO,cAAc,CAAC;IAE1C,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,iBAAiB,CAAC;IACjD,MAAM,eAAe,GAAG,IAAI,EAAE,eAAe,IAAI,WAAW,CAAC;IAE7D,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC;IAC3D,MAAM,OAAO,GAAG,IAAI,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;IAC3G,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO;IAC1D,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,CAAC,CAAC;IAErC,MAAM,UAAU,GAAwB;QACtC,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;YAC1B,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,OAAO;YAChB,QAAQ;YACR,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,EAAE,SAAS,CAAC;SACxC,CAAC;KACH,CAAC;IAEF,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,YAAY,EAAE,CAAC;QAC7C,UAAU,CAAC,IAAI,CACb,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;YAC7B,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,EAAE,SAAS,CAAC;SACpD,CAAC,CACH,CAAC;IACJ,CAAC;IAED,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IAC7D,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,OAAO,YAAY,EAAE,CAAC;IACxB,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,cAAc,GAAG,IAAI,CAAC;AACxB,CAAC"}

package/dist/utils/paths.d.ts

@@ -0,0 +1,8 @@
+export declare function normalizePath(filePath: string): string;
+/**
+ * Get the data directory for a brain instance.
+ * @param envVar - Environment variable name (e.g. 'BRAIN_DATA_DIR')
+ * @param defaultDir - Default directory name in home (e.g. '.brain')
+ */
+export declare function getDataDir(envVar?: string, defaultDir?: string): string;
+export declare function getPipeName(name?: string): string;

package/dist/utils/paths.js

@@ -0,0 +1,23 @@
+import path from 'node:path';
+import os from 'node:os';
+export function normalizePath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+/**
+ * Get the data directory for a brain instance.
+ * @param envVar - Environment variable name (e.g. 'BRAIN_DATA_DIR')
+ * @param defaultDir - Default directory name in home (e.g. '.brain')
+ */
+export function getDataDir(envVar = 'BRAIN_DATA_DIR', defaultDir = '.brain') {
+    const envDirValue = process.env[envVar];
+    if (envDirValue)
+        return path.resolve(envDirValue);
+    return path.join(os.homedir(), defaultDir);
+}
+export function getPipeName(name = 'brain') {
+    if (process.platform === 'win32') {
+        return `\\\\.\\pipe\\${name}`;
+    }
+    return path.join(os.tmpdir(), `${name}.sock`);
+}
+//# sourceMappingURL=paths.js.map

package/dist/utils/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,OAAO,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,SAAiB,gBAAgB,EAAE,aAAqB,QAAQ;IACzF,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,WAAW;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAClD,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe,OAAO;IAChD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO,gBAAgB,IAAI,EAAE,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC;AAChD,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@timmeck/brain-core",
+  "version": "1.0.0",
+  "description": "Shared core infrastructure for the Brain ecosystem — IPC, MCP, CLI, DB connection, and utilities",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./types": "./dist/types/ipc.types.js",
+    "./utils/hash": "./dist/utils/hash.js",
+    "./utils/logger": "./dist/utils/logger.js",
+    "./utils/paths": "./dist/utils/paths.js",
+    "./utils/events": "./dist/utils/events.js",
+    "./db": "./dist/db/connection.js",
+    "./ipc/protocol": "./dist/ipc/protocol.js",
+    "./ipc/server": "./dist/ipc/server.js",
+    "./ipc/client": "./dist/ipc/client.js",
+    "./mcp/server": "./dist/mcp/server.js",
+    "./mcp/http-server": "./dist/mcp/http-server.js",
+    "./cli/colors": "./dist/cli/colors.js",
+    "./api/server": "./dist/api/server.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest"
+  },
+  "keywords": [
+    "brain",
+    "brain-core",
+    "mcp",
+    "claude-code",
+    "ipc",
+    "named-pipes",
+    "synapse-network",
+    "developer-tools",
+    "shared-infrastructure"
+  ],
+  "author": "Tim Mecklenburg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/timmeck/brain-core"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^11.7.0",
+    "chalk": "^5.6.2",
+    "winston": "^3.17.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/api/server.ts

@@ -0,0 +1,210 @@
+import http from 'node:http';
+import { getLogger } from '../utils/logger.js';
+import type { IpcRouter } from '../ipc/server.js';
+
+export interface ApiServerOptions {
+  port: number;
+  router: IpcRouter;
+  apiKey?: string;
+}
+
+export interface RouteDefinition {
+  method: string;
+  pattern: RegExp;
+  ipcMethod: string;
+  extractParams: (match: RegExpMatchArray, query: URLSearchParams, body?: unknown) => unknown;
+}
+
+export class BaseApiServer {
+  private server: http.Server | null = null;
+  protected logger = getLogger();
+  private routes: RouteDefinition[];
+  protected sseClients: Set<http.ServerResponse> = new Set();
+
+  constructor(protected options: ApiServerOptions) {
+    this.routes = this.buildRoutes();
+  }
+
+  start(): void {
+    const { port, apiKey } = this.options;
+
+    this.server = http.createServer((req, res) => {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-API-Key');
+
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      if (apiKey) {
+        const provided = (req.headers['x-api-key'] as string) ??
+          req.headers.authorization?.replace('Bearer ', '');
+        if (provided !== apiKey) {
+          this.json(res, 401, { error: 'Unauthorized', message: 'Invalid or missing API key' });
+          return;
+        }
+      }
+
+      this.handleRequest(req, res).catch((err) => {
+        this.logger.error('API error:', err);
+        this.json(res, 500, {
+          error: 'Internal Server Error',
+          message: err instanceof Error ? err.message : String(err),
+        });
+      });
+    });
+
+    this.server.listen(port, () => {
+      this.logger.info(`REST API server started on http://localhost:${port}`);
+    });
+  }
+
+  stop(): void {
+    for (const client of this.sseClients) {
+      try { client.end(); } catch { /* ignore */ }
+    }
+    this.sseClients.clear();
+    this.server?.close();
+    this.server = null;
+    this.logger.info('REST API server stopped');
+  }
+
+  /** Override to add domain-specific RESTful routes */
+  protected buildRoutes(): RouteDefinition[] {
+    return [];
+  }
+
+  private async handleRequest(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const pathname = url.pathname;
+    const method = req.method ?? 'GET';
+    const query = url.searchParams;
+
+    // Health check
+    if (pathname === '/api/v1/health') {
+      this.json(res, 200, { status: 'ok', timestamp: new Date().toISOString() });
+      return;
+    }
+
+    // SSE event stream
+    if (pathname === '/api/v1/events' && method === 'GET') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+      });
+      res.write('data: {"type":"connected"}\n\n');
+      this.sseClients.add(res);
+      req.on('close', () => this.sseClients.delete(res));
+      return;
+    }
+
+    // List all available methods
+    if (pathname === '/api/v1/methods' && method === 'GET') {
+      const methods = this.options.router.listMethods();
+      this.json(res, 200, {
+        methods,
+        rpcEndpoint: '/api/v1/rpc',
+        usage: 'POST /api/v1/rpc with body { "method": "<method>", "params": {...} }',
+      });
+      return;
+    }
+
+    // Generic RPC endpoint
+    if (pathname === '/api/v1/rpc' && method === 'POST') {
+      const body = await this.readBody(req);
+      if (!body) {
+        this.json(res, 400, { error: 'Bad Request', message: 'Empty request body' });
+        return;
+      }
+
+      const parsed = JSON.parse(body);
+
+      // Batch RPC support
+      if (Array.isArray(parsed)) {
+        const results = parsed.map((call: { method: string; params?: unknown; id?: string | number }) => {
+          try {
+            const result = this.options.router.handle(call.method, call.params ?? {});
+            return { id: call.id, result };
+          } catch (err) {
+            return { id: call.id, error: err instanceof Error ? err.message : String(err) };
+          }
+        });
+        this.json(res, 200, results);
+        return;
+      }
+
+      if (!parsed.method) {
+        this.json(res, 400, { error: 'Bad Request', message: 'Missing "method" field' });
+        return;
+      }
+
+      try {
+        const result = this.options.router.handle(parsed.method, parsed.params ?? {});
+        this.json(res, 200, { result });
+      } catch (err) {
+        this.json(res, 400, { error: err instanceof Error ? err.message : String(err) });
+      }
+      return;
+    }
+
+    // RESTful routes
+    let body: unknown = undefined;
+    if (method === 'POST' || method === 'PUT') {
+      try {
+        const raw = await this.readBody(req);
+        body = raw ? JSON.parse(raw) : {};
+      } catch {
+        this.json(res, 400, { error: 'Bad Request', message: 'Invalid JSON body' });
+        return;
+      }
+    }
+
+    for (const route of this.routes) {
+      if (route.method !== method) continue;
+      const match = pathname.match(route.pattern);
+      if (!match) continue;
+
+      try {
+        const params = route.extractParams(match, query, body);
+        const result = this.options.router.handle(route.ipcMethod, params);
+        this.json(res, method === 'POST' ? 201 : 200, { result });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const status = msg.startsWith('Unknown method') ? 404 : 400;
+        this.json(res, status, { error: msg });
+      }
+      return;
+    }
+
+    this.json(res, 404, { error: 'Not Found', message: `No route for ${method} ${pathname}` });
+  }
+
+  protected json(res: http.ServerResponse, status: number, data: unknown): void {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(data));
+  }
+
+  protected readBody(req: http.IncomingMessage): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      req.on('data', (chunk: Buffer) => chunks.push(chunk));
+      req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+      req.on('error', reject);
+    });
+  }
+
+  protected broadcastSSE(data: unknown): void {
+    const msg = `data: ${JSON.stringify(data)}\n\n`;
+    for (const client of this.sseClients) {
+      try {
+        client.write(msg);
+      } catch {
+        this.sseClients.delete(client);
+      }
+    }
+  }
+}

package/src/cli/colors.ts

@@ -0,0 +1,105 @@
+import chalk from 'chalk';
+
+// Shared brand color palette — identical across all brains
+export const c = {
+  // Primary palette
+  blue: chalk.hex('#5b9cff'),
+  purple: chalk.hex('#b47aff'),
+  cyan: chalk.hex('#47e5ff'),
+  green: chalk.hex('#3dffa0'),
+  red: chalk.hex('#ff5577'),
+  orange: chalk.hex('#ffb347'),
+  dim: chalk.hex('#8b8fb0'),
+  dimmer: chalk.hex('#4a4d6e'),
+
+  // Semantic
+  label: chalk.hex('#8b8fb0'),
+  value: chalk.white.bold,
+  heading: chalk.hex('#5b9cff').bold,
+  success: chalk.hex('#3dffa0').bold,
+  error: chalk.hex('#ff5577').bold,
+  warn: chalk.hex('#ffb347').bold,
+  info: chalk.hex('#47e5ff'),
+};
+
+// Shared base icons — each brain extends with domain-specific icons
+export const baseIcons = {
+  check: '\u2713',
+  cross: '\u2717',
+  arrow: '\u2192',
+  dot: '\u25CF',
+  circle: '\u25CB',
+  bar: '\u2588',
+  barLight: '\u2591',
+  dash: '\u2500',
+  pipe: '\u2502',
+  corner: '\u2514',
+  tee: '\u251C',
+  star: '\u2605',
+  bolt: '\u26A1',
+  gear: '\u2699',
+  chart: '\uD83D\uDCCA',
+  synapse: '\uD83D\uDD17',
+  insight: '\uD83D\uDCA1',
+  warn: '\u26A0',
+  error: '\u274C',
+  ok: '\u2705',
+  clock: '\u23F1',
+};
+
+export function header(title: string, icon?: string): string {
+  const prefix = icon ? `${icon}  ` : '';
+  const line = c.dimmer(baseIcons.dash.repeat(40));
+  return `\n${line}\n${prefix}${c.heading(title)}\n${line}`;
+}
+
+export function keyValue(key: string, value: string | number, indent = 2): string {
+  const pad = ' '.repeat(indent);
+  return `${pad}${c.label(key + ':')} ${c.value(String(value))}`;
+}
+
+export function statusBadge(status: string): string {
+  switch (status.toLowerCase()) {
+    case 'resolved':
+    case 'active':
+    case 'running':
+      return c.green(`[${status.toUpperCase()}]`);
+    case 'open':
+    case 'unresolved':
+      return c.red(`[${status.toUpperCase()}]`);
+    case 'warning':
+      return c.warn(`[${status.toUpperCase()}]`);
+    default:
+      return c.dim(`[${status.toUpperCase()}]`);
+  }
+}
+
+export function progressBar(current: number, total: number, width = 20): string {
+  const pct = Math.min(1, current / Math.max(1, total));
+  const filled = Math.round(pct * width);
+  const empty = width - filled;
+  return c.cyan(baseIcons.bar.repeat(filled)) + c.dimmer(baseIcons.barLight.repeat(empty));
+}
+
+export function divider(width = 40): string {
+  return c.dimmer(baseIcons.dash.repeat(width));
+}
+
+export function table(rows: string[][], colWidths?: number[]): string {
+  if (rows.length === 0) return '';
+  const widths = colWidths ?? rows[0].map((_, i) =>
+    Math.max(...rows.map(r => stripAnsi(r[i] ?? '').length))
+  );
+  return rows.map(row =>
+    row.map((cell, i) => {
+      const stripped = stripAnsi(cell);
+      const pad = Math.max(0, (widths[i] ?? stripped.length) - stripped.length);
+      return cell + ' '.repeat(pad);
+    }).join('  ')
+  ).join('\n');
+}
+
+export function stripAnsi(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*m/g, '');
+}

package/src/db/connection.ts

@@ -0,0 +1,22 @@
+import Database from 'better-sqlite3';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLogger } from '../utils/logger.js';
+
+export function createConnection(dbPath: string): Database.Database {
+  const logger = getLogger();
+  const dir = path.dirname(dbPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  logger.info(`Opening database at ${dbPath}`);
+  const db = new Database(dbPath);
+
+  db.pragma('journal_mode = WAL');
+  db.pragma('synchronous = NORMAL');
+  db.pragma('cache_size = 10000');
+  db.pragma('foreign_keys = ON');
+
+  return db;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+// ── Types ──────────────────────────────────────────────────
+export type { IpcMessage } from './types/ipc.types.js';
+
+// ── Utils ──────────────────────────────────────────────────
+export { sha256 } from './utils/hash.js';
+export { createLogger, getLogger, resetLogger } from './utils/logger.js';
+export type { LoggerOptions } from './utils/logger.js';
+export { normalizePath, getDataDir, getPipeName } from './utils/paths.js';
+export { TypedEventBus } from './utils/events.js';
+
+// ── DB ─────────────────────────────────────────────────────
+export { createConnection } from './db/connection.js';
+
+// ── IPC ────────────────────────────────────────────────────
+export { encodeMessage, MessageDecoder } from './ipc/protocol.js';
+export { IpcServer } from './ipc/server.js';
+export type { IpcRouter } from './ipc/server.js';
+export { IpcClient } from './ipc/client.js';
+
+// ── MCP ────────────────────────────────────────────────────
+export { startMcpServer } from './mcp/server.js';
+export type { McpServerOptions } from './mcp/server.js';
+export { McpHttpServer } from './mcp/http-server.js';
+export type { McpHttpServerOptions } from './mcp/http-server.js';
+
+// ── CLI ────────────────────────────────────────────────────
+export { c, baseIcons, header, keyValue, statusBadge, progressBar, divider, table, stripAnsi } from './cli/colors.js';
+
+// ── API ────────────────────────────────────────────────────
+export { BaseApiServer } from './api/server.js';
+export type { ApiServerOptions, RouteDefinition } from './api/server.js';

package/src/ipc/client.ts

@@ -0,0 +1,117 @@
+import net from 'node:net';
+import { randomUUID } from 'node:crypto';
+import type { IpcMessage } from '../types/ipc.types.js';
+import { encodeMessage, MessageDecoder } from './protocol.js';
+import { getPipeName } from '../utils/paths.js';
+
+interface PendingRequest {
+  resolve: (result: unknown) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class IpcClient {
+  private socket: net.Socket | null = null;
+  private decoder = new MessageDecoder();
+  private pending = new Map<string, PendingRequest>();
+  private onNotification?: (msg: IpcMessage) => void;
+
+  constructor(
+    private pipeName: string = getPipeName(),
+    private timeout: number = 5000,
+  ) {}
+
+  connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.socket = net.createConnection(this.pipeName, () => {
+        resolve();
+      });
+
+      this.socket.on('data', (chunk) => {
+        const messages = this.decoder.feed(chunk);
+        for (const msg of messages) {
+          this.handleMessage(msg);
+        }
+      });
+
+      this.socket.on('error', (err) => {
+        reject(err);
+        for (const [id, req] of this.pending) {
+          clearTimeout(req.timer);
+          req.reject(new Error(`Connection error: ${err.message}`));
+          this.pending.delete(id);
+        }
+      });
+
+      this.socket.on('close', () => {
+        for (const [id, req] of this.pending) {
+          clearTimeout(req.timer);
+          req.reject(new Error('Connection closed'));
+          this.pending.delete(id);
+        }
+        this.socket = null;
+      });
+    });
+  }
+
+  request(method: string, params?: unknown): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      if (!this.socket || this.socket.destroyed) {
+        return reject(new Error('Not connected'));
+      }
+
+      const id = randomUUID();
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Request timeout: ${method} (${this.timeout}ms)`));
+      }, this.timeout);
+
+      this.pending.set(id, { resolve, reject, timer });
+
+      const msg: IpcMessage = {
+        id,
+        type: 'request',
+        method,
+        params,
+      };
+      this.socket.write(encodeMessage(msg));
+    });
+  }
+
+  setNotificationHandler(handler: (msg: IpcMessage) => void): void {
+    this.onNotification = handler;
+  }
+
+  disconnect(): void {
+    for (const [id, req] of this.pending) {
+      clearTimeout(req.timer);
+      req.reject(new Error('Client disconnecting'));
+      this.pending.delete(id);
+    }
+    this.socket?.destroy();
+    this.socket = null;
+    this.decoder.reset();
+  }
+
+  get connected(): boolean {
+    return this.socket !== null && !this.socket.destroyed;
+  }
+
+  private handleMessage(msg: IpcMessage): void {
+    if (msg.type === 'response') {
+      const req = this.pending.get(msg.id);
+      if (!req) return;
+
+      clearTimeout(req.timer);
+      this.pending.delete(msg.id);
+
+      if (msg.error) {
+        req.reject(new Error(msg.error.message));
+      } else {
+        req.resolve(msg.result);
+      }
+    } else if (msg.type === 'notification') {
+      this.onNotification?.(msg);
+    }
+  }
+}