@kb-labs/adapters 0.5.0

package/packages/adapters-redis/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/packages/adapters-redis/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node';
+
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json',
+  entry: ['src/index.ts', 'src/manifest.ts'],
+  dts: true,
+});

package/packages/adapters-snapshot-localfs/README.md

@@ -0,0 +1,10 @@
+# @kb-labs/adapters-snapshot-localfs
+
+Local filesystem implementation of `ISnapshotProvider`.
+
+## Features
+
+- Capture snapshot by copying source directory into snapshot store
+- Restore snapshot to target directory
+- Status/delete/garbage-collect lifecycle
+- Can resolve workspace root from workspace registry

package/packages/adapters-snapshot-localfs/eslint.config.js

@@ -0,0 +1,2 @@
+import cfg from '@kb-labs/devkit/eslint/node.js';
+export default cfg;

package/packages/adapters-snapshot-localfs/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kb-labs/adapters-snapshot-localfs",
+  "version": "0.5.0",
+  "description": "Local filesystem adapter implementing ISnapshotProvider",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix"
+  },
+  "peerDependencies": {
+    "@kb-labs/core-platform": "*"
+  },
+  "devDependencies": {
+    "@kb-labs/core-platform": "link:../../../../platform/kb-labs-core/packages/core-platform",
+    "@types/node": "^24.3.3",
+    "eslint": "^9",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "rimraf": "^6.0.1"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}

