@kb-labs/shared 1.1.0

package/packages/shared-command-kit/src/validation/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @module @kb-labs/shared-command-kit/validation
+ * Validation schema builders
+ */
+
+export * from './schema-builders';

package/packages/shared-command-kit/src/validation/schema-builders.ts

@@ -0,0 +1,409 @@
+/**
+ * Schema Builders for KB Labs Plugins
+ *
+ * Optional helpers for common Zod validation patterns.
+ * You can always use plain Zod - these are just conveniences for repetitive patterns.
+ *
+ * @example
+ * ```typescript
+ * import { schema } from '@kb-labs/shared-command-kit';
+ *
+ * const RequestSchema = schema.object({
+ *   cwd: schema.cwd(),
+ *   scope: schema.scopeId(),
+ *   text: schema.text({ min: 1, max: 10000 }),
+ *   mode: schema.enum(['instant', 'auto', 'thinking'], { default: 'auto' }),
+ *   limit: schema.positiveInt({ max: 100, default: 10 }),
+ * });
+ * ```
+ */
+
+import { z } from 'zod';
+
+/**
+ * Current working directory path (optional string)
+ * Commonly used in CLI and REST handlers
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   cwd: schema.cwd(),
+ * });
+ * // Equivalent to: cwd: z.string().optional()
+ * ```
+ */
+export function cwd() {
+  return z.string().optional().describe('Current working directory path');
+}
+
+/**
+ * Scope identifier (required non-empty string)
+ * Used for Mind RAG scopes, workflow scopes, etc.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   scope: schema.scopeId(),
+ * });
+ * // Equivalent to: scope: z.string().min(1)
+ * ```
+ */
+export function scopeId() {
+  return z.string().min(1).describe('Scope identifier');
+}
+
+/**
+ * Text string with optional length constraints
+ *
+ * @example
+ * ```typescript
+ * schema.text({ min: 1, max: 10000 })
+ * // Equivalent to: z.string().min(1).max(10000)
+ * ```
+ */
+export function text(options?: { min?: number; max?: number; default?: string }): z.ZodString | z.ZodDefault<z.ZodString> {
+  let schema = z.string();
+
+  if (options?.min !== undefined) {
+    schema = schema.min(options.min);
+  }
+
+  if (options?.max !== undefined) {
+    schema = schema.max(options.max);
+  }
+
+  if (options?.default !== undefined) {
+    return schema.default(options.default).describe('Text string');
+  }
+
+  return schema.describe('Text string');
+}
+
+/**
+ * Positive integer with optional constraints
+ *
+ * @example
+ * ```typescript
+ * schema.positiveInt({ max: 100, default: 10 })
+ * // Equivalent to: z.number().int().positive().max(100).default(10)
+ * ```
+ */
+export function positiveInt(options?: { min?: number; max?: number; default?: number }): z.ZodNumber | z.ZodDefault<z.ZodNumber> {
+  let schema = z.number().int().positive();
+
+  if (options?.min !== undefined) {
+    schema = schema.min(options.min);
+  }
+
+  if (options?.max !== undefined) {
+    schema = schema.max(options.max);
+  }
+
+  if (options?.default !== undefined) {
+    return schema.default(options.default).describe('Positive integer');
+  }
+
+  return schema.describe('Positive integer');
+}
+
+/**
+ * Non-negative integer (0 or positive)
+ *
+ * @example
+ * ```typescript
+ * schema.nonNegativeInt({ max: 100 })
+ * // Equivalent to: z.number().int().min(0).max(100)
+ * ```
+ */
+export function nonNegativeInt(options?: { max?: number; default?: number }): z.ZodNumber | z.ZodDefault<z.ZodNumber> {
+  let schema = z.number().int().min(0);
+
+  if (options?.max !== undefined) {
+    schema = schema.max(options.max);
+  }
+
+  if (options?.default !== undefined) {
+    return schema.default(options.default).describe('Non-negative integer');
+  }
+
+  return schema.describe('Non-negative integer');
+}
+
+/**
+ * Enum with optional default value
+ *
+ * @example
+ * ```typescript
+ * schema.enum(['instant', 'auto', 'thinking'], { default: 'auto' })
+ * // Equivalent to: z.enum(['instant', 'auto', 'thinking']).default('auto')
+ * ```
+ */
+export function enumSchema<T extends [string, ...string[]]>(
+  values: T,
+  options?: { default?: T[number] }
+): z.ZodDefault<z.ZodEnum<T>> | z.ZodEnum<T> {
+  const schema = z.enum(values);
+
+  if (options?.default !== undefined) {
+    return schema.default(options.default as T[number]);
+  }
+
+  return schema;
+}
+
+/**
+ * Plugin ID (@kb-labs/package-name format)
+ *
+ * @example
+ * ```typescript
+ * schema.pluginId()
+ * // Matches: @kb-labs/mind, @kb-labs/workflow, etc.
+ * ```
+ */
+export function pluginId() {
+  return z
+    .string()
+    .regex(/^@kb-labs\/[a-z][a-z0-9-]*$/, 'Must be in format @kb-labs/package-name')
+    .describe('Plugin ID');
+}
+
+/**
+ * Command ID (plugin:command format)
+ *
+ * @example
+ * ```typescript
+ * schema.commandId()
+ * // Matches: mind:query, workflow:run, etc.
+ * ```
+ */
+export function commandId() {
+  return z
+    .string()
+    .regex(/^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$/, 'Must be in format plugin:command')
+    .describe('Command ID');
+}
+
+/**
+ * Artifact ID (plugin.artifact.id format)
+ *
+ * @example
+ * ```typescript
+ * schema.artifactId()
+ * // Matches: mind.index.vector, workflow.run.result, etc.
+ * ```
+ */
+export function artifactId() {
+  return z
+    .string()
+    .regex(/^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/, 'Must be in format plugin.artifact.id')
+    .describe('Artifact ID');
+}
+
+/**
+ * File path (string)
+ * Optional with default to undefined
+ *
+ * @example
+ * ```typescript
+ * schema.filePath()
+ * // Equivalent to: z.string()
+ * ```
+ */
+export function filePath(options?: { optional?: boolean }) {
+  const schema = z.string().describe('File path');
+
+  if (options?.optional) {
+    return schema.optional();
+  }
+
+  return schema;
+}
+
+/**
+ * URL string
+ *
+ * @example
+ * ```typescript
+ * schema.url()
+ * // Equivalent to: z.string().url()
+ * ```
+ */
+export function url(options?: { optional?: boolean }) {
+  const schema = z.string().url().describe('URL');
+
+  if (options?.optional) {
+    return schema.optional();
+  }
+
+  return schema;
+}
+
+/**
+ * Email string
+ *
+ * @example
+ * ```typescript
+ * schema.email()
+ * // Equivalent to: z.string().email()
+ * ```
+ */
+export function email(options?: { optional?: boolean }) {
+  const schema = z.string().email().describe('Email address');
+
+  if (options?.optional) {
+    return schema.optional();
+  }
+
+  return schema;
+}
+
+/**
+ * UUID string
+ *
+ * @example
+ * ```typescript
+ * schema.uuid()
+ * // Equivalent to: z.string().uuid()
+ * ```
+ */
+export function uuid(options?: { optional?: boolean }) {
+  const schema = z.string().uuid().describe('UUID');
+
+  if (options?.optional) {
+    return schema.optional();
+  }
+
+  return schema;
+}
+
+/**
+ * ISO datetime string
+ *
+ * @example
+ * ```typescript
+ * schema.datetime()
+ * // Equivalent to: z.string().datetime()
+ * ```
+ */
+export function datetime(options?: { optional?: boolean }) {
+  const schema = z.string().datetime().describe('ISO datetime');
+
+  if (options?.optional) {
+    return schema.optional();
+  }
+
+  return schema;
+}
+
+/**
+ * JSON object (any valid JSON object)
+ *
+ * @example
+ * ```typescript
+ * schema.json()
+ * // Equivalent to: z.record(z.unknown())
+ * ```
+ */
+export function json() {
+  return z.record(z.unknown()).describe('JSON object');
+}
+
+/**
+ * Boolean with optional default
+ *
+ * @example
+ * ```typescript
+ * schema.boolean({ default: false })
+ * // Equivalent to: z.boolean().default(false)
+ * ```
+ */
+export function boolean(options?: { default?: boolean }) {
+  const schema = z.boolean();
+
+  if (options?.default !== undefined) {
+    return schema.default(options.default);
+  }
+
+  return schema;
+}
+
+/**
+ * Array of items with optional length constraints
+ *
+ * @example
+ * ```typescript
+ * schema.array(z.string(), { min: 1, max: 10 })
+ * // Equivalent to: z.array(z.string()).min(1).max(10)
+ * ```
+ */
+export function array<T extends z.ZodTypeAny>(
+  itemSchema: T,
+  options?: { min?: number; max?: number }
+) {
+  let schema = z.array(itemSchema);
+
+  if (options?.min !== undefined) {
+    schema = schema.min(options.min);
+  }
+
+  if (options?.max !== undefined) {
+    schema = schema.max(options.max);
+  }
+
+  return schema;
+}
+
+/**
+ * Object schema builder (alias for z.object)
+ *
+ * @example
+ * ```typescript
+ * schema.object({ name: z.string() })
+ * // Equivalent to: z.object({ name: z.string() })
+ * ```
+ */
+export function object<T extends z.ZodRawShape>(shape: T) {
+  return z.object(shape);
+}
+
+/**
+ * Export schema builders namespace
+ *
+ * @example
+ * ```typescript
+ * import { schema } from '@kb-labs/shared-command-kit';
+ *
+ * const MySchema = schema.object({
+ *   cwd: schema.cwd(),
+ *   scope: schema.scopeId(),
+ *   text: schema.text({ min: 1, max: 10000 }),
+ * });
+ * ```
+ */
+export const schema = {
+  // Path and ID builders
+  cwd,
+  scopeId,
+  pluginId,
+  commandId,
+  artifactId,
+  filePath,
+
+  // String builders
+  text,
+  url,
+  email,
+  uuid,
+  datetime,
+
+  // Number builders
+  positiveInt,
+  nonNegativeInt,
+
+  // Other builders
+  enum: enumSchema,
+  boolean,
+  json,
+  array,
+  object,
+};

