@kb-labs/shared 1.1.0

package/packages/shared-http/src/operation-metrics-tracker.ts

@@ -0,0 +1,107 @@
+import { performance } from 'node:perf_hooks';
+import type { ServiceOperationSample } from '@kb-labs/core-contracts';
+
+type StatusStats = {
+  count: number;
+  totalDurationMs: number;
+  maxDurationMs: number;
+};
+
+type OperationStats = {
+  totalCount: number;
+  totalDurationMs: number;
+  maxDurationMs: number;
+  errorCount: number;
+  byStatus: Record<OperationStatus, StatusStats>;
+};
+
+export type OperationStatus = 'ok' | 'error';
+
+export interface OperationObserver {
+  recordOperation(operation: string, durationMs?: number, status?: OperationStatus, count?: number): void;
+  observeOperation<T>(operation: string, work: () => T | Promise<T>): Promise<T>;
+}
+
+function createEmptyStats(): OperationStats {
+  return {
+    totalCount: 0,
+    totalDurationMs: 0,
+    maxDurationMs: 0,
+    errorCount: 0,
+    byStatus: {
+      ok: { count: 0, totalDurationMs: 0, maxDurationMs: 0 },
+      error: { count: 0, totalDurationMs: 0, maxDurationMs: 0 },
+    },
+  };
+}
+
+export class OperationMetricsTracker implements OperationObserver {
+  private readonly stats = new Map<string, OperationStats>();
+
+  reset(): void {
+    this.stats.clear();
+  }
+
+  recordOperation(operation: string, durationMs = 0, status: OperationStatus = 'ok', count = 1): void {
+    if (typeof operation !== 'string' || operation.length === 0 || !Number.isFinite(count) || count <= 0) {
+      return;
+    }
+
+    const normalizedDuration = Number.isFinite(durationMs) ? Math.max(durationMs, 0) : 0;
+    const entry = this.stats.get(operation) ?? createEmptyStats();
+    entry.totalCount += count;
+    entry.totalDurationMs += normalizedDuration;
+    entry.maxDurationMs = Math.max(entry.maxDurationMs, normalizedDuration);
+    entry.byStatus[status].count += count;
+    entry.byStatus[status].totalDurationMs += normalizedDuration;
+    entry.byStatus[status].maxDurationMs = Math.max(entry.byStatus[status].maxDurationMs, normalizedDuration);
+    if (status === 'error') {
+      entry.errorCount += count;
+    }
+    this.stats.set(operation, entry);
+  }
+
+  async observeOperation<T>(operation: string, work: () => T | Promise<T>): Promise<T> {
+    const startedAt = performance.now();
+    try {
+      const result = await work();
+      this.recordOperation(operation, performance.now() - startedAt, 'ok');
+      return result;
+    } catch (error) {
+      this.recordOperation(operation, performance.now() - startedAt, 'error');
+      throw error;
+    }
+  }
+
+  getTopOperations(limit = 5): ServiceOperationSample[] {
+    return Array.from(this.stats.entries())
+      .sort((a, b) => b[1].totalCount - a[1].totalCount || b[1].maxDurationMs - a[1].maxDurationMs)
+      .slice(0, limit)
+      .map(([operation, stats]) => ({
+        operation,
+        count: stats.totalCount,
+        avgDurationMs: stats.totalCount > 0 ? stats.totalDurationMs / stats.totalCount : 0,
+        maxDurationMs: stats.maxDurationMs,
+        errorCount: stats.errorCount,
+      }));
+  }
+
+  getMetricLines(): string[] {
+    const lines: string[] = [];
+    for (const [operation, stats] of this.stats.entries()) {
+      for (const status of ['ok', 'error'] as const) {
+        const statusStats = stats.byStatus[status];
+        if (statusStats.count <= 0) {
+          continue;
+        }
+        lines.push(`service_operation_total{operation="${operation}",status="${status}"} ${statusStats.count}`);
+        lines.push(
+          `service_operation_duration_ms{operation="${operation}",status="${status}"} ${Number(
+            statusStats.totalDurationMs.toFixed(2),
+          )}`,
+        );
+      }
+    }
+    return lines;
+  }
+}

package/packages/shared-http/src/register-openapi.ts