package/packages/adapters-snapshot-localfs/src/index.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { mkdtemp, rm, writeFile, readFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { LocalFsSnapshotAdapter } from './index.js';
+
+describe('LocalFsSnapshotAdapter', () => {
+  it('captures and restores workspace snapshot', async () => {
+    const tmp = await mkdtemp(path.join(os.tmpdir(), 'kb-snapshot-'));
+    try {
+      const workspaceId = 'ws_1';
+      const workspaceRoot = path.join(tmp, 'demo');
+      await mkdir(path.join(tmp, '.kb/runtime/workspace-registry'), { recursive: true });
+      await mkdir(workspaceRoot, { recursive: true });
+      await writeFile(
+        path.join(tmp, '.kb/runtime/workspace-registry', `${workspaceId}.json`),
+        JSON.stringify({ workspaceId, rootPath: workspaceRoot }, null, 2),
+        'utf8'
+      );
+
+      const filePath = path.join(workspaceRoot, 'hello.txt');
+      await writeFile(filePath, 'v1', 'utf8');
+
+      const snapshot = new LocalFsSnapshotAdapter({ workspace: { cwd: tmp } });
+      const snap = await snapshot.capture({ workspaceId, namespace: 'demo' });
+
+      await writeFile(filePath, 'v2', 'utf8');
+      await snapshot.restore({
+        snapshotId: snap.snapshotId,
+        workspaceId,
+        overwrite: true,
+      });
+
+      const restored = await readFile(filePath, 'utf8');
+      expect(restored).toBe('v1');
+    } finally {
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+});

package/packages/adapters-snapshot-localfs/src/index.ts

@@ -0,0 +1,292 @@
+import { mkdir, readFile, rm, writeFile, access, cp, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type {
+  ISnapshotProvider,
+  CaptureSnapshotRequest,
+  SnapshotDescriptor,
+  RestoreSnapshotRequest,
+  RestoreSnapshotResult,
+  SnapshotStatusResult,
+  SnapshotGarbageCollectRequest,
+  SnapshotGarbageCollectResult,
+  SnapshotProviderCapabilities,
+  SnapshotStatus,
+} from '@kb-labs/core-platform';
+
+export { manifest } from './manifest.js';
+
+interface WorkspaceContext {
+  cwd?: string;
+}
+
+export interface LocalFsSnapshotAdapterConfig {
+  storageDir?: string;
+  workspaceRegistryDir?: string;
+  workspace?: WorkspaceContext;
+}
+
+interface SnapshotRecord {
+  snapshotId: string;
+  status: SnapshotStatus;
+  createdAt: string;
+  updatedAt: string;
+  workspaceId?: string;
+  environmentId?: string;
+  sourcePath: string;
+  payloadPath: string;
+  namespace?: string;
+}
+
+interface WorkspaceRecord {
+  workspaceId: string;
+  rootPath?: string;
+}
+
+export class LocalFsSnapshotAdapter implements ISnapshotProvider {
+  private readonly cwd: string;
+  private readonly storageDir: string;
+  private readonly workspaceRegistryDir: string;
+  private readonly records = new Map<string, SnapshotRecord>();
+
+  constructor(private readonly config: LocalFsSnapshotAdapterConfig = {}) {
+    this.cwd = path.resolve(config.workspace?.cwd ?? process.cwd());
+    this.storageDir = path.resolve(this.cwd, config.storageDir ?? '.kb/runtime/snapshots');
+    this.workspaceRegistryDir = path.resolve(
+      this.cwd,
+      config.workspaceRegistryDir ?? '.kb/runtime/workspace-registry'
+    );
+  }
+
+  async capture(request: CaptureSnapshotRequest): Promise<SnapshotDescriptor> {
+    const snapshotId = request.snapshotId ?? `snap_${randomUUID()}`;
+    const now = new Date().toISOString();
+    const sourcePath = await this.resolveSourcePath(request);
+    const namespace = request.namespace ?? 'default';
+    const payloadPath = path.join(this.storageDir, namespace, snapshotId);
+
+    await mkdir(path.dirname(payloadPath), { recursive: true });
+    await rm(payloadPath, { recursive: true, force: true });
+    await cp(sourcePath, payloadPath, { recursive: true, force: true });
+
+    const record: SnapshotRecord = {
+      snapshotId,
+      status: 'ready',
+      createdAt: now,
+      updatedAt: now,
+      workspaceId: request.workspaceId,
+      environmentId: request.environmentId,
+      sourcePath,
+      payloadPath,
+      namespace,
+    };
+
+    await this.persistRecord(record);
+
+    return {
+      snapshotId,
+      provider: 'snapshot-localfs',
+      status: 'ready',
+      createdAt: now,
+      updatedAt: now,
+      workspaceId: request.workspaceId,
+      environmentId: request.environmentId,
+      metadata: {
+        namespace,
+        payloadPath,
+      },
+    };
+  }
+
+  async restore(request: RestoreSnapshotRequest): Promise<RestoreSnapshotResult> {
+    const record = await this.getRecordOrThrow(request.snapshotId);
+    const now = new Date().toISOString();
+
+    const targetPath = request.targetPath
+      ? path.resolve(this.cwd, request.targetPath)
+      : await this.resolveRestoreTargetPath(request.workspaceId, record.workspaceId);
+
+    if (!request.overwrite) {
+      try {
+        await access(targetPath);
+        throw new Error(`Restore target already exists: ${targetPath}. Use overwrite=true.`);
+      } catch (error) {
+        if (error instanceof Error && error.message.startsWith('Restore target already exists')) {
+          throw error;
+        }
+        // path missing, continue
+      }
+    }
+
+    if (request.overwrite) {
+      await rm(targetPath, { recursive: true, force: true });
+    }
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await cp(record.payloadPath, targetPath, { recursive: true, force: true });
+
+    record.status = 'ready';
+    record.updatedAt = now;
+    await this.persistRecord(record);
+
+    return {
+      snapshotId: request.snapshotId,
+      restoredAt: now,
+      workspaceId: request.workspaceId,
+      environmentId: request.environmentId,
+      targetPath,
+    };
+  }
+
+  async getStatus(snapshotId: string): Promise<SnapshotStatusResult> {
+    const record = await this.getRecordOrThrow(snapshotId);
+    return {
+      snapshotId,
+      status: record.status,
+      updatedAt: record.updatedAt,
+    };
+  }
+
+  async delete(snapshotId: string): Promise<void> {
+    const record = await this.getRecordOrThrow(snapshotId);
+    await rm(record.payloadPath, { recursive: true, force: true });
+    this.records.delete(snapshotId);
+    await rm(this.getRecordPath(snapshotId), { force: true });
+  }
+
+  async garbageCollect(
+    request: SnapshotGarbageCollectRequest = {}
+  ): Promise<SnapshotGarbageCollectResult> {
+    const beforeTs = request.before ? new Date(request.before).getTime() : Number.POSITIVE_INFINITY;
+    const limit = request.limit ?? Number.POSITIVE_INFINITY;
+    const dryRun = request.dryRun ?? false;
+    let scanned = 0;
+    let deleted = 0;
+
+    for (const record of await this.loadAllRecords()) {
+      scanned += 1;
+      const createdTs = new Date(record.createdAt).getTime();
+      if (createdTs >= beforeTs) {
+        continue;
+      }
+      if (request.namespace && record.namespace !== request.namespace) {
+        continue;
+      }
+      if (deleted >= limit) {
+        break;
+      }
+
+      if (!dryRun) {
+        await this.delete(record.snapshotId);
+      }
+      deleted += 1;
+    }
+
+    return { scanned, deleted, dryRun };
+  }
+
+  getCapabilities(): SnapshotProviderCapabilities {
+    return {
+      supportsWorkspaceSnapshots: true,
+      supportsEnvironmentSnapshots: false,
+      supportsGarbageCollection: true,
+      supportsIncrementalSnapshots: false,
+      custom: {
+        provider: 'localfs',
+      },
+    };
+  }
+
+  private async resolveSourcePath(request: CaptureSnapshotRequest): Promise<string> {
+    if (request.sourcePath) {
+      return path.resolve(this.cwd, request.sourcePath);
+    }
+
+    if (request.workspaceId) {
+      const workspace = await this.readWorkspaceRecord(request.workspaceId);
+      if (workspace.rootPath) {
+        return workspace.rootPath;
+      }
+    }
+
+    throw new Error('Snapshot capture requires sourcePath or resolvable workspaceId');
+  }
+
+  private async resolveRestoreTargetPath(
+    requestedWorkspaceId?: string,
+    recordWorkspaceId?: string
+  ): Promise<string> {
+    const workspaceId = requestedWorkspaceId ?? recordWorkspaceId;
+    if (!workspaceId) {
+      throw new Error('Snapshot restore requires targetPath or workspaceId');
+    }
+    const workspace = await this.readWorkspaceRecord(workspaceId);
+    if (!workspace.rootPath) {
+      throw new Error(`Workspace rootPath not found for workspaceId=${workspaceId}`);
+    }
+    return workspace.rootPath;
+  }
+
+  private getRecordPath(snapshotId: string): string {
+    return path.join(this.storageDir, '.records', `${snapshotId}.json`);
+  }
+
+  private async persistRecord(record: SnapshotRecord): Promise<void> {
+    this.records.set(record.snapshotId, record);
+    const recordPath = this.getRecordPath(record.snapshotId);
+    await mkdir(path.dirname(recordPath), { recursive: true });
+    await writeFile(recordPath, JSON.stringify(record, null, 2), 'utf8');
+  }
+
+  private async getRecordOrThrow(snapshotId: string): Promise<SnapshotRecord> {
+    const inMemory = this.records.get(snapshotId);
+    if (inMemory) {
+      return inMemory;
+    }
+
+    const recordPath = this.getRecordPath(snapshotId);
+    try {
+      const raw = await readFile(recordPath, 'utf8');
+      const parsed = JSON.parse(raw) as SnapshotRecord;
+      this.records.set(snapshotId, parsed);
+      return parsed;
+    } catch {
+      throw new Error(`Snapshot not found: ${snapshotId}`);
+    }
+  }
+
+  private async readWorkspaceRecord(workspaceId: string): Promise<WorkspaceRecord> {
+    const filePath = path.join(this.workspaceRegistryDir, `${workspaceId}.json`);
+    const raw = await readFile(filePath, 'utf8');
+    return JSON.parse(raw) as WorkspaceRecord;
+  }
+
+  private async loadAllRecords(): Promise<SnapshotRecord[]> {
+    const recordsDir = path.join(this.storageDir, '.records');
+    try {
+      const entries = await readdir(recordsDir);
+      const loaded: SnapshotRecord[] = [];
+      for (const entry of entries) {
+        if (!entry.endsWith('.json')) {
+          continue;
+        }
+        const filePath = path.join(recordsDir, entry);
+        const fileStat = await stat(filePath);
+        if (!fileStat.isFile()) {
+          continue;
+        }
+        const raw = await readFile(filePath, 'utf8');
+        loaded.push(JSON.parse(raw) as SnapshotRecord);
+      }
+      return loaded;
+    } catch {
+      return [];
+    }
+  }
+}
+
+export function createAdapter(config?: LocalFsSnapshotAdapterConfig): LocalFsSnapshotAdapter {
+  return new LocalFsSnapshotAdapter(config);
+}
+
+export default createAdapter;

package/packages/adapters-snapshot-localfs/src/manifest.ts

@@ -0,0 +1,32 @@
+import type { AdapterManifest } from '@kb-labs/core-platform';
+
+export const manifest: AdapterManifest = {
+  manifestVersion: '1.0.0',
+  id: 'localfs-snapshot-provider',
+  name: 'LocalFS Snapshot Provider',
+  version: '0.1.0',
+  description: 'Snapshot provider on local filesystem',
+  author: 'KB Labs Team',
+  license: 'KBPL-1.1',
+  type: 'core',
+  implements: 'ISnapshotProvider',
+  contexts: ['workspace'],
+  capabilities: {
+    custom: {
+      provider: 'localfs',
+      workspaceRegistry: true,
+    },
+  },
+  configSchema: {
+    storageDir: {
+      type: 'string',
+      default: '.kb/runtime/snapshots',
+      description: 'Root directory where snapshots are stored',
+    },
+    workspaceRegistryDir: {
+      type: 'string',
+      default: '.kb/runtime/workspace-registry',
+      description: 'Directory with workspace metadata for source path resolution',
+    },
+  },
+};

package/packages/adapters-snapshot-localfs/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/packages/adapters-snapshot-localfs/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@kb-labs/core-platform": [
+        "../../../kb-labs-core/packages/core-platform/src/index.ts"
+      ],
+      "@kb-labs/core-platform/*": [
+        "../../../kb-labs-core/packages/core-platform/src/*"
+      ]
+    }
+  },
+  "include": ["src"]
+}

package/packages/adapters-snapshot-localfs/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts', 'src/manifest.ts'],
+  format: ['esm'],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  target: 'es2022',
+  external: [/^@kb-labs\/.*/],
+});

