@axiom-lattice/local-stores 1.0.1

package/src/database.ts

@@ -0,0 +1,259 @@
+/**
+ * Shared SQLite database connection for local stores using sql.js (WASM).
+ *
+ * sql.js is a pure JavaScript/WASM SQLite implementation that requires
+ * no native dependencies. The database is persisted to a file on disk.
+ *
+ * @example
+ * ```ts
+ * import { initDatabase, closeDatabase } from "@axiom-lattice/local-stores";
+ *
+ * await initDatabase({ dbPath: "~/.axiom/lattice.db" });
+ * // ... create stores using getDatabase() ...
+ * await closeDatabase();
+ * ```
+ */
+
+import initSqlJs, { type Database as SqlJsDatabase, type SqlJsStatic, type BindParams } from "sql.js";
+import * as path from "path";
+import * as os from "os";
+import * as fs from "fs";
+
+export interface LocalStoreOptions {
+  /**
+   * Path to the SQLite database file.
+   * Supports `~` for home directory expansion.
+   * @default "~/.axiom/lattice.db"
+   */
+  dbPath?: string;
+}
+
+let _SQL: SqlJsStatic | null = null;
+let _db: DatabaseWrapper | null = null;
+
+function expandHome(filePath: string): string {
+  if (filePath.startsWith("~")) {
+    return path.join(os.homedir(), filePath.slice(1));
+  }
+  return filePath;
+}
+
+/**
+ * A thin wrapper around sql.js that provides an API similar to better-sqlite3.
+ */
+export class DatabaseWrapper {
+  private db: SqlJsDatabase;
+  private dbPath: string;
+
+  constructor(sql: SqlJsStatic, dbPath: string) {
+    this.dbPath = dbPath;
+    if (fs.existsSync(dbPath)) {
+      const buffer = fs.readFileSync(dbPath);
+      this.db = new sql.Database(buffer);
+    } else {
+      this.db = new sql.Database();
+    }
+  }
+
+  /**
+   * Execute a SQL statement and return the wrapper for chaining (run).
+   * Automatically persists changes to disk.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  run(sql: string, ...params: any[]): RunResult {
+    this.db.run(sql, params);
+    this.save();
+    return new RunResult(this.db);
+  }
+
+  /**
+   * Prepare and execute a query returning all matching rows as objects.
+   */
+  prepare(sql: string): StatementWrapper {
+    return new StatementWrapper(this.db, sql, this);
+  }
+
+  /**
+   * Execute raw SQL (for DDL statements).
+   */
+  exec(sql: string): void {
+    this.db.exec(sql);
+  }
+
+  /**
+   * Persist the database to disk.
+   */
+  save(): void {
+    const data = this.db.export();
+    const buffer = Buffer.from(data);
+    fs.writeFileSync(this.dbPath, buffer);
+  }
+
+  /**
+   * Close the database.
+   */
+  close(): void {
+    this.db.close();
+  }
+
+  /**
+   * Get the underlying sql.js database instance.
+   */
+  getRawDb(): SqlJsDatabase {
+    return this.db;
+  }
+}
+
+/**
+ * Wraps a prepared statement with a better-sqlite3-like API.
+ */
+export class StatementWrapper {
+  private db: SqlJsDatabase;
+  private sql: string;
+  private parent: DatabaseWrapper | null;
+
+  constructor(db: SqlJsDatabase, sql: string, parent?: DatabaseWrapper) {
+    this.db = db;
+    this.sql = sql;
+    this.parent = parent || null;
+  }
+
+  /**
+   * Execute and return all rows as objects.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  all(...params: any[]): unknown[] {
+    const stmt = this.db.prepare(this.sql);
+    try {
+      if (params.length > 0) {
+        stmt.bind(params as BindParams);
+      }
+      const rows: Record<string, unknown>[] = [];
+      while (stmt.step()) {
+        rows.push(stmt.getAsObject());
+      }
+      return rows;
+    } finally {
+      stmt.free();
+    }
+  }
+
+  /**
+   * Execute and return the first row as an object, or undefined.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  get(...params: any[]): unknown {
+    const stmt = this.db.prepare(this.sql);
+    try {
+      if (params.length > 0) {
+        stmt.bind(params as BindParams);
+      }
+      if (stmt.step()) {
+        return stmt.getAsObject();
+      }
+      return undefined;
+    } finally {
+      stmt.free();
+    }
+  }
+
+  /**
+   * Execute without returning rows (INSERT/UPDATE/DELETE).
+   * Automatically persists changes to disk.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  run(...params: any[]): RunResult {
+    this.db.run(this.sql, params as BindParams);
+    if (this.parent) {
+      this.parent.save();
+    }
+    return new RunResult(this.db);
+  }
+}
+
+/**
+ * Result of a run operation.
+ */
+export class RunResult {
+  private db: SqlJsDatabase;
+
+  constructor(db: SqlJsDatabase) {
+    this.db = db;
+  }
+
+  /** Number of rows modified by the last INSERT/UPDATE/DELETE. */
+  get changes(): number {
+    return this.db.getRowsModified();
+  }
+}
+
+/**
+ * Initialize the shared SQLite database.
+ * Must be called (and awaited) before using any stores.
+ */
+export async function initDatabase(options: LocalStoreOptions = {}): Promise<DatabaseWrapper> {
+  if (_db) return _db;
+
+  if (!_SQL) {
+    _SQL = await initSqlJs();
+  }
+
+  const rawPath = options.dbPath || "~/.axiom/lattice.db";
+  const dbPath = expandHome(rawPath);
+
+  // Ensure parent directory exists
+  const dir = path.dirname(dbPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  _db = new DatabaseWrapper(_SQL, dbPath);
+  _db.exec("PRAGMA journal_mode = WAL;");
+  _db.exec("PRAGMA foreign_keys = ON;");
+
+  return _db;
+}
+
+/**
+ * Get the shared database instance.
+ * Must be called after `await initDatabase()`.
+ */
+export function getDatabase(): DatabaseWrapper {
+  if (!_db) {
+    throw new Error("Database not initialized. Call await initDatabase() first.");
+  }
+  return _db;
+}
+
+/**
+ * Persist and close the database connection.
+ */
+export function closeDatabase(): void {
+  if (_db) {
+    _db.save();
+    _db.close();
+    _db = null;
+  }
+}
+
+/**
+ * Execute a CREATE TABLE IF NOT EXISTS statement.
+ * Helper for idempotent schema initialization.
+ */
+export function ensureTable(db: DatabaseWrapper, ddl: string): void {
+  db.exec(ddl);
+}
+
+/**
+ * ISO timestamp helper — returns current time as ISO string.
+ */
+export function nowISO(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Parse an ISO timestamp string back to a Date object.
+ */
+export function parseISO(iso: string): Date {
+  return new Date(iso);
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @axiom-lattice/local-stores
+ *
+ * Local SQLite-based store implementations for the Axiom Lattice framework.
+ * All stores share a single SQLite database file for zero-config persistence.
+ *
+ * @example
+ * ```ts
+ * import { createLocalStoreConfig, closeDatabase } from "@axiom-lattice/local-stores";
+ * import { configureStores } from "@axiom-lattice/core";
+ *
+ * const stores = await createLocalStoreConfig({ dbPath: "./data/lattice.db" });
+ * const dispose = await configureStores(stores);
+ *
+ * // On shutdown:
+ * await dispose();
+ * closeDatabase();
+ * ```
+ */
+
+export { initDatabase, getDatabase, closeDatabase, ensureTable, nowISO, parseISO, DatabaseWrapper, StatementWrapper, RunResult } from "./database";
+export type { LocalStoreOptions } from "./database";
+
+export { createLocalStoreConfig } from "./createLocalStoreConfig";
+export type { LocalStoreConfigOptions } from "./createLocalStoreConfig";
+
+export { LocalThreadStore } from "./stores/LocalThreadStore";
+export { LocalAssistantStore } from "./stores/LocalAssistantStore";
+export { LocalWorkspaceStore } from "./stores/LocalWorkspaceStore";
+export { LocalProjectStore } from "./stores/LocalProjectStore";
+export { LocalUserStore } from "./stores/LocalUserStore";
+export { LocalTenantStore } from "./stores/LocalTenantStore";
+export { LocalUserTenantLinkStore } from "./stores/LocalUserTenantLinkStore";
+export { LocalDatabaseConfigStore } from "./stores/LocalDatabaseConfigStore";
+export { LocalMetricsServerConfigStore } from "./stores/LocalMetricsServerConfigStore";
+export { LocalMcpServerConfigStore } from "./stores/LocalMcpServerConfigStore";
+export { LocalWorkflowTrackingStore } from "./stores/LocalWorkflowTrackingStore";
+export { LocalEvalStore } from "./stores/LocalEvalStore";
+export { LocalChannelBindingStore } from "./stores/LocalChannelBindingStore";
+export { LocalChannelInstallationStore } from "./stores/LocalChannelInstallationStore";
+export { LocalA2AApiKeyStore } from "./stores/LocalA2AApiKeyStore";
+export { LocalThreadMessageQueueStore } from "./stores/LocalThreadMessageQueueStore";
+export { LocalSkillStore } from "./stores/LocalSkillStore";
+export { LocalScheduleStorage } from "./stores/LocalScheduleStorage";

package/src/stores/LocalA2AApiKeyStore.ts

@@ -0,0 +1,177 @@
+/**
+ * Local SQLite implementation of A2AApiKeyStore.
+ */
+
+import { DatabaseWrapper } from "../database";
+import type {
+  A2AApiKeyStore,
+  A2AApiKeyRecord,
+  CreateA2AApiKeyInput,
+  A2AApiKeyEntry,
+} from "@axiom-lattice/protocols";
+import { ensureTable, nowISO, parseISO } from "../database";
+import { encrypt, decrypt } from "@axiom-lattice/core";
+import { randomUUID } from "crypto";
+
+const DDL = `
+CREATE TABLE IF NOT EXISTS lt_a2a_api_keys (
+  id TEXT PRIMARY KEY,
+  key_value TEXT NOT NULL,
+  tenant_id TEXT NOT NULL,
+  project_id TEXT,
+  workspace_id TEXT,
+  label TEXT,
+  enabled INTEGER NOT NULL DEFAULT 1,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+`;
+
+interface KeyRow {
+  id: string;
+  key_value: string;
+  tenant_id: string;
+  project_id: string | null;
+  workspace_id: string | null;
+  label: string | null;
+  enabled: number;
+  created_at: string;
+  updated_at: string;
+}
+
+function generateApiKey(): string {
+  return `a2a_${randomUUID().replace(/-/g, "")}`;
+}
+
+export class LocalA2AApiKeyStore implements A2AApiKeyStore {
+  private db: DatabaseWrapper;
+
+  constructor(db: DatabaseWrapper) {
+    this.db = db;
+    ensureTable(db, DDL);
+  }
+
+  async findByKey(key: string): Promise<A2AApiKeyRecord | null> {
+    const rows = this.db.prepare(
+      `SELECT * FROM lt_a2a_api_keys WHERE enabled = 1`,
+    ).all() as unknown as KeyRow[];
+    for (const row of rows) {
+      try {
+        if (decrypt(row.key_value) === key) return mapRowToRecord(row);
+      } catch { /* skip unreadable */ }
+    }
+    return null;
+  }
+
+  async list(params: { tenantId?: string; limit?: number; offset?: number }): Promise<A2AApiKeyRecord[]> {
+    const limit = params.limit || 100;
+    const offset = params.offset || 0;
+    let rows: KeyRow[];
+    if (params.tenantId) {
+      rows = this.db.prepare(
+        `SELECT * FROM lt_a2a_api_keys WHERE tenant_id = ? ORDER BY created_at DESC LIMIT ? OFFSET ?`,
+      ).all(params.tenantId, limit, offset) as unknown as KeyRow[];
+    } else {
+      rows = this.db.prepare(
+        `SELECT * FROM lt_a2a_api_keys ORDER BY created_at DESC LIMIT ? OFFSET ?`,
+      ).all(limit, offset) as unknown as KeyRow[];
+    }
+    return rows.map(mapRowToRecord);
+  }
+
+  async create(input: CreateA2AApiKeyInput): Promise<A2AApiKeyRecord> {
+    const key = generateApiKey();
+    const now = nowISO();
+    this.db.prepare(
+      `INSERT INTO lt_a2a_api_keys (key_value, tenant_id, project_id, workspace_id, label, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    ).run(encrypt(key), input.tenantId, input.projectId || null, input.workspaceId || null, input.label || null, now, now);
+
+    const lastId = this.db.prepare(`SELECT last_insert_rowid() as id`).get() as { id: number };
+
+    const record: A2AApiKeyRecord = {
+      id: String(lastId.id),
+      key,
+      tenantId: input.tenantId,
+      projectId: input.projectId,
+      workspaceId: input.workspaceId,
+      label: input.label,
+      enabled: true,
+      createdAt: parseISO(now),
+      updatedAt: parseISO(now),
+    };
+    return record;
+  }
+
+  async disable(id: string): Promise<A2AApiKeyRecord> {
+    const now = nowISO();
+    this.db.prepare(
+      `UPDATE lt_a2a_api_keys SET enabled = 0, updated_at = ? WHERE id = ?`,
+    ).run(now, id);
+    const row = this.db.prepare(`SELECT * FROM lt_a2a_api_keys WHERE id = ?`).get(id) as unknown as KeyRow;
+    if (!row) throw new Error(`A2A API key not found: ${id}`);
+    return mapRowToRecord(row);
+  }
+
+  async enable(id: string): Promise<A2AApiKeyRecord> {
+    const now = nowISO();
+    this.db.prepare(
+      `UPDATE lt_a2a_api_keys SET enabled = 1, updated_at = ? WHERE id = ?`,
+    ).run(now, id);
+    const row = this.db.prepare(`SELECT * FROM lt_a2a_api_keys WHERE id = ?`).get(id) as unknown as KeyRow;
+    if (!row) throw new Error(`A2A API key not found: ${id}`);
+    return mapRowToRecord(row);
+  }
+
+  async rotate(id: string): Promise<A2AApiKeyRecord> {
+    const key = generateApiKey();
+    const now = nowISO();
+    this.db.prepare(
+      `UPDATE lt_a2a_api_keys SET key_value = ?, updated_at = ? WHERE id = ?`,
+    ).run(encrypt(key), now, id);
+    const row = this.db.prepare(`SELECT * FROM lt_a2a_api_keys WHERE id = ?`).get(id) as unknown as KeyRow;
+    if (!row) throw new Error(`A2A API key not found: ${id}`);
+    const record = mapRowToRecord(row);
+    record.key = key;
+    return record;
+  }
+
+  async delete(id: string): Promise<void> {
+    this.db.prepare(`DELETE FROM lt_a2a_api_keys WHERE id = ?`).run(id);
+  }
+
+  async loadIntoMap(): Promise<Map<string, A2AApiKeyEntry>> {
+    const rows = this.db.prepare(
+      `SELECT * FROM lt_a2a_api_keys WHERE enabled = 1`,
+    ).all() as unknown as KeyRow[];
+    const map = new Map<string, A2AApiKeyEntry>();
+    for (const row of rows) {
+      try {
+        const key = decrypt(row.key_value);
+        map.set(key, {
+          key,
+          tenantId: row.tenant_id,
+          projectId: row.project_id || undefined,
+          workspaceId: row.workspace_id || undefined,
+        });
+      } catch { /* skip */ }
+    }
+    return map;
+  }
+}
+
+function mapRowToRecord(row: KeyRow): A2AApiKeyRecord {
+  let key = "";
+  try { key = decrypt(row.key_value); } catch { key = row.key_value; }
+  return {
+    id: row.id,
+    key,
+    tenantId: row.tenant_id,
+    projectId: row.project_id || undefined,
+    workspaceId: row.workspace_id || undefined,
+    label: row.label || undefined,
+    enabled: row.enabled === 1,
+    createdAt: parseISO(row.created_at),
+    updatedAt: parseISO(row.updated_at),
+  };
+}

package/src/stores/LocalAssistantStore.ts

@@ -0,0 +1,149 @@
+/**
+ * Local SQLite implementation of AssistantStore.
+ */
+
+import { DatabaseWrapper } from "../database";
+import type {
+  AssistantStore,
+  Assistant,
+  CreateAssistantRequest,
+} from "@axiom-lattice/protocols";
+import { ensureTable, nowISO, parseISO } from "../database";
+
+const DDL = `
+CREATE TABLE IF NOT EXISTS lt_assistants (
+  id TEXT NOT NULL,
+  tenant_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  description TEXT,
+  graph_definition TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (tenant_id, id)
+);
+`;
+
+interface AssistantRow {
+  id: string;
+  tenant_id: string;
+  name: string;
+  description: string | null;
+  graph_definition: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export class LocalAssistantStore implements AssistantStore {
+  private db: DatabaseWrapper;
+
+  constructor(db: DatabaseWrapper) {
+    this.db = db;
+    ensureTable(db, DDL);
+  }
+
+  async getAllAssistants(tenantId: string): Promise<Assistant[]> {
+    const rows = this.db.prepare(
+      `SELECT * FROM lt_assistants WHERE tenant_id = ? ORDER BY created_at DESC`,
+    ).all(tenantId) as unknown as AssistantRow[];
+    return rows.map(mapRowToAssistant);
+  }
+
+  async getAssistantById(tenantId: string, id: string): Promise<Assistant | null> {
+    const row = this.db.prepare(
+      `SELECT * FROM lt_assistants WHERE tenant_id = ? AND id = ?`,
+    ).get(tenantId, id) as unknown as AssistantRow | undefined;
+    return row ? mapRowToAssistant(row) : null;
+  }
+
+  async createAssistant(
+    tenantId: string,
+    id: string,
+    data: CreateAssistantRequest,
+  ): Promise<Assistant> {
+    const now = nowISO();
+
+    this.db.prepare(
+      `INSERT INTO lt_assistants (id, tenant_id, name, description, graph_definition, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(tenant_id, id) DO UPDATE SET
+         name = excluded.name,
+         description = excluded.description,
+         graph_definition = excluded.graph_definition,
+         updated_at = excluded.updated_at`,
+    ).run(id, tenantId, data.name, data.description || null, JSON.stringify(data.graphDefinition), now, now);
+
+    return {
+      id,
+      tenantId,
+      name: data.name,
+      description: data.description,
+      graphDefinition: data.graphDefinition,
+      createdAt: parseISO(now),
+      updatedAt: parseISO(now),
+    };
+  }
+
+  async updateAssistant(
+    tenantId: string,
+    id: string,
+    updates: Partial<CreateAssistantRequest>,
+  ): Promise<Assistant | null> {
+    const existing = await this.getAssistantById(tenantId, id);
+    if (!existing) return null;
+
+    const setClauses: string[] = [];
+    const values: unknown[] = [];
+
+    if (updates.name !== undefined) {
+      setClauses.push("name = ?");
+      values.push(updates.name);
+    }
+    if (updates.description !== undefined) {
+      setClauses.push("description = ?");
+      values.push(updates.description || null);
+    }
+    if (updates.graphDefinition !== undefined) {
+      setClauses.push("graph_definition = ?");
+      values.push(JSON.stringify(updates.graphDefinition));
+    }
+
+    if (setClauses.length === 0) return existing;
+
+    const now = nowISO();
+    setClauses.push("updated_at = ?");
+    values.push(now);
+    values.push(tenantId, id);
+
+    this.db.prepare(
+      `UPDATE lt_assistants SET ${setClauses.join(", ")} WHERE tenant_id = ? AND id = ?`,
+    ).run(...values);
+
+    return this.getAssistantById(tenantId, id);
+  }
+
+  async deleteAssistant(tenantId: string, id: string): Promise<boolean> {
+    const result = this.db.prepare(
+      `DELETE FROM lt_assistants WHERE tenant_id = ? AND id = ?`,
+    ).run(tenantId, id);
+    return result.changes > 0;
+  }
+
+  async hasAssistant(tenantId: string, id: string): Promise<boolean> {
+    const row = this.db.prepare(
+      `SELECT 1 FROM lt_assistants WHERE tenant_id = ? AND id = ? LIMIT 1`,
+    ).get(tenantId, id);
+    return row !== undefined;
+  }
+}
+
+function mapRowToAssistant(row: AssistantRow): Assistant {
+  return {
+    id: row.id,
+    tenantId: row.tenant_id,
+    name: row.name,
+    description: row.description || undefined,
+    graphDefinition: JSON.parse(row.graph_definition),
+    createdAt: parseISO(row.created_at),
+    updatedAt: parseISO(row.updated_at),
+  };
+}