@kb-labs/adapters 0.5.0

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

@@ -0,0 +1,172 @@
+import { mkdir, access, writeFile, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type {
+  IWorkspaceProvider,
+  MaterializeWorkspaceRequest,
+  WorkspaceDescriptor,
+  AttachWorkspaceRequest,
+  WorkspaceAttachment,
+  WorkspaceStatusResult,
+  WorkspaceProviderCapabilities,
+  WorkspaceStatus,
+} from '@kb-labs/core-platform';
+
+export { manifest } from './manifest.js';
+
+interface WorkspaceContext {
+  cwd?: string;
+}
+
+export interface LocalFsWorkspaceAdapterConfig {
+  rootDir?: string;
+  registryDir?: string;
+  workspace?: WorkspaceContext;
+}
+
+interface WorkspaceRecord {
+  workspaceId: string;
+  rootPath?: string;
+  status: WorkspaceStatus;
+  updatedAt: string;
+}
+
+function isFileSourceRef(sourceRef?: string): string | undefined {
+  if (!sourceRef) {
+    return undefined;
+  }
+  if (sourceRef.startsWith('file://')) {
+    return sourceRef.slice('file://'.length);
+  }
+  if (sourceRef.startsWith('/') || sourceRef.startsWith('./') || sourceRef.startsWith('../')) {
+    return sourceRef;
+  }
+  return undefined;
+}
+
+export class LocalFsWorkspaceAdapter implements IWorkspaceProvider {
+  private readonly workspaceRoot: string;
+  private readonly registryDir: string;
+  private readonly workspaceCwd: string;
+  private readonly records = new Map<string, WorkspaceRecord>();
+
+  constructor(private readonly config: LocalFsWorkspaceAdapterConfig = {}) {
+    this.workspaceCwd = path.resolve(config.workspace?.cwd ?? process.cwd());
+    this.workspaceRoot = path.resolve(this.workspaceCwd, config.rootDir ?? '.kb/runtime/workspaces');
+    this.registryDir = path.resolve(this.workspaceCwd, config.registryDir ?? '.kb/runtime/workspace-registry');
+  }
+
+  async materialize(request: MaterializeWorkspaceRequest): Promise<WorkspaceDescriptor> {
+    const workspaceId = request.workspaceId ?? `ws_${randomUUID()}`;
+    const now = new Date().toISOString();
+
+    const explicitPath = request.basePath ? path.resolve(this.workspaceCwd, request.basePath) : undefined;
+    const sourcePath = isFileSourceRef(request.sourceRef)
+      ? path.resolve(this.workspaceCwd, isFileSourceRef(request.sourceRef) as string)
+      : undefined;
+
+    const rootPath = explicitPath ?? sourcePath ?? path.join(this.workspaceRoot, workspaceId);
+
+    await mkdir(rootPath, { recursive: true });
+
+    const descriptor: WorkspaceDescriptor = {
+      workspaceId,
+      provider: 'workspace-localfs',
+      status: 'ready',
+      rootPath,
+      createdAt: now,
+      updatedAt: now,
+      metadata: {
+        sourceRef: request.sourceRef,
+      },
+    };
+
+    await this.persistRecord({
+      workspaceId,
+      rootPath,
+      status: descriptor.status,
+      updatedAt: now,
+    });
+
+    return descriptor;
+  }
+
+  async attach(request: AttachWorkspaceRequest): Promise<WorkspaceAttachment> {
+    const now = new Date().toISOString();
+    const record = await this.getRecordOrThrow(request.workspaceId);
+
+    record.status = 'attached';
+    record.updatedAt = now;
+    await this.persistRecord(record);
+
+    return {
+      workspaceId: request.workspaceId,
+      environmentId: request.environmentId,
+      mountPath: request.mountPath ?? '/workspace',
+      attachedAt: now,
+      metadata: {
+        rootPath: record.rootPath,
+        readOnly: request.readOnly ?? false,
+      },
+    };
+  }
+
+  async release(workspaceId: string): Promise<void> {
+    const now = new Date().toISOString();
+    const record = await this.getRecordOrThrow(workspaceId);
+    record.status = 'released';
+    record.updatedAt = now;
+    await this.persistRecord(record);
+  }
+
+  async getStatus(workspaceId: string): Promise<WorkspaceStatusResult> {
+    const record = await this.getRecordOrThrow(workspaceId);
+    return {
+      workspaceId,
+      status: record.status,
+      updatedAt: record.updatedAt,
+    };
+  }
+
+  getCapabilities(): WorkspaceProviderCapabilities {
+    return {
+      supportsAttach: true,
+      supportsRelease: true,
+      supportsReadOnlyMounts: true,
+      custom: {
+        provider: 'localfs',
+      },
+    };
+  }
+
+  private async persistRecord(record: WorkspaceRecord): Promise<void> {
+    this.records.set(record.workspaceId, record);
+    await mkdir(this.registryDir, { recursive: true });
+    const filePath = path.join(this.registryDir, `${record.workspaceId}.json`);
+    await writeFile(filePath, JSON.stringify(record, null, 2), 'utf8');
+  }
+
+  private async getRecordOrThrow(workspaceId: string): Promise<WorkspaceRecord> {
+    const inMemory = this.records.get(workspaceId);
+    if (inMemory) {
+      return inMemory;
+    }
+
+    const filePath = path.join(this.registryDir, `${workspaceId}.json`);
+    try {
+      await access(filePath);
+      const raw = await readFile(filePath, 'utf8');
+      const parsed = JSON.parse(raw) as WorkspaceRecord;
+      this.records.set(workspaceId, parsed);
+      return parsed;
+    } catch {
+      throw new Error(`Workspace not found: ${workspaceId}`);
+    }
+  }
+}
+
+export function createAdapter(config?: LocalFsWorkspaceAdapterConfig): LocalFsWorkspaceAdapter {
+  return new LocalFsWorkspaceAdapter(config);
+}
+
+export default createAdapter;

package/packages/adapters-workspace-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-workspace-provider',
+  name: 'LocalFS Workspace Provider',
+  version: '0.1.0',
+  description: 'Workspace provider on local filesystem',
+  author: 'KB Labs Team',
+  license: 'KBPL-1.1',
+  type: 'core',
+  implements: 'IWorkspaceProvider',
+  contexts: ['workspace'],
+  capabilities: {
+    custom: {
+      provider: 'localfs',
+      workspaceRegistry: true,
+    },
+  },
+  configSchema: {
+    rootDir: {
+      type: 'string',
+      default: '.kb/runtime/workspaces',
+      description: 'Root directory where managed workspaces are created',
+    },
+    registryDir: {
+      type: 'string',
+      default: '.kb/runtime/workspace-registry',
+      description: 'Directory with workspace metadata for cross-adapter lookup',
+    },
+  },
+};

