@kb-labs/shared 1.1.0

package/packages/shared-testing/src/setup-platform.ts

@@ -0,0 +1,101 @@
+/**
+ * @module @kb-labs/shared-testing/setup-platform
+ *
+ * Solves the "singleton gap" problem: composables (useLLM, useCache, etc.)
+ * read from the global platform singleton, but createTestContext() only
+ * populates ctx.platform. This module bridges the gap by setting test mocks
+ * directly into the global singleton.
+ */
+
+import { platform, resetPlatform } from '@kb-labs/core-runtime';
+import type {
+  ILLM,
+  ICache,
+  IEmbeddings,
+  IVectorStore,
+  IStorage,
+  IAnalytics,
+  ILogger,
+  IEventBus,
+} from '@kb-labs/core-platform';
+
+/**
+ * Options for setting up the test platform.
+ * Only adapters that are provided will be registered.
+ * Omitted adapters will use the PlatformContainer's built-in fallbacks.
+ */
+export interface TestPlatformOptions {
+  llm?: ILLM;
+  cache?: ICache;
+  embeddings?: IEmbeddings;
+  vectorStore?: IVectorStore;
+  storage?: IStorage;
+  analytics?: IAnalytics;
+  logger?: ILogger;
+  eventBus?: IEventBus;
+}
+
+export interface TestPlatformResult {
+  /** The global platform singleton (with test mocks applied) */
+  platform: typeof platform;
+  /** Call in afterEach() to reset the singleton to a clean state */
+  cleanup: () => void;
+}
+
+/**
+ * Setup the global platform singleton with test mocks.
+ *
+ * This ensures that useLLM(), useCache() and other composables
+ * return the test mocks instead of uninitialized/stale adapters.
+ *
+ * @example
+ * ```typescript
+ * import { setupTestPlatform, mockLLM } from '@kb-labs/shared-testing';
+ *
+ * describe('my handler', () => {
+ *   let cleanup: () => void;
+ *
+ *   beforeEach(() => {
+ *     const result = setupTestPlatform({
+ *       llm: mockLLM().onAnyComplete().respondWith('hello'),
+ *     });
+ *     cleanup = result.cleanup;
+ *   });
+ *
+ *   afterEach(() => cleanup());
+ *
+ *   it('uses LLM', async () => {
+ *     const llm = useLLM(); // Returns the test mock!
+ *     const res = await llm!.complete('test');
+ *     expect(res.content).toBe('hello');
+ *   });
+ * });
+ * ```
+ */
+export function setupTestPlatform(options: TestPlatformOptions = {}): TestPlatformResult {
+  // Reset everything first — clean slate
+  resetPlatform();
+
+  // Register provided adapters into the global singleton
+  const adapterMap: Array<[string, unknown]> = [
+    ['llm', options.llm],
+    ['cache', options.cache],
+    ['embeddings', options.embeddings],
+    ['vectorStore', options.vectorStore],
+    ['storage', options.storage],
+    ['analytics', options.analytics],
+    ['logger', options.logger],
+    ['eventBus', options.eventBus],
+  ];
+
+  for (const [key, instance] of adapterMap) {
+    if (instance !== undefined) {
+      platform.setAdapter(key, instance);
+    }
+  }
+
+  return {
+    platform,
+    cleanup: () => resetPlatform(),
+  };
+}

package/packages/shared-testing/src/test-command.ts