@@ -0,0 +1,108 @@
+import { jsonSchemaTransform } from 'fastify-type-provider-zod';
+
+/** Minimal structural interface to accept any Fastify instance regardless of version. */
+interface FastifyLike {
+  register(plugin: unknown, opts?: unknown): unknown;
+  get(path: string, handler: (req: unknown, reply: unknown) => unknown): void;
+  swagger?(): unknown;
+}
+
+export interface OpenAPIOptions {
+  title: string;
+  description?: string;
+  version?: string;
+  /** Route prefix for Swagger UI. Default: '/docs' */
+  docsPath?: string;
+  /** Route for the raw OpenAPI JSON spec. Default: '/openapi.json' */
+  specPath?: string;
+  servers?: Array<{ url: string; description?: string }>;
+  /**
+   * Set to false to skip Swagger UI registration (e.g. in production).
+   * The spec endpoint (/openapi.json) is still registered.
+   * Default: true
+   */
+  ui?: boolean;
+}
+
+/**
+ * Wraps jsonSchemaTransform to safely handle routes with plain JSON schemas.
+ * ftzp v6 only accepts Zod schemas — plain JSON objects cause InvalidSchemaError.
+ * Routes without `tags` are hidden anyway (hideUntagged), so we skip transform
+ * for them to avoid the error.
+ */
+function safeJsonSchemaTransform(input: { schema: Record<string, unknown>; url: string; [k: string]: unknown }) {
+  const { schema } = input;
+
+  // No schema or explicitly hidden — pass through
+  if (!schema || schema.hide) {
+    return input;
+  }
+
+  // Routes without tags will be excluded by hideUntagged.
+  // Skip Zod transform for them to avoid errors on plain JSON schemas.
+  if (!schema.tags || (Array.isArray(schema.tags) && schema.tags.length === 0)) {
+    return { schema: { ...schema, hide: true }, url: input.url };
+  }
+
+  // Tagged routes — delegate to ftzp's jsonSchemaTransform (expects Zod schemas)
+  return jsonSchemaTransform(input as unknown as Parameters<typeof jsonSchemaTransform>[0]);
+}
+
+/**
+ * Registers @fastify/swagger + @fastify/swagger-ui on a Fastify instance.
+ *
+ * Call BEFORE registering routes, AFTER creating the Fastify instance.
+ *
+ * Routes without `tags:` are excluded from the spec (hideUntagged: true).
+ * Use this as the visibility toggle — internal/undocumented routes simply
+ * omit `tags:` and they won't appear in /docs or /openapi.json.
+ *
+ * @example
+ * ```ts
+ * import { registerOpenAPI } from '@kb-labs/shared-http';
+ *
+ * await registerOpenAPI(server, {
+ *   title: 'My Service',
+ *   version: '1.0.0',
+ *   servers: [{ url: 'http://localhost:3000', description: 'Local dev' }],
+ *   ui: process.env.NODE_ENV !== 'production',
+ * });
+ * ```
+ */
+export async function registerOpenAPI(server: FastifyLike, options: OpenAPIOptions): Promise<void> {
+  const swagger = await import('@fastify/swagger');
+
+  await server.register(swagger.default ?? swagger, {
+    openapi: {
+      info: {
+        title: options.title,
+        description: options.description ?? '',
+        version: options.version ?? '1.0.0',
+      },
+      servers: options.servers ?? [],
+    },
+    transform: safeJsonSchemaTransform,
+    hideUntagged: true,
+  });
+
+  const specPath = options.specPath ?? '/openapi.json';
+
+  await server.register(async (scope: FastifyLike) => {
+    scope.get(specPath, (_req, reply) => {
+      const s = server as { swagger?: () => unknown };
+      return (reply as { send(v: unknown): unknown }).send(s.swagger?.());
+    });
+  });
+
+  if (options.ui !== false) {
+    const swaggerUi = await import('@fastify/swagger-ui');
+
+    await server.register(swaggerUi.default ?? swaggerUi, {
+      routePrefix: options.docsPath ?? '/docs',
+      uiConfig: {
+        docExpansion: 'list',
+        deepLinking: true,
+      },
+    });
+  }
+}