package/packages/adapters-workspace-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-workspace-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-workspace-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-workspace-worktree/README.md

@@ -0,0 +1,9 @@
+# @kb-labs/adapters-workspace-localfs
+
+Local filesystem implementation of `IWorkspaceProvider`.
+
+## Features
+
+- Materialize workspace from existing path or create dedicated directory
+- Attach/release status for environment mount lifecycle
+- Workspace registry persisted for integration with snapshot adapters

package/packages/adapters-workspace-worktree/eslint.config.js

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

package/packages/adapters-workspace-worktree/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kb-labs/adapters-workspace-worktree",
+  "version": "0.5.0",
+  "description": "Git worktree adapter implementing IWorkspaceProvider for isolated execution",
+  "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-workspace-worktree/src/index.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { WorktreeWorkspaceAdapter } from './index.js';
+
+describe('WorktreeWorkspaceAdapter', () => {
+  it('should export createAdapter factory', async () => {
+    const { createAdapter } = await import('./index.js');
+    expect(typeof createAdapter).toBe('function');
+  });
+
+  it('should create adapter with default config', () => {
+    const adapter = new WorktreeWorkspaceAdapter();
+    expect(adapter).toBeDefined();
+    expect(typeof adapter.materialize).toBe('function');
+    expect(typeof adapter.release).toBe('function');
+    expect(typeof adapter.getStatus).toBe('function');
+    expect(typeof adapter.getCapabilities).toBe('function');
+  });
+
+  it('should return capabilities', () => {
+    const adapter = new WorktreeWorkspaceAdapter();
+    const caps = adapter.getCapabilities();
+    expect(caps.supportsAttach).toBe(true);
+    expect(caps.supportsRelease).toBe(true);
+  });
+
+  it('should return released status for unknown workspace', async () => {
+    const adapter = new WorktreeWorkspaceAdapter();
+    const status = await adapter.getStatus('nonexistent');
+    expect(status.status).toBe('released');
+  });
+
+  it('should reject invalid branch names', async () => {
+    const adapter = new WorktreeWorkspaceAdapter();
+    await expect(
+      adapter.materialize({ sourceRef: 'main; rm -rf /' })
+    ).rejects.toThrow('Invalid branch name');
+  });
+});

package/packages/adapters-workspace-worktree/src/index.ts

