@kb-labs/shared 1.1.0

package/packages/shared-command-kit/src/lifecycle/define-handlers.ts

@@ -0,0 +1,366 @@
+/**
+ * Lifecycle Hook Helpers
+ *
+ * Optional helpers for plugin lifecycle hooks (setup, destroy, upgrade).
+ * You can always use plain functions - this is just convenience.
+ *
+ * @example
+ * ```typescript
+ * import { defineSetupHandler } from '@kb-labs/shared-command-kit';
+ *
+ * export const setup = defineSetupHandler({
+ *   name: 'mind:setup',
+ *   workspace: {
+ *     directories: ['.kb/mind/index', '.kb/mind/cache'],
+ *   },
+ *   config: {
+ *     'kb.config.json': {
+ *       mind: { enabled: true, scopes: ['default'] },
+ *     },
+ *   },
+ *   async handler(ctx) {
+ *     ctx.log('Mind workspace initialized');
+ *     return { ok: true };
+ *   },
+ * });
+ * ```
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { existsSync } from 'node:fs';
+
+/**
+ * Lifecycle handler context
+ */
+export interface LifecycleContext {
+  /** Output directory (plugin workspace root) */
+  outdir: string;
+  /** Plugin ID */
+  pluginId: string;
+  /** Request ID for tracing */
+  requestId?: string;
+  /** Logger */
+  log?: (level: 'debug' | 'info' | 'warn' | 'error', msg: string, meta?: Record<string, unknown>) => void;
+  /** Environment getter */
+  env?: (key: string) => string | undefined;
+}
+
+/**
+ * Workspace setup configuration
+ */
+export interface WorkspaceConfig {
+  /** Directories to create (relative to outdir or absolute) */
+  directories?: string[];
+  /** Files to create with content */
+  files?: Record<string, string>;
+}
+
+/**
+ * Config file updates
+ */
+export type ConfigUpdates = Record<string, Record<string, unknown>>;
+
+/**
+ * Setup handler definition
+ */
+export interface SetupHandlerDefinition {
+  /** Handler name (for logging) */
+  name: string;
+  /** Workspace configuration (directories/files to create) */
+  workspace?: WorkspaceConfig;
+  /** Config file updates (will be merged with existing config) */
+  config?: ConfigUpdates;
+  /** Custom setup logic (optional) */
+  handler?: (ctx: LifecycleContext) => Promise<{ ok: boolean; message?: string }>;
+}
+
+/**
+ * Destroy handler definition
+ */
+export interface DestroyHandlerDefinition {
+  /** Handler name (for logging) */
+  name: string;
+  /** Workspace cleanup (directories/files to remove) */
+  workspace?: {
+    /** Directories to remove */
+    directories?: string[];
+    /** Files to remove */
+    files?: string[];
+  };
+  /** Config cleanup (keys to remove from config files) */
+  config?: Record<string, string[]>; // file -> keys to remove
+  /** Custom destroy logic (optional) */
+  handler?: (ctx: LifecycleContext) => Promise<{ ok: boolean; message?: string }>;
+}
+
+/**
+ * Setup handler result
+ */
+export interface SetupResult {
+  ok: boolean;
+  message?: string;
+}
+
+/**
+ * Define a setup handler with declarative workspace and config setup
+ *
+ * @example
+ * ```typescript
+ * export const setup = defineSetupHandler({
+ *   name: 'mind:setup',
+ *   workspace: {
+ *     directories: [
+ *       '.kb/mind/index',
+ *       '.kb/mind/cache',
+ *       '.kb/mind/pack',
+ *     ],
+ *     files: {
+ *       '.kb/mind/.gitignore': 'cache/\npack/\n',
+ *     },
+ *   },
+ *   config: {
+ *     'kb.config.json': {
+ *       mind: {
+ *         enabled: true,
+ *         scopes: ['default'],
+ *       },
+ *     },
+ *   },
+ *   async handler(ctx) {
+ *     ctx.log?.('info', 'Custom setup logic', {});
+ *     return { ok: true };
+ *   },
+ * });
+ * ```
+ */
+export function defineSetupHandler(
+  definition: SetupHandlerDefinition
+): (ctx: LifecycleContext) => Promise<SetupResult> {
+  return async (ctx: LifecycleContext) => {
+    const log = ctx.log || ((level: string, msg: string, meta?: Record<string, unknown>) => {
+      console.log(`[${level}] ${msg}`, meta || '');
+    });
+
+    try {
+      log('info', 'Setup started', { handler: definition.name, outdir: ctx.outdir });
+
+      // 1. Create workspace directories and files
+      if (definition.workspace) {
+        await setupWorkspace(ctx.outdir, definition.workspace, log);
+      }
+
+      // 2. Update config files
+      if (definition.config) {
+        await updateConfigFiles(ctx.outdir, definition.config, log);
+      }
+
+      // 3. Run custom handler logic
+      if (definition.handler) {
+        const result = await definition.handler(ctx);
+        if (!result.ok) {
+          return result;
+        }
+      }
+
+      log('info', 'Setup completed', { handler: definition.name });
+      return { ok: true, message: `${definition.name} setup completed` };
+    } catch (error: any) {
+      log('error', 'Setup failed', {
+        handler: definition.name,
+        error: error.message,
+        stack: error.stack,
+      });
+      return { ok: false, message: `Setup failed: ${error.message}` };
+    }
+  };
+}
+
+/**
+ * Define a destroy handler with declarative cleanup
+ *
+ * @example
+ * ```typescript
+ * export const destroy = defineDestroyHandler({
+ *   name: 'mind:destroy',
+ *   workspace: {
+ *     directories: ['.kb/mind'],
+ *   },
+ *   config: {
+ *     'kb.config.json': ['mind'], // Remove 'mind' key
+ *   },
+ * });
+ * ```
+ */
+export function defineDestroyHandler(
+  definition: DestroyHandlerDefinition
+): (ctx: LifecycleContext) => Promise<SetupResult> {
+  return async (ctx: LifecycleContext) => {
+    const log = ctx.log || ((level: string, msg: string, meta?: Record<string, unknown>) => {
+      console.log(`[${level}] ${msg}`, meta || '');
+    });
+
+    try {
+      log('info', 'Destroy started', { handler: definition.name, outdir: ctx.outdir });
+
+      // 1. Clean up config files
+      if (definition.config) {
+        await cleanupConfigFiles(ctx.outdir, definition.config, log);
+      }
+
+      // 2. Remove workspace directories and files
+      if (definition.workspace) {
+        await cleanupWorkspace(ctx.outdir, definition.workspace, log);
+      }
+
+      // 3. Run custom handler logic
+      if (definition.handler) {
+        const result = await definition.handler(ctx);
+        if (!result.ok) {
+          return result;
+        }
+      }
+
+      log('info', 'Destroy completed', { handler: definition.name });
+      return { ok: true, message: `${definition.name} destroy completed` };
+    } catch (error: any) {
+      log('error', 'Destroy failed', {
+        handler: definition.name,
+        error: error.message,
+        stack: error.stack,
+      });
+      return { ok: false, message: `Destroy failed: ${error.message}` };
+    }
+  };
+}
+
+/**
+ * Setup workspace directories and files
+ */
+async function setupWorkspace(
+  outdir: string,
+  config: WorkspaceConfig,
+  log: (level: 'error' | 'info' | 'debug' | 'warn', msg: string, meta?: Record<string, unknown>) => void
+): Promise<void> {
+  // Create directories
+  if (config.directories) {
+    for (const dir of config.directories) {
+      const dirPath = path.resolve(outdir, dir);
+      await fs.mkdir(dirPath, { recursive: true });
+      log('debug', 'Created directory', { path: dirPath });
+    }
+  }
+
+  // Create files
+  if (config.files) {
+    for (const [filePath, content] of Object.entries(config.files)) {
+      const fullPath = path.resolve(outdir, filePath);
+      const dirPath = path.dirname(fullPath);
+      await fs.mkdir(dirPath, { recursive: true });
+      await fs.writeFile(fullPath, content, 'utf-8');
+      log('debug', 'Created file', { path: fullPath });
+    }
+  }
+}
+
+/**
+ * Update config files (merge with existing config)
+ */
+async function updateConfigFiles(
+  outdir: string,
+  updates: ConfigUpdates,
+  log: (level: 'error' | 'info' | 'debug' | 'warn', msg: string, meta?: Record<string, unknown>) => void
+): Promise<void> {
+  for (const [configFile, configUpdates] of Object.entries(updates)) {
+    const configPath = path.resolve(outdir, configFile);
+
+    // Read existing config or create empty
+    let config: Record<string, unknown> = {};
+    if (existsSync(configPath)) {
+      const content = await fs.readFile(configPath, 'utf-8');
+      try {
+        config = JSON.parse(content);
+      } catch (error) {
+        log('warn', 'Failed to parse existing config, starting fresh', { path: configPath });
+      }
+    }
+
+    // Merge updates
+    config = { ...config, ...configUpdates };
+
+    // Write updated config
+    const dirPath = path.dirname(configPath);
+    await fs.mkdir(dirPath, { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    log('debug', 'Updated config file', { path: configPath });
+  }
+}
+
+/**
+ * Cleanup workspace directories and files
+ */
+async function cleanupWorkspace(
+  outdir: string,
+  config: DestroyHandlerDefinition['workspace'],
+  log: (level: 'error' | 'info' | 'debug' | 'warn', msg: string, meta?: Record<string, unknown>) => void
+): Promise<void> {
+  if (!config) {return;}
+
+  // Remove files first
+  if (config.files) {
+    for (const file of config.files) {
+      const filePath = path.resolve(outdir, file);
+      if (existsSync(filePath)) {
+        await fs.unlink(filePath);
+        log('debug', 'Removed file', { path: filePath });
+      }
+    }
+  }
+
+  // Remove directories
+  if (config.directories) {
+    for (const dir of config.directories) {
+      const dirPath = path.resolve(outdir, dir);
+      if (existsSync(dirPath)) {
+        await fs.rm(dirPath, { recursive: true, force: true });
+        log('debug', 'Removed directory', { path: dirPath });
+      }
+    }
+  }
+}
+
+/**
+ * Cleanup config files (remove keys)
+ */
+async function cleanupConfigFiles(
+  outdir: string,
+  cleanups: Record<string, string[]>,
+  log: (level: 'error' | 'info' | 'debug' | 'warn', msg: string, meta?: Record<string, unknown>) => void
+): Promise<void> {
+  for (const [configFile, keysToRemove] of Object.entries(cleanups)) {
+    const configPath = path.resolve(outdir, configFile);
+
+    if (!existsSync(configPath)) {
+      continue;
+    }
+
+    // Read config
+    const content = await fs.readFile(configPath, 'utf-8');
+    let config: Record<string, unknown>;
+    try {
+      config = JSON.parse(content);
+    } catch (error) {
+      log('warn', 'Failed to parse config for cleanup', { path: configPath });
+      continue;
+    }
+
+    // Remove keys
+    for (const key of keysToRemove) {
+      delete config[key];
+    }
+
+    // Write updated config
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    log('debug', 'Cleaned up config file', { path: configPath, removed: keysToRemove });
+  }
+}

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

@@ -0,0 +1,6 @@
+/**
+ * @module @kb-labs/shared-command-kit/lifecycle
+ * Lifecycle hook helpers (setup, destroy, upgrade)
+ */
+
+export * from './define-handlers';

package/packages/shared-command-kit/src/manifest.ts

@@ -0,0 +1,127 @@
+/**
+ * Manifest definition helpers
+ * @module @kb-labs/shared-command-kit/manifest
+ */
+
+import type { ManifestV3 } from '@kb-labs/plugin-contracts';
+
+/**
+ * Define a ManifestV3 with type safety
+ *
+ * This is a type-safe wrapper for creating ManifestV3 objects.
+ * It provides compile-time validation via TypeScript and optional
+ * runtime validation via Zod (if enabled).
+ *
+ * For built plugins (dist/), this function is compiled away and only
+ * the plain object remains, avoiding runtime dependencies.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * export const manifest = defineManifest({
+ *   schema: 'kb.plugin/2',
+ *   id: '@kb-labs/my-plugin',
+ *   version: '1.0.0',
+ *   cli: {
+ *     commands: [...]
+ *   }
+ * });
+ *
+ * // With contracts typing (Level 2)
+ * import type { PluginContracts } from '@kb-labs/my-plugin-contracts';
+ *
+ * export const manifest = defineManifest<typeof pluginContractsManifest>({
+ *   schema: 'kb.plugin/2',
+ *   id: '@kb-labs/my-plugin',
+ *   artifacts: [
+ *     { id: 'my.artifact.id' } // ✅ Type-checked against contracts
+ *   ],
+ *   cli: {
+ *     commands: [{
+ *       id: 'my:command', // ✅ Type-checked against contracts
+ *       // ...
+ *     }]
+ *   }
+ * });
+ * ```
+ *
+ * @param manifest - Manifest configuration
+ * @returns ManifestV3 object
+ */
+export function defineManifest<TContracts = unknown>(
+  manifest: ManifestV3
+): ManifestV3 {
+  // In development, you could add runtime validation here if needed:
+  // if (process.env.NODE_ENV === 'development') {
+  //   validateManifestV3(manifest);
+  // }
+
+  // For production builds, this is just an identity function
+  // that provides type safety at compile time
+  return manifest;
+}
+
+/**
+ * Flag schema definition (compatible with defineFlags)
+ */
+type FlagSchemaDefinition = Record<
+  string,
+  {
+    type: 'string' | 'boolean' | 'number' | 'array';
+    alias?: string;
+    default?: unknown;
+    description?: string;
+    choices?: string[];
+    required?: boolean;
+  }
+>;
+
+/**
+ * Convert flag schema definition to CliFlagDecl[] for manifest
+ *
+ * This helper converts the flag schema format used in defineCommand
+ * to the array format expected in ManifestV3.
+ *
+ * @example
+ * ```typescript
+ * const helloFlags = {
+ *   name: { type: 'string', description: 'Name to greet', alias: 'n' },
+ *   json: { type: 'boolean', description: 'Emit JSON', default: false }
+ * };
+ *
+ * const manifestFlags = defineCommandFlags(helloFlags);
+ * // Use in manifest: flags: manifestFlags
+ *
+ * // In manifest.v2.ts:
+ * export const manifest = defineManifest({
+ *   cli: {
+ *     commands: [{
+ *       id: 'hello',
+ *       flags: defineCommandFlags(helloFlags),
+ *       // ...
+ *     }]
+ *   }
+ * });
+ * ```
+ */
+export function defineCommandFlags<TFlags extends FlagSchemaDefinition>(
+  flags: TFlags
+): Array<{
+  name: string;
+  type: 'string' | 'boolean' | 'number' | 'array';
+  alias?: string;
+  default?: unknown;
+  description?: string;
+  choices?: string[];
+  required?: boolean;
+}> {
+  return Object.entries(flags).map(([name, flag]) => ({
+    name,
+    type: flag.type,
+    ...(flag.alias !== undefined && { alias: flag.alias }),
+    ...(flag.default !== undefined && { default: flag.default }),
+    ...(flag.description !== undefined && { description: flag.description }),
+    ...(flag.choices !== undefined && { choices: flag.choices }),
+    ...(flag.required !== undefined && { required: flag.required }),
+  }));
+}

package/packages/shared-command-kit/src/rest/define-handler.ts

@@ -0,0 +1,187 @@
+/**
+ * REST Handler Definition (V3)
+ *
+ * Define REST handlers compatible with plugin-runtime's runInProcess().
+ * Returns { execute } object with (ctx, input) signature.
+ *
+ * @example
+ * ```typescript
+ * import { defineHandler } from '@kb-labs/shared-command-kit';
+ *
+ * export default defineHandler({
+ *   async execute(ctx, input: { scope?: string }) {
+ *     const plan = await loadPlan(ctx.cwd);
+ *     return plan;
+ *   }
+ * });
+ * ```
+ */
+
+import type { PluginContextV3 } from '@kb-labs/plugin-contracts';
+
+/**
+ * REST input structure from route-mounter.
+ * Query params, body, and route params are separated to avoid conflicts.
+ */
+export interface RestInput<TQuery = unknown, TBody = unknown, TParams = unknown> {
+  query?: TQuery;
+  body?: TBody;
+  params?: TParams;
+}
+
+/**
+ * Handler interface expected by runInProcess().
+ */
+export interface Handler<TConfig = unknown, TInput = unknown, TOutput = unknown> {
+  /**
+   * Execute the handler
+   */
+  execute(
+    ctx: PluginContextV3<TConfig>,
+    input: TInput
+  ): Promise<TOutput>;
+}
+
+/**
+ * Handler definition options.
+ * Extensible for future features (inputSchema, middleware, etc.)
+ */
+export interface HandlerDefinition<TConfig = unknown, TInput = unknown, TOutput = unknown> {
+  /**
+   * Execute the handler.
+   * Returns data directly - no need for exitCode/CommandResult wrapper.
+   *
+   * @param ctx - Plugin context with runtime APIs (fs, fetch, env, ui, etc.)
+   * @param input - Request input (body for POST, query for GET, etc.)
+   * @returns Response data (will be serialized as JSON)
+   * @throws Error on failure (will be converted to HTTP 500)
+   */
+  execute(
+    ctx: PluginContextV3<TConfig>,
+    input: TInput
+  ): Promise<TOutput>;
+
+  // Future options (non-breaking additions):
+  // inputSchema?: ZodType<TInput>;
+  // outputSchema?: ZodType<TOutput>;
+  // middleware?: Middleware[];
+  // timeout?: number;
+}
+
+/**
+ * Define a REST handler
+ *
+ * Creates a handler object compatible with runInProcess() from plugin-runtime.
+ * The handler receives full PluginContextV3 with runtime APIs.
+ *
+ * @example
+ * ```typescript
+ * // Simple handler
+ * export default defineHandler({
+ *   async execute(ctx, input: { scope?: string }) {
+ *     const plan = await loadPlan(ctx.cwd);
+ *     return plan;
+ *   }
+ * });
+ *
+ * // With typed query parameters using RestInput
+ * import { defineHandler, type RestInput } from '@kb-labs/sdk';
+ *
+ * export default defineHandler({
+ *   async execute(ctx, input: RestInput<{ workspace?: string }>) {
+ *     const workspace = input.query?.workspace || 'root';
+ *     return { workspace };
+ *   }
+ * });
+ *
+ * // With typed query and body
+ * interface QueryParams {
+ *   workspace?: string;
+ * }
+ *
+ * interface BodyParams {
+ *   name: string;
+ *   description?: string;
+ * }
+ *
+ * export default defineHandler({
+ *   async execute(ctx, input: RestInput<QueryParams, BodyParams>) {
+ *     const workspace = input.query?.workspace || 'root';
+ *     const name = input.body?.name;
+ *     return { workspace, name };
+ *   }
+ * });
+ *
+ * // With typed generics
+ * interface GetPlanInput {
+ *   scope?: string;
+ *   includeHistory?: boolean;
+ * }
+ *
+ * interface ReleasePlan {
+ *   version: string;
+ *   packages: string[];
+ * }
+ *
+ * export default defineHandler<unknown, GetPlanInput, ReleasePlan>({
+ *   async execute(ctx, input) {
+ *     // ctx: PluginContextV3 with runtime.fs, ui, etc.
+ *     // input: GetPlanInput (typed)
+ *     // return: ReleasePlan (typed)
+ *     return await loadPlan(ctx.cwd, input.scope);
+ *   }
+ * });
+ *
+ * // Using runtime APIs
+ * export default defineHandler({
+ *   async execute(ctx, input: { path: string }) {
+ *     // File system access
+ *     const content = await ctx.runtime.fs.readFile(input.path, 'utf-8');
+ *
+ *     // Environment variables
+ *     const apiKey = ctx.runtime.env('API_KEY');
+ *
+ *     // Logging
+ *     ctx.runtime.log('info', 'Processing file', { path: input.path });
+ *
+ *     return { content, hasApiKey: !!apiKey };
+ *   }
+ * });
+ * ```
+ */
+export function defineHandler<TConfig = unknown, TInput = unknown, TOutput = unknown>(
+  definition: HandlerDefinition<TConfig, TInput, TOutput>
+): Handler<TConfig, TInput, TOutput> {
+  // Return handler object compatible with runInProcess()
+  // Currently passes through, but this wrapper enables:
+  // - Future input validation via inputSchema
+  // - Future output validation via outputSchema
+  // - Middleware execution
+  // - Logging/tracing hooks
+  // - Error normalization
+  return {
+    execute: async (ctx, input) => {
+      // Future: validate input against schema
+      // if (definition.inputSchema) {
+      //   input = definition.inputSchema.parse(input);
+      // }
+
+      // Future: run pre-middleware
+      // for (const mw of definition.middleware ?? []) {
+      //   await mw.before?.(ctx, input);
+      // }
+
+      // Future: validate output against schema
+      // if (definition.outputSchema) {
+      //   definition.outputSchema.parse(result);
+      // }
+
+      // Future: run post-middleware
+      // for (const mw of definition.middleware ?? []) {
+      //   await mw.after?.(ctx, input, result);
+      // }
+
+      return definition.execute(ctx, input);
+    },
+  };
+}

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

@@ -0,0 +1,11 @@
+/**
+ * @module @kb-labs/shared-command-kit/rest
+ * REST handler definition helpers
+ */
+
+export {
+  defineHandler,
+  type Handler,
+  type HandlerDefinition,
+  type RestInput,
+} from './define-handler.js';

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

@@ -0,0 +1,12 @@
+/**
+ * @module @kb-labs/shared-command-kit/studio
+ *
+ * Studio V2 types re-exported for convenience.
+ * Plugin authors use `@kb-labs/sdk/studio` instead.
+ */
+
+export type {
+  StudioConfig,
+  StudioPageEntry,
+  StudioMenuEntry,
+} from '@kb-labs/plugin-contracts';