package/packages/shared-http/src/resolve-schema-ref.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+export interface ZodSchemaRef {
+  /** Reference in format "package-name#ExportedSchemaName" */
+  zod: string;
+}
+
+export interface JsonSchemaRef {
+  $ref: string;
+}
+
+export type SchemaRef = ZodSchemaRef | JsonSchemaRef;
+
+/**
+ * Resolves a SchemaRef from a plugin manifest to a plain JSON Schema object.
+ *
+ * Supports two formats:
+ * - `{ $ref: "..." }` — returned as-is (already a JSON Schema reference)
+ * - `{ zod: "pkg#ExportName" }` — dynamically imports the package, grabs the
+ *   named export, and converts the ZodType to JSON Schema via zod-to-json-schema
+ *
+ * Fail-open: if the module cannot be imported or the export is missing/not a
+ * ZodType, returns null and logs a warning. The route will still mount — it just
+ * won't have schema documentation.
+ *
+ * @example
+ * ```ts
+ * const schema = await resolveSchemaRef({
+ *   zod: '@kb-labs/commit-contracts#GenerateRequestSchema'
+ * });
+ * // → { type: 'object', properties: { ... }, required: [...] }
+ * ```
+ */
+export async function resolveSchemaRef(ref: SchemaRef): Promise<Record<string, unknown> | null> {
+  if ('$ref' in ref) {
+    return { $ref: ref.$ref };
+  }
+
+  if ('zod' in ref) {
+    const hashIdx = ref.zod.lastIndexOf('#');
+    if (hashIdx === -1) {
+      console.warn(`[shared-http] resolveSchemaRef: invalid zod ref format "${ref.zod}" (expected "pkg#ExportName")`);
+      return null;
+    }
+
+    const modulePath = ref.zod.slice(0, hashIdx);
+    const exportName = ref.zod.slice(hashIdx + 1);
+
+    if (!modulePath || !exportName) {
+      console.warn(`[shared-http] resolveSchemaRef: empty module or export in "${ref.zod}"`);
+      return null;
+    }
+
+    try {
+      const mod = await import(modulePath);
+      const schema = mod[exportName];
+
+      if (!(schema instanceof z.ZodType)) {
+        console.warn(`[shared-http] resolveSchemaRef: "${ref.zod}" export is not a ZodType`);
+        return null;
+      }
+
+      // $refStrategy: 'none' inlines all nested schemas — avoids $ref chains
+      // that Fastify v4's JSON Schema validator may not resolve correctly.
+       
+      return zodToJsonSchema(schema as any, { $refStrategy: 'none' }) as Record<string, unknown>;
+    } catch (err) {
+      console.warn(`[shared-http] resolveSchemaRef: failed to import "${modulePath}": ${(err as Error).message}`);
+      return null;
+    }
+  }
+
+  return null;
+}

package/packages/shared-http/src/schemas.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+/**
+ * Standard error response schema.
+ * Use in route `response:` blocks for error status codes.
+ */
+export const ErrorResponseSchema = z.object({
+  ok: z.literal(false),
+  error: z.string(),
+  code: z.string().optional(),
+});
+
+/**
+ * Wraps a data schema in a standard success envelope.
+ *
+ * @example
+ * ```ts
+ * response: {
+ *   200: OkResponseSchema(z.object({ jobs: z.array(JobSchema) }))
+ * }
+ * ```
+ */
+export const OkResponseSchema = <T extends z.ZodTypeAny>(data: T) =>
+  z.object({
+    ok: z.literal(true),
+    data,
+  });
+
+export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;

package/packages/shared-http/src/service-observability.ts