package/packages/shared-command-kit/src/ws-types.ts

@@ -0,0 +1,106 @@
+/**
+ * Enhanced WebSocket types for better DX
+ *
+ * Provides type-safe message builders and pattern matching utilities.
+ */
+
+import type { PluginContextV3 } from '@kb-labs/plugin-contracts';
+import type { WSSender, WSMessage } from '@kb-labs/plugin-contracts';
+
+/**
+ * Type-safe message builder
+ *
+ * @example
+ * ```typescript
+ * const Progress = defineMessage<{ phase: string; progress: number }>('progress');
+ * const msg = Progress.create({ phase: 'analyzing', progress: 50 });
+ * // msg: { type: 'progress', payload: { phase: 'analyzing', progress: 50 }, timestamp: number }
+ * ```
+ */
+export class MessageBuilder<TPayload = unknown> {
+  constructor(private type: string) {}
+
+  /**
+   * Create message with payload
+   */
+  create(payload: TPayload, messageId?: string): WSMessage {
+    return {
+      type: this.type,
+      payload,
+      messageId,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Match against incoming message type (type guard)
+   */
+  is(message: WSMessage): message is WSMessage & { payload: TPayload } {
+    return message.type === this.type;
+  }
+}
+
+/**
+ * Helper to define typed messages
+ *
+ * @example
+ * ```typescript
+ * const StartMsg = defineMessage<{ scope?: string }>('start');
+ * const ProgressMsg = defineMessage<{ phase: string; progress: number }>('progress');
+ * ```
+ */
+export function defineMessage<TPayload = unknown>(type: string) {
+  return new MessageBuilder<TPayload>(type);
+}
+
+/**
+ * Message router for pattern matching
+ *
+ * Provides elegant routing of incoming WebSocket messages to typed handlers.
+ *
+ * @example
+ * ```typescript
+ * const router = new MessageRouter()
+ *   .on(StartMsg, async (ctx, payload, sender) => {
+ *     // payload is typed as { scope?: string }
+ *     console.log('Starting with scope:', payload.scope);
+ *   })
+ *   .on(StopMsg, async (ctx, payload, sender) => {
+ *     // Different message type, different payload type
+ *     sender.close(1000, 'Stopped by user');
+ *   });
+ *
+ * await router.handle(ctx, message, sender);
+ * ```
+ */
+export class MessageRouter<TConfig = unknown> {
+  private handlers = new Map<
+    string,
+    (ctx: PluginContextV3<TConfig>, payload: any, sender: WSSender) => Promise<void> | void
+  >();
+
+  /**
+   * Register message handler
+   */
+  on<TPayload>(
+    message: MessageBuilder<TPayload>,
+    handler: (ctx: PluginContextV3<TConfig>, payload: TPayload, sender: WSSender) => Promise<void> | void
+  ): this {
+    this.handlers.set(message['type'], handler);
+    return this;
+  }
+
+  /**
+   * Handle incoming message
+   *
+   * @returns true if message was handled, false otherwise
+   */
+  async handle(ctx: PluginContextV3<TConfig>, message: WSMessage, sender: WSSender): Promise<boolean> {
+    const handler = this.handlers.get(message.type);
+    if (handler) {
+      await handler(ctx, message.payload, sender);
+      return true;
+    }
+    return false;
+  }
+}

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

@@ -0,0 +1,30 @@
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node';
+
+export default defineConfig({
+  ...nodePreset,
+  entry: {
+    index: 'src/index.ts',
+    'flags/index': 'src/flags/index.ts',
+    'analytics/index': 'src/analytics/index.ts',
+    'errors/index': 'src/errors/index.ts',
+    'helpers/index': 'src/helpers/index.ts',
+    'studio/index': 'src/studio/index.ts',
+  },
+  tsconfig: 'tsconfig.build.json', // Use build-specific tsconfig without paths
+  dts: {
+    resolve: true, // Resolve external type declarations
+    entry: {
+      // Skip studio types due to dependency issues
+      index: 'src/index.ts',
+      'flags/index': 'src/flags/index.ts',
+      'analytics/index': 'src/analytics/index.ts',
+      'errors/index': 'src/errors/index.ts',
+      'helpers/index': 'src/helpers/index.ts',
+    },
+  },
+  external: [
+    /^@kb-labs\/.*/, // All workspace packages - let runtime resolve them
+  ],
+});
+

package/packages/shared-command-kit/vitest.config.ts

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

package/packages/shared-http/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@kb-labs/shared-http",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Shared Fastify/OpenAPI utilities for KB Labs HTTP services",
+  "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 --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@kb-labs/core-contracts": "link:../../../kb-labs-core/packages/core-contracts",
+    "zod": "^4.0.0",
+    "zod-to-json-schema": "^3.25.0"
+  },
+  "peerDependencies": {
+    "@fastify/swagger": ">=9.5.1",
+    "@fastify/swagger-ui": "^5.2.0",
+    "fastify": "^5.5.0",
+    "fastify-type-provider-zod": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@fastify/swagger": {
+      "optional": false
+    },
+    "@fastify/swagger-ui": {
+      "optional": false
+    },
+    "fastify-type-provider-zod": {
+      "optional": false
+    }
+  },
+  "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"
+  }
+}