@@ -0,0 +1,245 @@
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type {
+  IWorkspaceProvider,
+  MaterializeWorkspaceRequest,
+  WorkspaceDescriptor,
+  AttachWorkspaceRequest,
+  WorkspaceAttachment,
+  WorkspaceStatusResult,
+  WorkspaceProviderCapabilities,
+  WorkspaceStatus,
+} from '@kb-labs/core-platform';
+
+export { manifest } from './manifest.js';
+
+interface WorkspaceContext {
+  cwd?: string;
+}
+
+export interface WorktreeWorkspaceAdapterConfig {
+  worktreeDir?: string;
+  branch?: string;
+  initSubmodules?: boolean;
+  installDeps?: boolean;
+  workspace?: WorkspaceContext;
+}
+
+interface WorktreeRecord {
+  workspaceId: string;
+  worktreePath: string;
+  branch: string;
+  status: WorkspaceStatus;
+  createdAt: string;
+  runId?: string;
+}
+
+const TIMEOUTS = {
+  worktree: 30_000,
+  submodules: 600_000,
+  install: 300_000,
+  cleanup: 30_000,
+} as const;
+
+export class WorktreeWorkspaceAdapter implements IWorkspaceProvider {
+  private readonly repoRoot: string;
+  private readonly worktreeBaseDir: string;
+  private readonly defaultBranch: string;
+  private readonly initSubmodules: boolean;
+  private readonly installDeps: boolean;
+  private readonly records = new Map<string, WorktreeRecord>();
+
+  constructor(config: WorktreeWorkspaceAdapterConfig = {}) {
+    this.repoRoot = path.resolve(config.workspace?.cwd ?? process.cwd());
+    this.worktreeBaseDir = path.resolve(this.repoRoot, config.worktreeDir ?? '.worktrees');
+    this.defaultBranch = config.branch ?? 'main';
+    this.initSubmodules = config.initSubmodules ?? true;
+    this.installDeps = config.installDeps ?? true;
+  }
+
+  async materialize(request: MaterializeWorkspaceRequest): Promise<WorkspaceDescriptor> {
+    const workspaceId = request.workspaceId ?? `wt_${randomUUID().slice(0, 8)}`;
+    const branch = request.sourceRef ?? this.defaultBranch;
+    const runId = (request.metadata as Record<string, unknown>)?.runId as string | undefined;
+    const onProgress = request.onProgress;
+
+    if (!existsSync(this.worktreeBaseDir)) {
+      mkdirSync(this.worktreeBaseDir, { recursive: true });
+    }
+
+    const worktreePath = path.join(this.worktreeBaseDir, workspaceId);
+
+    // Reuse existing worktree (retry scenario — same run, same workspace)
+    if (existsSync(worktreePath)) {
+      const existing = this.records.get(workspaceId);
+      if (existing) {
+        onProgress?.({ stage: 'reuse', message: 'Reusing existing worktree', progress: 100 });
+        return {
+          workspaceId,
+          provider: 'worktree',
+          status: 'ready',
+          rootPath: worktreePath,
+          createdAt: existing.createdAt,
+          updatedAt: new Date().toISOString(),
+          metadata: { branch, runId, repoRoot: this.repoRoot, reused: true },
+        };
+      }
+      // Worktree exists on disk but not in records (stale) — reuse anyway
+      onProgress?.({ stage: 'reuse', message: 'Reusing existing worktree (recovered)', progress: 100 });
+      const now = new Date().toISOString();
+      this.records.set(workspaceId, { workspaceId, worktreePath, branch, status: 'ready', createdAt: now, runId });
+      return {
+        workspaceId,
+        provider: 'worktree',
+        status: 'ready',
+        rootPath: worktreePath,
+        createdAt: now,
+        updatedAt: now,
+        metadata: { branch, runId, repoRoot: this.repoRoot, reused: true },
+      };
+    }
+
+    const safeBranch = branch.replace(/[^a-zA-Z0-9_\-./]/g, '');
+    if (!safeBranch || safeBranch !== branch) {
+      throw new Error(`Invalid branch name: ${branch}`);
+    }
+
+    const progress = (stage: string, message: string, pct?: number) => {
+      onProgress?.({ stage, message, progress: pct });
+    };
+
+    try {
+      // Stage 1: Create worktree
+      progress('worktree', `Creating worktree from ${safeBranch}...`, 10);
+      this.exec(
+        `git worktree add --detach "${worktreePath}" ${safeBranch}`,
+        this.repoRoot,
+        TIMEOUTS.worktree,
+      );
+      progress('worktree', 'Worktree created', 25);
+
+      // Stage 2: Initialize submodules
+      if (this.initSubmodules) {
+        progress('submodules', 'Initializing submodules...', 30);
+        this.exec(
+          'git submodule update --recursive',
+          worktreePath,
+          TIMEOUTS.submodules,
+        );
+        progress('submodules', 'Submodules ready', 60);
+      }
+
+      // Stage 3: Install dependencies
+      if (this.installDeps) {
+        progress('dependencies', 'Installing dependencies (pnpm install)...', 65);
+        this.exec(
+          'pnpm install --frozen-lockfile',
+          worktreePath,
+          TIMEOUTS.install,
+        );
+        progress('dependencies', 'Dependencies installed', 95);
+      }
+
+      progress('ready', 'Workspace ready', 100);
+
+      const record: WorktreeRecord = {
+        workspaceId,
+        worktreePath,
+        branch,
+        status: 'ready',
+        createdAt: new Date().toISOString(),
+        runId,
+      };
+      this.records.set(workspaceId, record);
+
+      return {
+        workspaceId,
+        provider: 'worktree',
+        status: 'ready',
+        rootPath: worktreePath,
+        createdAt: record.createdAt,
+        updatedAt: record.createdAt,
+        metadata: { branch, runId, repoRoot: this.repoRoot },
+      };
+    } catch (error) {
+      progress('failed', `Provisioning failed: ${error instanceof Error ? error.message : String(error)}`);
+
+      try {
+        this.exec(`git worktree remove "${worktreePath}" --force`, this.repoRoot, TIMEOUTS.cleanup);
+      } catch { /* ignore cleanup errors */ }
+
+      throw new Error(
+        `Failed to provision workspace: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  async attach(_request: AttachWorkspaceRequest): Promise<WorkspaceAttachment> {
+    return {
+      workspaceId: _request.workspaceId,
+      environmentId: _request.environmentId,
+      mountPath: this.records.get(_request.workspaceId)?.worktreePath,
+      attachedAt: new Date().toISOString(),
+    };
+  }
+
+  async release(workspaceId: string): Promise<void> {
+    const record = this.records.get(workspaceId);
+    if (!record) {
+      return;
+    }
+
+    try {
+      this.exec(`git worktree remove "${record.worktreePath}" --force`, this.repoRoot, TIMEOUTS.cleanup);
+    } catch {
+      if (existsSync(record.worktreePath)) {
+        rmSync(record.worktreePath, { recursive: true, force: true });
+      }
+      try {
+        this.exec('git worktree prune', this.repoRoot, TIMEOUTS.cleanup);
+      } catch { /* ignore */ }
+    }
+
+    record.status = 'released';
+    this.records.delete(workspaceId);
+  }
+
+  async getStatus(workspaceId: string): Promise<WorkspaceStatusResult> {
+    const record = this.records.get(workspaceId);
+    if (!record) {
+      return { workspaceId, status: 'released', updatedAt: new Date().toISOString() };
+    }
+
+    const exists = existsSync(record.worktreePath);
+    return {
+      workspaceId,
+      status: exists ? record.status : 'failed',
+      updatedAt: record.createdAt,
+    };
+  }
+
+  getCapabilities(): WorkspaceProviderCapabilities {
+    return {
+      supportsAttach: true,
+      supportsRelease: true,
+    };
+  }
+
+  private exec(command: string, cwd: string, timeout = 60_000): string {
+    return execSync(command, {
+      cwd,
+      encoding: 'utf8',
+      timeout,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  }
+}
+
+/**
+ * Adapter factory — called by platform adapter loader.
+ */
+export function createAdapter(config: WorktreeWorkspaceAdapterConfig = {}): WorktreeWorkspaceAdapter {
+  return new WorktreeWorkspaceAdapter(config);
+}

package/packages/adapters-workspace-worktree/src/manifest.ts

@@ -0,0 +1,38 @@
+import type { AdapterManifest } from '@kb-labs/core-platform';
+
+export const manifest: AdapterManifest = {
+  manifestVersion: '1.0.0',
+  id: 'worktree-workspace-provider',
+  name: 'Git Worktree Workspace Provider',
+  version: '0.1.0',
+  description: 'Creates isolated git worktrees for pipeline execution',
+  author: 'KB Labs Team',
+  license: 'KBPL-1.1',
+  type: 'core',
+  implements: 'IWorkspaceProvider',
+  contexts: ['workspace'],
+  capabilities: {
+    custom: {
+      provider: 'worktree',
+      isolation: true,
+      gitSubmodules: true,
+    },
+  },
+  configSchema: {
+    worktreeDir: {
+      type: 'string',
+      default: '.worktrees',
+      description: 'Directory where worktrees are created (relative to repo root)',
+    },
+    branch: {
+      type: 'string',
+      default: 'main',
+      description: 'Default branch to create worktrees from',
+    },
+    initSubmodules: {
+      type: 'boolean',
+      default: true,
+      description: 'Initialize git submodules in worktree',
+    },
+  },
+};

package/packages/adapters-workspace-worktree/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-workspace-worktree/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": [
+        "../../../../platform/kb-labs-core/packages/core-platform/src/index.ts"
+      ],
+      "@kb-labs/core-platform/*": [
+        "../../../../platform/kb-labs-core/packages/core-platform/src/*"
+      ]
+    }
+  },
+  "include": ["src"]
+}

package/packages/adapters-workspace-worktree/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\/.*/],
+});