@@ -0,0 +1,63 @@
+import {
+  validateServiceObservabilityDescribe,
+  validateServiceObservabilityHealth,
+} from '@kb-labs/core-contracts';
+
+export interface VersionedObservabilityShape {
+  schema: string;
+  contractVersion: string;
+}
+
+export interface ServiceReadyResponse {
+  schema: 'kb.ready/1';
+  ts: string;
+  ready: boolean;
+  status: 'ready' | 'degraded' | 'initializing';
+  reason: string;
+  components: Record<string, unknown>;
+}
+
+/**
+ * Shared builder for versioned service describe payloads.
+ * Keeps services on a single construction path instead of ad hoc objects.
+ */
+export function createServiceObservabilityDescribe<T extends VersionedObservabilityShape>(options: T): T {
+  const result = validateServiceObservabilityDescribe(options);
+  if (!result.ok) {
+    throw new Error(
+      `Invalid observability describe payload: ${result.issues.map((issue: { path: string; message: string }) => `${issue.path}: ${issue.message}`).join(', ')}`,
+    );
+  }
+  return options;
+}
+
+/**
+ * Shared builder for versioned service health payloads.
+ * Callers provide the contract-specific shape while keeping a common entry point.
+ */
+export function createServiceObservabilityHealth<T extends VersionedObservabilityShape>(options: T): T {
+  const result = validateServiceObservabilityHealth(options);
+  if (!result.ok) {
+    throw new Error(
+      `Invalid observability health payload: ${result.issues.map((issue: { path: string; message: string }) => `${issue.path}: ${issue.message}`).join(', ')}`,
+    );
+  }
+  return options;
+}
+
+export function createServiceReadyResponse(options: {
+  ready: boolean;
+  status?: ServiceReadyResponse['status'];
+  reason?: string;
+  components?: Record<string, unknown>;
+  ts?: string;
+}): ServiceReadyResponse {
+  return {
+    schema: 'kb.ready/1',
+    ts: options.ts ?? new Date().toISOString(),
+    ready: options.ready,
+    status: options.status ?? (options.ready ? 'ready' : 'initializing'),
+    reason: options.reason ?? (options.ready ? 'ready' : 'initializing'),
+    components: options.components ?? {},
+  };
+}

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

@@ -0,0 +1,23 @@
+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\/.*/,
+    'fastify',
+    '@fastify/swagger',
+    '@fastify/swagger-ui',
+    'fastify-type-provider-zod',
+  ],
+});

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

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+import nodePreset from '@kb-labs/devkit/vitest/node.js';
+
+export default defineConfig({
+  ...nodePreset,
+  test: {
+    ...nodePreset.test,
+    coverage: {
+      ...nodePreset.test?.coverage,
+      enabled: false,
+    },
+  },
+});

package/packages/shared-perm-presets/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-perm-presets/README.md

@@ -0,0 +1,78 @@
+# @kb-labs/perm-presets
+
+> Composable permission presets for KB Labs plugin manifests.
+
+## Installation
+
+```bash
+pnpm add @kb-labs/perm-presets
+```
+
+Or use via `@kb-labs/sdk` (already bundled):
+
+```typescript
+import { minimalPreset, combinePermissions } from '@kb-labs/sdk';
+```
+
+## Quick Start
+
+```typescript
+import { combine, minimal, llmAccess, gitWorkflow } from '@kb-labs/perm-presets';
+import { defineManifest } from '@kb-labs/sdk';
+
+export default defineManifest({
+  schema: 'kb.plugin/3',
+  id: 'my-plugin',
+  version: '1.0.0',
+  permissions: combine(minimal, llmAccess, gitWorkflow),
+});
+```
+
+## Available Presets
+
+| Preset | Description |
+|--------|-------------|
+| `minimal` | Minimal permissions (read-only workspace) |
+| `gitWorkflow` | Git read/write operations |
+| `npmPublish` | npm publish permissions |
+| `fullEnv` | Full environment variable access |
+| `kbPlatform` | KB Labs platform API access |
+| `llmAccess` | LLM API access |
+| `vectorStore` | Vector store access |
+| `ciEnvironment` | CI/CD environment permissions |
+
+## API
+
+### `combine(...presets)`
+
+Merge multiple presets into a single `PermissionSpec`:
+
+```typescript
+import { combine, minimal, llmAccess } from '@kb-labs/perm-presets';
+
+const permissions = combine(minimal, llmAccess);
+```
+
+### `combinePresets(presets[])`
+
+Same as `combine` but accepts an array:
+
+```typescript
+import { combinePresets, presets } from '@kb-labs/perm-presets';
+
+const permissions = combinePresets([presets.minimal, presets.llmAccess]);
+```
+
+### `presets` namespace
+
+All presets accessible as a namespace:
+
+```typescript
+import { presets, combine } from '@kb-labs/perm-presets';
+
+const permissions = combine(presets.minimal, presets.kbPlatform);
+```
+
+## License
+
+MIT

package/packages/shared-perm-presets/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',
+  //   ]
+  // }
+];

package/packages/shared-perm-presets/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@kb-labs/perm-presets",
+  "version": "1.1.0",
+  "description": "Composable permission presets for KB Labs plugins",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rimraf dist",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",
+    "typescript": "^5.6.3",
+    "tsup": "^8.5.0",
+    "rimraf": "^6.0.1",
+    "vitest": "^3.2.4",
+    "@types/node": "^24.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}