@@ -0,0 +1,288 @@
+/**
+ * @module @kb-labs/shared-testing/test-command
+ *
+ * Single-function test runner for plugin command handlers.
+ *
+ * Eliminates boilerplate: no manual context creation, no descriptor setup,
+ * no mock wiring. Import your handler, call testCommand(), assert on result.
+ *
+ * @example
+ * ```typescript
+ * import { testCommand, mockLLM } from '@kb-labs/shared-testing';
+ * import handler from '../src/commands/greet.js';
+ *
+ * it('greets the user', async () => {
+ *   const result = await testCommand(handler, {
+ *     flags: { name: 'Alice' },
+ *   });
+ *
+ *   expect(result.exitCode).toBe(0);
+ *   expect(result.result).toEqual({ message: 'Hello, Alice!' });
+ *   expect(result.ui.success).toHaveBeenCalledWith('Hello, Alice!');
+ * });
+ * ```
+ */
+
+import type {
+  PluginContextV3,
+  CommandResult,
+  UIFacade,
+  PlatformServices,
+} from '@kb-labs/plugin-contracts';
+
+import {
+  createTestContext,
+  type CreateTestContextOptions,
+} from './create-test-context.js';
+
+// ────────────────────────────────────────────────────────────────────
+// Types
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Any handler that has an execute(ctx, input) method.
+ * Covers CommandHandlerV3, RouteHandler, Handler, and raw objects.
+ */
+export interface TestableHandler<TConfig = unknown, TInput = unknown, TResult = unknown> {
+  execute(
+    context: PluginContextV3<TConfig>,
+    input: TInput
+  ): Promise<TResult> | TResult;
+  cleanup?(): Promise<void> | void;
+}
+
+/**
+ * Options for testCommand().
+ *
+ * Provide only what you need — everything else gets sensible defaults.
+ */
+export interface TestCommandOptions<TConfig = unknown> {
+  // ── Input ──────────────────────────────────────────────────────
+
+  /** CLI flags (sugar for input: { flags, argv }) */
+  flags?: Record<string, unknown>;
+
+  /** CLI positional arguments (default: []) */
+  argv?: string[];
+
+  /** REST query params (sugar for input: { query }) */
+  query?: Record<string, unknown>;
+
+  /** REST request body (sugar for input: { body }) */
+  body?: unknown;
+
+  /** REST route params (sugar for input: { params }) */
+  params?: Record<string, unknown>;
+
+  /**
+   * Raw input object. If provided, flags/argv/query/body/params are ignored.
+   * Use this when your handler expects a custom input shape.
+   */
+  input?: unknown;
+
+  // ── Context ────────────────────────────────────────────────────
+
+  /** Host type (default: 'cli') */
+  host?: 'cli' | 'rest' | 'workflow' | 'webhook';
+
+  /** Plugin config passed as ctx.config */
+  config?: TConfig;
+
+  /** Working directory (default: process.cwd()) */
+  cwd?: string;
+
+  /** Tenant ID */
+  tenantId?: string;
+
+  /** Abort signal */
+  signal?: AbortSignal;
+
+  // ── Mocks ──────────────────────────────────────────────────────
+
+  /** Override platform services (e.g., { llm: mockLLM().onAnyComplete().respondWith('ok') }) */
+  platform?: Partial<PlatformServices>;
+
+  /** Override UI facade (individual methods are merged with default spy UI) */
+  ui?: Partial<UIFacade>;
+
+  /**
+   * Sync platform mocks to global singleton for composables (useLLM, useCache, etc.)
+   * @default true
+   */
+  syncSingleton?: boolean;
+}
+
+/**
+ * Result of testCommand() — everything you need for assertions.
+ */
+export interface TestCommandResult<TResult = unknown> {
+  /** Exit code from CommandResult (0 = success). Defaults to 0 if handler returns raw data. */
+  exitCode: number;
+
+  /** The result data from the handler */
+  result: TResult | undefined;
+
+  /** Custom metadata from CommandResult.meta */
+  meta: Record<string, unknown> | undefined;
+
+  /** The raw return value from handler.execute() — useful for non-CommandResult handlers */
+  raw: unknown;
+
+  /** UI facade with vi.fn() spies — assert on ui.success, ui.error, etc. */
+  ui: UIFacade;
+
+  /** The full context that was passed to the handler */
+  ctx: PluginContextV3;
+
+  /** Call in afterEach() to reset the global platform singleton */
+  cleanup: () => void;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Implementation
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Test a plugin command handler with minimal boilerplate.
+ *
+ * Creates a test context, builds the input object, calls handler.execute(),
+ * and returns a result with UI spies for assertions.
+ *
+ * @example CLI command
+ * ```typescript
+ * import handler from '../src/commands/greet.js';
+ *
+ * const result = await testCommand(handler, {
+ *   flags: { name: 'Alice' },
+ * });
+ * expect(result.exitCode).toBe(0);
+ * expect(result.ui.success).toHaveBeenCalledWith('Hello, Alice!');
+ * ```
+ *
+ * @example REST handler
+ * ```typescript
+ * import handler from '../src/routes/create-plan.js';
+ *
+ * const result = await testCommand(handler, {
+ *   host: 'rest',
+ *   body: { name: 'v2.0' },
+ *   query: { workspace: 'root' },
+ * });
+ * expect(result.result).toMatchObject({ name: 'v2.0' });
+ * ```
+ *
+ * @example With LLM mock
+ * ```typescript
+ * import { testCommand, mockLLM } from '@kb-labs/shared-testing';
+ * import handler from '../src/commands/analyze.js';
+ *
+ * const llm = mockLLM().onAnyComplete().respondWith('looks good');
+ * const result = await testCommand(handler, {
+ *   flags: { file: 'index.ts' },
+ *   platform: { llm },
+ * });
+ * expect(llm.complete).toHaveBeenCalled();
+ * expect(result.exitCode).toBe(0);
+ * ```
+ */
+export async function testCommand<TResult = unknown, TConfig = unknown>(
+  handler: TestableHandler<TConfig, any, any>,
+  options: TestCommandOptions<TConfig> = {}
+): Promise<TestCommandResult<TResult>> {
+  const {
+    flags,
+    argv = [],
+    query,
+    body,
+    params,
+    input: rawInput,
+    host = 'cli',
+    config,
+    cwd,
+    tenantId,
+    signal,
+    platform,
+    ui,
+    syncSingleton = true,
+  } = options;
+
+  // ── Build context ──────────────────────────────────────────────
+
+  const ctxOptions: CreateTestContextOptions = {
+    host,
+    config,
+    cwd,
+    tenantId,
+    signal,
+    platform,
+    ui,
+    syncSingleton,
+  };
+
+  const { ctx, cleanup } = createTestContext<TConfig>(ctxOptions);
+
+  // ── Build input ────────────────────────────────────────────────
+
+  let input: unknown;
+
+  if (rawInput !== undefined) {
+    // Explicit raw input takes precedence
+    input = rawInput;
+  } else if (host === 'rest') {
+    // REST handlers expect { query?, body?, params? }
+    input = {
+      ...(query !== undefined ? { query } : {}),
+      ...(body !== undefined ? { body } : {}),
+      ...(params !== undefined ? { params } : {}),
+    };
+  } else {
+    // CLI/workflow handlers expect { flags, argv }
+    input = { flags: flags ?? {}, argv };
+  }
+
+  // ── Execute ────────────────────────────────────────────────────
+
+  let raw: unknown;
+  try {
+    raw = await handler.execute(ctx as PluginContextV3<TConfig>, input as any);
+  } finally {
+    // Call cleanup if handler has one
+    await handler.cleanup?.();
+  }
+
+  // ── Normalize result ───────────────────────────────────────────
+
+  // Handler may return CommandResult<T>, void, or raw data.
+  // Detect by checking for exitCode property.
+  let exitCode = 0;
+  let result: TResult | undefined;
+  let meta: Record<string, unknown> | undefined;
+
+  if (raw != null && typeof raw === 'object' && 'exitCode' in raw) {
+    // CommandResult shape
+    const cmdResult = raw as CommandResult<TResult>;
+    exitCode = cmdResult.exitCode;
+    result = cmdResult.result;
+    meta = cmdResult.meta;
+  } else if (raw === undefined || raw === null) {
+    // void return (RouteHandler can return void)
+    exitCode = 0;
+    result = undefined;
+    meta = undefined;
+  } else {
+    // Raw data (Handler from defineHandler returns data directly)
+    exitCode = 0;
+    result = raw as TResult;
+    meta = undefined;
+  }
+
+  return {
+    exitCode,
+    result,
+    meta,
+    raw,
+    ui: ctx.ui,
+    ctx: ctx as PluginContextV3,
+    cleanup,
+  };
+}

package/packages/shared-testing/tsconfig.build.json

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

package/packages/shared-testing/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/shared-testing/tsup.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node';
+
+export default defineConfig({
+  ...nodePreset,
+  entry: {
+    index: 'src/index.ts',
+  },
+  tsconfig: 'tsconfig.build.json',
+  dts: {
+    resolve: true,
+    entry: {
+      index: 'src/index.ts',
+    },
+  },
+  external: [
+    /^@kb-labs\/.*/, // All workspace packages - let runtime resolve them
+    'vitest',
+  ],
+});

package/packages/shared-testing/vitest.config.ts

@@ -0,0 +1,3 @@
+import preset from '@kb-labs/devkit/vitest/node';
+
+export default preset;

package/packages/shared-tool-kit/CHANGELOG.md

@@ -0,0 +1,20 @@
+## [1.1.0] - 2026-03-24
+
+**5 packages** bumped to v1.1.0
+
+| Package | Previous | Bump |
+|---------|----------|------|
+| `@kb-labs/perm-presets` | 1.0.0 | minor |
+| `@kb-labs/shared-command-kit` | 1.0.0 | minor |
+| `@kb-labs/shared-tool-kit` | 1.0.0 | minor |
+| `@kb-labs/shared-cli-ui` | 1.0.0 | minor |
+| `@kb-labs/shared-testing` | 1.0.0 | minor |
+
+### ✨ New Features
+
+- **config**: Introduces new configuration files for package management, allowing users to easily manage dependencies and ensure consistent environments across projects.
+- **github**: Implements GitHub workflows for CI/CD, streamlining the development process and enabling quicker, more reliable software updates for users.
+
+### 🐛 Bug Fixes
+
+- **tests**: Improves code clarity by using an object type instead of a placeholder, which helps prevent misunderstandings in the codebase and enhances maintainability. Additionally, it resolves a linting issue that could lead to confusion when no value is returned from certain functions.

package/packages/shared-tool-kit/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@kb-labs/shared-tool-kit",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Tool factory and mock utilities for KB Labs agent tool development",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/testing/index.js",
+      "types": "./dist/testing/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",
+    "@types/node": "^24.3.3",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "packageManager": "pnpm@9.11.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/shared-tool-kit/src/__tests__/factory.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createTool } from '../factory.js';
+
+interface TestCtx {
+  workingDir: string;
+  verbose?: boolean;
+}
+
+const spec = {
+  name: 'test_tool',
+  description: 'A test tool',
+  parameters: {
+    type: 'object' as const,
+    properties: {
+      value: { type: 'string', description: 'A string value' },
+    },
+    required: ['value'],
+  },
+  execute: async ({ value }: { value: string }, ctx: TestCtx) => ({
+    success: true,
+    output: `${value} from ${ctx.workingDir}`,
+  }),
+};
+
+describe('createTool', () => {
+  it('returns a factory function', () => {
+    const factory = createTool(spec);
+    expect(typeof factory).toBe('function');
+  });
+
+  it('factory returns tool with correct definition', () => {
+    const factory = createTool(spec);
+    const tool = factory({ workingDir: '/project' });
+
+    expect(tool.definition.type).toBe('function');
+    expect(tool.definition.function.name).toBe('test_tool');
+    expect(tool.definition.function.description).toBe('A test tool');
+    expect(tool.definition.function.parameters.required).toContain('value');
+  });
+
+  it('tool executor calls spec.execute with input and context', async () => {
+    const execute = vi.fn(async () => ({ success: true, output: 'ok' }));
+    const factory = createTool({ ...spec, execute });
+
+    const ctx: TestCtx = { workingDir: '/my/project' };
+    const tool = factory(ctx);
+    await tool.executor({ value: 'hello' });
+
+    expect(execute).toHaveBeenCalledWith({ value: 'hello' }, ctx);
+  });
+
+  it('executor returns result from spec.execute', async () => {
+    const factory = createTool(spec);
+    const tool = factory({ workingDir: '/root' });
+
+    const result = await tool.executor({ value: 'test' }) as any;
+
+    expect(result.success).toBe(true);
+    expect(result.output).toBe('test from /root');
+  });
+
+  it('each factory call creates independent tool bound to its context', async () => {
+    const execute = vi.fn(async (_input: unknown, ctx: TestCtx) => ({
+      success: true,
+      output: ctx.workingDir,
+    }));
+    const factory = createTool({ ...spec, execute });
+
+    const tool1 = factory({ workingDir: '/dir1' });
+    const tool2 = factory({ workingDir: '/dir2' });
+
+    const r1 = await tool1.executor({}) as any;
+    const r2 = await tool2.executor({}) as any;
+
+    expect(r1.output).toBe('/dir1');
+    expect(r2.output).toBe('/dir2');
+  });
+
+  it('parameters shape is preserved verbatim', () => {
+    const customParams = {
+      type: 'object' as const,
+      properties: {
+        foo: { type: 'number' },
+        bar: { type: 'boolean' },
+      },
+      required: ['foo'],
+    };
+    const factory = createTool({ ...spec, parameters: customParams });
+    const tool = factory({ workingDir: '/' });
+
+    expect(tool.definition.function.parameters).toEqual(customParams);
+  });
+
+  it('executor propagates errors from spec.execute', async () => {
+    const factory = createTool({
+      ...spec,
+      execute: async () => { throw new Error('something went wrong'); },
+    });
+    const tool = factory({ workingDir: '/' });
+
+    await expect(tool.executor({})).rejects.toThrow('something went wrong');
+  });
+});