package/packages/adapters-sqlite/README.md

@@ -0,0 +1,163 @@
+# @kb-labs/adapters-sqlite
+
+> Part of [KB Labs](https://github.com/KirillBaranov/kb-labs) ecosystem. Works exclusively within KB Labs platform.
+
+Lightweight embedded SQL database adapter using better-sqlite3 with FTS, JSON, and transaction support.
+
+## Overview
+
+| Property | Value |
+|----------|-------|
+| **Implements** | `ISQLDatabase` |
+| **Type** | `core` |
+| **Requires** | None |
+| **Category** | Database |
+
+## Features
+
+- **Embedded Database** - No external server required
+- **Full-Text Search** - FTS5 for fast text search
+- **JSON Support** - Store and query JSON fields
+- **Prepared Statements** - Optimized query execution
+- **Transaction Support** - ACID-compliant operations
+
+## Installation
+
+```bash
+pnpm add @kb-labs/adapters-sqlite
+```
+
+## Configuration
+
+Add to your `kb.config.json`:
+
+```json
+{
+  "platform": {
+    "adapters": {
+      "db": "@kb-labs/adapters-sqlite"
+    },
+    "adapterOptions": {
+      "db": {
+        "filename": ".kb/data/kb.db",
+        "readonly": false,
+        "timeout": 5000
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `filename` | `string` | - | Database file path (`:memory:` for in-memory) |
+| `readonly` | `boolean` | `false` | Open in readonly mode |
+| `timeout` | `number` | `5000` | Busy timeout in milliseconds |
+
+## Usage
+
+### Via Platform (Recommended)
+
+```typescript
+import { usePlatform } from '@kb-labs/sdk';
+
+const platform = usePlatform();
+
+// Execute query
+const users = platform.db.query<User>('SELECT * FROM users WHERE active = ?', [true]);
+
+// Insert
+platform.db.run('INSERT INTO users (name, email) VALUES (?, ?)', ['John', 'john@example.com']);
+
+// Transaction
+platform.db.transaction(() => {
+  platform.db.run('UPDATE accounts SET balance = balance - 100 WHERE id = ?', [1]);
+  platform.db.run('UPDATE accounts SET balance = balance + 100 WHERE id = ?', [2]);
+});
+```
+
+### Standalone (Testing/Development)
+
+```typescript
+import { createAdapter } from '@kb-labs/adapters-sqlite';
+
+const db = createAdapter({ filename: ':memory:' });
+
+db.run('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+db.run('INSERT INTO users (name) VALUES (?)', ['John']);
+
+const users = db.query('SELECT * FROM users');
+```
+
+## Adapter Manifest
+
+```typescript
+{
+  id: 'sqlite-database',
+  name: 'SQLite Database',
+  version: '1.0.0',
+  implements: 'ISQLDatabase',
+  capabilities: {
+    transactions: true,
+    search: true,
+    custom: {
+      prepared: true,
+      fts: true,
+      json: true,
+    },
+  },
+}
+```
+
+## FAQ
+
+<details>
+<summary><strong>Q: How do I use in-memory database?</strong></summary>
+
+Set filename to `:memory:`:
+
+```json
+{
+  "adapterOptions": {
+    "db": {
+      "filename": ":memory:"
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Q: How do I enable WAL mode for better concurrency?</strong></summary>
+
+Run pragma after initialization:
+
+```typescript
+db.run('PRAGMA journal_mode = WAL');
+```
+</details>
+
+<details>
+<summary><strong>Q: How do I use full-text search?</strong></summary>
+
+Create FTS5 virtual table:
+
+```typescript
+db.run('CREATE VIRTUAL TABLE docs_fts USING fts5(content)');
+db.run("INSERT INTO docs_fts VALUES ('hello world')");
+const results = db.query("SELECT * FROM docs_fts WHERE docs_fts MATCH 'hello'");
+```
+</details>
+
+## Related Adapters
+
+| Adapter | Use Case |
+|---------|----------|
+| `@kb-labs/adapters-log-sqlite` | Log persistence using SQLite |
+| `@kb-labs/adapters-mongodb` | Document database for complex data |
+
+## License
+
+[KB Public License v1.1](../../LICENSE) - KB Labs Team

package/packages/adapters-sqlite/eslint.config.js

@@ -0,0 +1,27 @@
+/**
+ * Standard ESLint configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - DevKit preset already includes all standard ignores
+ * - Only add project-specific ignores if absolutely necessary
+ * - Document why custom ignores are needed
+ *
+ * @see https://github.com/kb-labs/devkit#eslint-configuration
+ */
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [
+  ...nodePreset,
+
+  // OPTIONAL: Add project-specific ignores only if needed
+  // DevKit preset already ignores: dist/, coverage/, node_modules/, *.d.ts, scripts/, etc.
+  // {
+  //   ignores: [
+  //     // Add ONLY project-specific patterns here
+  //     // Example: '**/*.generated.ts',
+  //   ]
+  // }
+];