@kb-labs/shared-command-kit 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1696 @@
+import { PluginContextV3, ManifestV3, PermissionSpec, JobDecl, CommandResult as CommandResult$1, HostContext, WSMessage, WSSender, WSInput } from '@kb-labs/plugin-contracts';
+export { PluginContextV3 } from '@kb-labs/plugin-contracts';
+import { FlagSchemaDefinition as FlagSchemaDefinition$1, InferFlags } from './flags/index.js';
+export { ArrayFlagSchema, BaseFlagSchema, BooleanFlagSchema, FlagSchema, FlagSchemaWithInfer, FlagType, FlagValidationError, NumberFlagSchema, SafeValidationResult, StringFlagSchema, ValidationResult, defineFlags, validateFlags, validateFlagsSafe } from './flags/index.js';
+export { AnalyticsContext, AnalyticsEvents, createAnalyticsWrapper, trackEvent, withAnalytics } from './analytics/index.js';
+export { ErrorDefinition, ErrorDefinitions, FormatErrorOptions, FormattedError, PluginError, commonErrors, defineError, formatError } from './errors/index.js';
+export { getLLMTier, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isVectorStoreAvailable, trackAnalyticsEvent, useAnalytics, useCache, useConfig, useEmbeddings, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore } from './helpers/index.js';
+import { z } from 'zod';
+export { CommandOutput } from '@kb-labs/shared-cli-ui';
+export { LLMTier, UseLLMOptions } from '@kb-labs/core-platform';
+import '@kb-labs/core-runtime';
+
+/**
+ * @module @kb-labs/shared-command-kit
+ * System Command Definition - For KB Labs official commands with full privileges
+ */
+
+/**
+ * Flag definition for Command interface
+ */
+interface FlagDefinition {
+    name: string;
+    type: 'string' | 'boolean' | 'number' | 'array';
+    alias?: string;
+    description?: string;
+    default?: unknown;
+    required?: boolean;
+    choices?: string[];
+}
+/**
+ * Command definition for system commands
+ */
+interface Command {
+    name: string;
+    describe: string;
+    longDescription?: string;
+    category?: string;
+    aliases?: string[];
+    flags?: FlagDefinition[];
+    examples?: string[];
+    run: (ctx: PluginContextV3, argv: string[], flags: Record<string, unknown>) => Promise<number>;
+}
+/**
+ * Command group definition
+ */
+interface CommandGroup {
+    name: string;
+    describe: string;
+    commands: Command[];
+}
+/**
+ * Extended command config for system commands
+ *
+ * All type parameters are optional - use them when you want type safety, skip them for simplicity.
+ *
+ * TFlags can be inferred from the flags schema, but can also be explicitly provided
+ * for better type inference in complex cases.
+ *
+ * TResult must extend CommandResult (requires ok: boolean field).
+ */
+interface SystemCommandConfig<TFlags extends FlagSchemaDefinition$1 = FlagSchemaDefinition$1, TResult extends CommandResult = CommandResult, TArgv extends readonly string[] = string[]> {
+    /** Command name (required for system commands) */
+    name: string;
+    /** Command description (required for system commands) */
+    description: string;
+    /** Long description for help */
+    longDescription?: string;
+    /** Category (defaults to 'system') */
+    category?: string;
+    /** Command aliases */
+    aliases?: string[];
+    /** Usage examples */
+    examples?: string[];
+    /** Flag schema definition - TypeScript will infer TFlags from this */
+    flags: TFlags;
+    /**
+     * Analytics configuration (legacy field, kept for backward compatibility)
+     * Use ctx.platform.analytics.track() or withAnalytics() helper instead
+     */
+    analytics?: {
+        command?: string;
+        startEvent?: string;
+        finishEvent?: string;
+        actor?: string;
+        context?: Record<string, unknown>;
+        includeFlags?: boolean;
+    };
+    /** Command handler - receives PluginContextV3 and must return TResult */
+    handler: (ctx: PluginContextV3, argv: TArgv, flags: InferFlags<TFlags>) => Promise<number | TResult> | number | TResult;
+    /** Optional formatter - receives TResult with inferred flags */
+    formatter?: (result: TResult, ctx: PluginContextV3, flags: InferFlags<TFlags>, argv?: TArgv) => void;
+}
+/**
+ * Define a system command with full privileges
+ *
+ * System commands are KB Labs official commands that run with full system access,
+ * bypassing sandbox restrictions. They are architecturally separated from plugin
+ * commands - plugins can NEVER gain system privileges.
+ *
+ * TResult is REQUIRED - every command must explicitly declare its result contract.
+ * This ensures type safety and enables future contract validation.
+ *
+ * @example
+ * ```typescript
+ * import { defineSystemCommand, type CommandResult, type FlagSchemaDefinition } from '@kb-labs/shared-command-kit';
+ *
+ * // Simple command with automatic flag type inference (RECOMMENDED)
+ * export const helloCommand = defineSystemCommand<CommandResult & { message: string }>({
+ *   name: 'hello',
+ *   description: 'Print a friendly greeting',
+ *   category: 'system',
+ *   flags: {
+ *     name: { type: 'string', description: 'Name to greet' },
+ *     json: { type: 'boolean', default: false },
+ *   } satisfies FlagSchemaDefinition, // Preserves literal types for type inference
+ *   async handler(ctx, argv, flags) {
+ *     // ctx is EnhancedCliContext (extends PluginContextV3)
+ *     // ctx.cwd - working directory (V2 promoted field)
+ *     // ctx.ui - UI output API with new convenience methods
+ *     // flags.name is inferred as string | undefined
+ *     const message = `Hello, ${flags.name || 'World'}!`;
+ *
+ *     // UI output (CLI only, no-op in REST/Workflow)
+ *     if (!flags.json) {
+ *       if (ctx.ui?.success) {
+ *         ctx.ui.success('Greeting', [
+ *           { items: [message] },
+ *         ]);
+ *       }
+ *     } else {
+ *       ctx.ui?.json({ message });
+ *     }
+ *
+ *     return { ok: true, message };
+ *   },
+ * });
+ *
+ * // Command with explicit result type and automatic flag inference
+ * type WorkflowListResult = CommandResult & {
+ *   workflows: Array<{ id: string }>;
+ *   total: number;
+ * };
+ *
+ * export const wfList = defineSystemCommand<WorkflowListResult>({
+ *   name: 'list',
+ *   description: 'List workflows',
+ *   flags: {
+ *     source: { type: 'string', default: 'all' },
+ *     tag: { type: 'string' },
+ *     json: { type: 'boolean', default: false },
+ *   } satisfies FlagSchemaDefinition, // TypeScript infers flag types automatically
+ *   async handler(ctx, argv, flags) {
+ *     // flags.source is inferred as string
+ *     // flags.tag is inferred as string | undefined
+ *     // flags.json is inferred as boolean
+ *     const workflows = await listWorkflows(flags.source, flags.tag);
+ *
+ *     // UI output (new convenience methods)
+ *     if (!flags.json) {
+ *       if (ctx.ui?.success) {
+ *         ctx.ui.success('Workflows', [
+ *           { header: 'Summary', items: [`Total: ${workflows.length}`, `Source: ${flags.source}`] },
+ *           { items: workflows.map(w => `• ${w.id}`) },
+ *         ]);
+ *       }
+ *     } else {
+ *       ctx.ui?.json({ workflows, total: workflows.length });
+ *     }
+ *
+ *     return { ok: true, workflows, total: workflows.length };
+ *   },
+ * });
+ *
+ * // Command with explicit flag types (for complex cases)
+ * export const wfRun = defineSystemCommand<
+ *   { 'workflow-id': { type: 'string'; required: true } },
+ *   CommandResult & { run: WorkflowRun }
+ * >({
+ *   name: 'run',
+ *   description: 'Execute a workflow',
+ *   flags: {
+ *     'workflow-id': { type: 'string', required: true },
+ *   },
+ *   async handler(ctx, argv, flags) {
+ *     // flags['workflow-id'] is inferred as string (required)
+ *
+ *     // Progress tracking (CLI only, no-op in REST/Workflow)
+ *     ctx.ui?.startProgress('running', 'Starting workflow...');
+ *     const run = await executeWorkflow(flags['workflow-id']);
+ *     ctx.ui?.completeProgress('running', 'Workflow started!');
+ *
+ *     return { ok: true, run };
+ *   },
+ * });
+ *
+ * // Note: System commands support all UI convenience methods:
+ * // - ctx.ui.success() / showError() / warning() / info() - Result display with sideBox
+ * // - ctx.ui.startProgress() / completeProgress() / failProgress() - Progress tracking
+ * // - ctx.ui.table() / keyValue() / list() - Low-level formatting
+ * // All UI methods are CLI-only and no-op in REST/Workflow contexts
+ * ```
+ */
+declare function defineSystemCommand<TFlags extends FlagSchemaDefinition$1, TResult extends CommandResult = CommandResult, TArgv extends readonly string[] = string[]>(config: SystemCommandConfig<TFlags, TResult, TArgv>): Command;
+/**
+ * Create a system command group
+ *
+ * Groups organize related system commands for better help organization
+ * and registration.
+ *
+ * @example
+ * ```typescript
+ * export const systemInfoGroup = defineSystemCommandGroup(
+ *   'system:info',
+ *   'System information commands',
+ *   [helloCommand, versionCommand, healthCommand]
+ * );
+ * ```
+ */
+declare function defineSystemCommandGroup(name: string, describe: string, commands: Command[]): CommandGroup;
+
+/**
+ * Manifest definition helpers
+ * @module @kb-labs/shared-command-kit/manifest
+ */
+
+/**
+ * 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
+ */
+declare function defineManifest<TContracts = unknown>(manifest: ManifestV3): ManifestV3;
+/**
+ * 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),
+ *       // ...
+ *     }]
+ *   }
+ * });
+ * ```
+ */
+declare 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;
+}>;
+
+/**
+ * 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 }),
+ * });
+ * ```
+ */
+
+/**
+ * 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()
+ * ```
+ */
+declare function cwd(): z.ZodOptional<z.ZodString>;
+/**
+ * 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)
+ * ```
+ */
+declare function scopeId(): z.ZodString;
+/**
+ * Text string with optional length constraints
+ *
+ * @example
+ * ```typescript
+ * schema.text({ min: 1, max: 10000 })
+ * // Equivalent to: z.string().min(1).max(10000)
+ * ```
+ */
+declare function text(options?: {
+    min?: number;
+    max?: number;
+    default?: string;
+}): z.ZodString | z.ZodDefault<z.ZodString>;
+/**
+ * Positive integer with optional constraints
+ *
+ * @example
+ * ```typescript
+ * schema.positiveInt({ max: 100, default: 10 })
+ * // Equivalent to: z.number().int().positive().max(100).default(10)
+ * ```
+ */
+declare function positiveInt(options?: {
+    min?: number;
+    max?: number;
+    default?: number;
+}): z.ZodNumber | z.ZodDefault<z.ZodNumber>;
+/**
+ * Non-negative integer (0 or positive)
+ *
+ * @example
+ * ```typescript
+ * schema.nonNegativeInt({ max: 100 })
+ * // Equivalent to: z.number().int().min(0).max(100)
+ * ```
+ */
+declare function nonNegativeInt(options?: {
+    max?: number;
+    default?: number;
+}): z.ZodNumber | z.ZodDefault<z.ZodNumber>;
+/**
+ * Enum with optional default value
+ *
+ * @example
+ * ```typescript
+ * schema.enum(['instant', 'auto', 'thinking'], { default: 'auto' })
+ * // Equivalent to: z.enum(['instant', 'auto', 'thinking']).default('auto')
+ * ```
+ */
+declare function enumSchema<T extends [string, ...string[]]>(values: T, options?: {
+    default?: T[number];
+}): z.ZodDefault<z.ZodEnum<T>> | z.ZodEnum<T>;
+/**
+ * Plugin ID (@kb-labs/package-name format)
+ *
+ * @example
+ * ```typescript
+ * schema.pluginId()
+ * // Matches: @kb-labs/mind, @kb-labs/workflow, etc.
+ * ```
+ */
+declare function pluginId(): z.ZodString;
+/**
+ * Command ID (plugin:command format)
+ *
+ * @example
+ * ```typescript
+ * schema.commandId()
+ * // Matches: mind:query, workflow:run, etc.
+ * ```
+ */
+declare function commandId(): z.ZodString;
+/**
+ * Artifact ID (plugin.artifact.id format)
+ *
+ * @example
+ * ```typescript
+ * schema.artifactId()
+ * // Matches: mind.index.vector, workflow.run.result, etc.
+ * ```
+ */
+declare function artifactId(): z.ZodString;
+/**
+ * File path (string)
+ * Optional with default to undefined
+ *
+ * @example
+ * ```typescript
+ * schema.filePath()
+ * // Equivalent to: z.string()
+ * ```
+ */
+declare function filePath(options?: {
+    optional?: boolean;
+}): z.ZodString | z.ZodOptional<z.ZodString>;
+/**
+ * URL string
+ *
+ * @example
+ * ```typescript
+ * schema.url()
+ * // Equivalent to: z.string().url()
+ * ```
+ */
+declare function url(options?: {
+    optional?: boolean;
+}): z.ZodString | z.ZodOptional<z.ZodString>;
+/**
+ * Email string
+ *
+ * @example
+ * ```typescript
+ * schema.email()
+ * // Equivalent to: z.string().email()
+ * ```
+ */
+declare function email(options?: {
+    optional?: boolean;
+}): z.ZodString | z.ZodOptional<z.ZodString>;
+/**
+ * UUID string
+ *
+ * @example
+ * ```typescript
+ * schema.uuid()
+ * // Equivalent to: z.string().uuid()
+ * ```
+ */
+declare function uuid(options?: {
+    optional?: boolean;
+}): z.ZodString | z.ZodOptional<z.ZodString>;
+/**
+ * ISO datetime string
+ *
+ * @example
+ * ```typescript
+ * schema.datetime()
+ * // Equivalent to: z.string().datetime()
+ * ```
+ */
+declare function datetime(options?: {
+    optional?: boolean;
+}): z.ZodString | z.ZodOptional<z.ZodString>;
+/**
+ * JSON object (any valid JSON object)
+ *
+ * @example
+ * ```typescript
+ * schema.json()
+ * // Equivalent to: z.record(z.unknown())
+ * ```
+ */
+declare function json(): z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/**
+ * Boolean with optional default
+ *
+ * @example
+ * ```typescript
+ * schema.boolean({ default: false })
+ * // Equivalent to: z.boolean().default(false)
+ * ```
+ */
+declare function boolean(options?: {
+    default?: boolean;
+}): z.ZodBoolean | z.ZodDefault<z.ZodBoolean>;
+/**
+ * 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)
+ * ```
+ */
+declare function array<T extends z.ZodTypeAny>(itemSchema: T, options?: {
+    min?: number;
+    max?: number;
+}): z.ZodArray<T, "many">;
+/**
+ * Object schema builder (alias for z.object)
+ *
+ * @example
+ * ```typescript
+ * schema.object({ name: z.string() })
+ * // Equivalent to: z.object({ name: z.string() })
+ * ```
+ */
+declare function object<T extends z.ZodRawShape>(shape: T): z.ZodObject<T, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<T>, any> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never, z.baseObjectInputType<T> extends infer T_2 ? { [k_1 in keyof T_2]: T_2[k_1]; } : never>;
+/**
+ * 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 }),
+ * });
+ * ```
+ */
+declare const schema: {
+    cwd: typeof cwd;
+    scopeId: typeof scopeId;
+    pluginId: typeof pluginId;
+    commandId: typeof commandId;
+    artifactId: typeof artifactId;
+    filePath: typeof filePath;
+    text: typeof text;
+    url: typeof url;
+    email: typeof email;
+    uuid: typeof uuid;
+    datetime: typeof datetime;
+    positiveInt: typeof positiveInt;
+    nonNegativeInt: typeof nonNegativeInt;
+    enum: typeof enumSchema;
+    boolean: typeof boolean;
+    json: typeof json;
+    array: typeof array;
+    object: typeof object;
+};
+
+/**
+ * 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;
+ *   }
+ * });
+ * ```
+ */
+
+/**
+ * REST input structure from route-mounter.
+ * Query params, body, and route params are separated to avoid conflicts.
+ */
+interface RestInput<TQuery = unknown, TBody = unknown, TParams = unknown> {
+    query?: TQuery;
+    body?: TBody;
+    params?: TParams;
+}
+/**
+ * Handler interface expected by runInProcess().
+ */
+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.)
+ */
+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>;
+}
+/**
+ * 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 };
+ *   }
+ * });
+ * ```
+ */
+declare function defineHandler<TConfig = unknown, TInput = unknown, TOutput = unknown>(definition: HandlerDefinition<TConfig, TInput, TOutput>): Handler<TConfig, TInput, TOutput>;
+
+/**
+ * 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 };
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Lifecycle handler context
+ */
+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
+ */
+interface WorkspaceConfig {
+    /** Directories to create (relative to outdir or absolute) */
+    directories?: string[];
+    /** Files to create with content */
+    files?: Record<string, string>;
+}
+/**
+ * Config file updates
+ */
+type ConfigUpdates = Record<string, Record<string, unknown>>;
+/**
+ * Setup handler definition
+ */
+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
+ */
+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[]>;
+    /** Custom destroy logic (optional) */
+    handler?: (ctx: LifecycleContext) => Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+}
+/**
+ * Setup handler result
+ */
+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 };
+ *   },
+ * });
+ * ```
+ */
+declare function defineSetupHandler(definition: SetupHandlerDefinition): (ctx: LifecycleContext) => Promise<SetupResult>;
+/**
+ * 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
+ *   },
+ * });
+ * ```
+ */
+declare function defineDestroyHandler(definition: DestroyHandlerDefinition): (ctx: LifecycleContext) => Promise<SetupResult>;
+
+/**
+ * Job definition helpers
+ * @module @kb-labs/shared-command-kit/jobs
+ */
+
+/**
+ * Job input passed to handler at runtime
+ */
+interface JobInput {
+    /** Job identifier */
+    jobId: string;
+    /** When the job was scheduled to execute */
+    executedAt: Date;
+    /** How many times this job has run */
+    runCount: number;
+}
+/**
+ * Job handler function signature
+ *
+ * @template TInput - Custom input type (extends JobInput)
+ * @template TOutput - Handler return type
+ */
+type JobHandler<TInput extends JobInput = JobInput, TOutput = {
+    ok: boolean;
+    [key: string]: unknown;
+}> = (input: TInput, ctx: PluginContextV3) => Promise<TOutput>;
+/**
+ * Job definition configuration
+ *
+ * Combines JobDecl manifest fields with the actual handler function
+ * for type-safe job creation.
+ */
+interface JobDefinition<TInput extends JobInput = JobInput, TOutput = {
+    ok: boolean;
+    [key: string]: unknown;
+}> {
+    /** Unique job identifier within plugin (e.g., 'auto-index') */
+    id: string;
+    /**
+     * Cron schedule expression
+     * Supports shortcuts (@hourly, @daily, @weekly, @monthly, @yearly) and standard cron format
+     */
+    schedule: string;
+    /** Human-readable description */
+    describe?: string;
+    /** Whether job is enabled (default: true) */
+    enabled?: boolean;
+    /** Job priority (1-10, default: 5, higher = more important) */
+    priority?: number;
+    /** Execution timeout in milliseconds (default: 60000 = 1min) */
+    timeout?: number;
+    /** Number of retry attempts on failure (default: 2) */
+    retries?: number;
+    /** Tags for filtering and organization */
+    tags?: string[];
+    /** Permissions for job execution (filesystem, network, quotas) */
+    permissions?: PermissionSpec;
+    /** Job handler function */
+    handler: JobHandler<TInput, TOutput>;
+}
+/**
+ * Defined job object with manifest conversion
+ */
+interface DefinedJob<TInput extends JobInput = JobInput, TOutput = {
+    ok: boolean;
+    [key: string]: unknown;
+}> {
+    /** Job configuration */
+    readonly config: Omit<JobDefinition<TInput, TOutput>, 'handler'> & {
+        handler: string;
+    };
+    /** Job handler function */
+    readonly handler: JobHandler<TInput, TOutput>;
+    /** Convert to manifest JobDecl */
+    toManifest(handlerPath: string): JobDecl;
+}
+/**
+ * Define a type-safe job with handler
+ *
+ * This helper provides compile-time type safety for job definitions
+ * and allows sharing the same handler function between manifest and runtime.
+ *
+ * The handler function can be exported from a separate file and the manifest
+ * references it via the handler path.
+ *
+ * See plugin-template/src/jobs/hello.ts for a complete example.
+ *
+ * @param definition - Job configuration with handler
+ * @returns DefinedJob object with handler and manifest conversion
+ */
+declare function defineJob<TInput extends JobInput = JobInput, TOutput = {
+    ok: boolean;
+    [key: string]: unknown;
+}>(definition: JobDefinition<TInput, TOutput>): DefinedJob<TInput, TOutput>;
+
+/**
+ * Define a CLI command handler
+ */
+
+/**
+ * CLI input wrapper - V3 plugin system wraps flags in this structure
+ */
+interface CLIInput<TFlags = unknown> {
+    flags: TFlags;
+    argv: string[];
+}
+interface CommandHandlerV3<TConfig = unknown, TInput = unknown, TResult = unknown> {
+    /**
+     * Execute the command
+     */
+    execute(context: PluginContextV3<TConfig>, input: TInput): Promise<CommandResult$1<TResult>> | CommandResult$1<TResult>;
+    /**
+     * Optional cleanup - called after execute completes
+     */
+    cleanup?(): Promise<void> | void;
+}
+interface CommandDefinition<TConfig = unknown, TInput = unknown, TResult = unknown> {
+    /**
+     * Command ID (e.g., "my-plugin:greet")
+     */
+    id: string;
+    /**
+     * Command description
+     */
+    description?: string;
+    /**
+     * Handler implementation
+     */
+    handler: CommandHandlerV3<TConfig, TInput, TResult>;
+    /**
+     * Optional input schema validation (future: use Zod/JSON Schema)
+     */
+    schema?: unknown;
+}
+/**
+ * Define a CLI command
+ *
+ * For CLI commands, use CLIInput<TFlags> as TInput type to get proper typing
+ * for the V3 plugin system's { flags, argv } structure.
+ *
+ * @example
+ * ```typescript
+ * interface GreetFlags {
+ *   name?: string;
+ * }
+ *
+ * interface GreetResult {
+ *   message: string;
+ *   target: string;
+ * }
+ *
+ * export default defineCommand<unknown, CLIInput<GreetFlags>, GreetResult>({
+ *   id: 'greet',
+ *   description: 'Greet a user',
+ *   handler: {
+ *     async execute(context, input) {
+ *       const target = input.flags.name || 'World';
+ *       context.ui.success(`Hello, ${target}!`);
+ *
+ *       return {
+ *         exitCode: 0,
+ *         result: { message: `Hello, ${target}!`, target },
+ *         meta: { version: 'v3' }
+ *       };
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function defineCommand<TConfig = unknown, TInput = unknown, TResult = unknown>(definition: CommandDefinition<TConfig, TInput, TResult>): CommandHandlerV3<TConfig, TInput, TResult>;
+/**
+ * Type guard to check if host context is CLI
+ */
+declare function isCLIHost(hostContext: HostContext): hostContext is Extract<HostContext, {
+    host: 'cli';
+}>;
+
+/**
+ * Define a REST API route handler
+ */
+
+interface RouteHandler<TConfig = unknown, TInput = unknown> {
+    /**
+     * Execute the route handler
+     */
+    execute(context: PluginContextV3<TConfig>, input: TInput): Promise<CommandResult$1 | void> | CommandResult$1 | void;
+    /**
+     * Optional cleanup - called after execute completes
+     */
+    cleanup?(): Promise<void> | void;
+}
+interface RouteDefinition<TConfig = unknown, TInput = unknown> {
+    /**
+     * Route path (e.g., "/api/greet")
+     */
+    path: string;
+    /**
+     * HTTP method (e.g., "GET", "POST")
+     */
+    method: string;
+    /**
+     * Route description
+     */
+    description?: string;
+    /**
+     * Handler implementation
+     */
+    handler: RouteHandler<TConfig, TInput>;
+    /**
+     * Optional input schema validation (future: use Zod/JSON Schema)
+     */
+    schema?: unknown;
+}
+/**
+ * Define a REST API route
+ *
+ * @example
+ * ```typescript
+ * export default defineRoute({
+ *   path: '/greet',
+ *   method: 'POST',
+ *   description: 'Greet a user',
+ *   handler: {
+ *     async execute(context, input: { name: string }) {
+ *       return {
+ *         data: { message: `Hello, ${input.name}!` },
+ *         exitCode: 0,
+ *       };
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function defineRoute<TConfig = unknown, TInput = unknown>(definition: RouteDefinition<TConfig, TInput>): RouteHandler<TConfig, TInput>;
+/**
+ * Type guard to check if host context is REST
+ */
+declare function isRESTHost(hostContext: HostContext): hostContext is Extract<HostContext, {
+    host: 'rest';
+}>;
+
+/**
+ * Define a webhook handler
+ */
+
+interface WebhookHandler<TConfig = unknown, TInput = unknown> {
+    /**
+     * Execute the webhook handler
+     */
+    execute(context: PluginContextV3<TConfig>, input: TInput): Promise<CommandResult$1 | void> | CommandResult$1 | void;
+    /**
+     * Optional cleanup - called after execute completes
+     */
+    cleanup?(): Promise<void> | void;
+}
+interface WebhookDefinition<TConfig = unknown, TInput = unknown> {
+    /**
+     * Event name (e.g., "github:push", "stripe:payment.success")
+     */
+    event: string;
+    /**
+     * Webhook description
+     */
+    description?: string;
+    /**
+     * Handler implementation
+     */
+    handler: WebhookHandler<TConfig, TInput>;
+    /**
+     * Optional input schema validation (future: use Zod/JSON Schema)
+     */
+    schema?: unknown;
+}
+/**
+ * Define a webhook handler
+ *
+ * @example
+ * ```typescript
+ * export default defineWebhook({
+ *   event: 'github:push',
+ *   description: 'Handle GitHub push events',
+ *   handler: {
+ *     async execute(context, input: { ref: string; commits: any[] }) {
+ *       const { event, source, payload } = context.hostContext as WebhookHost;
+ *
+ *       context.ui.info(`Received ${event} from ${source}`);
+ *
+ *       // Process webhook...
+ *
+ *       return {
+ *         data: { processed: true },
+ *         exitCode: 0,
+ *       };
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function defineWebhook<TConfig = unknown, TInput = unknown>(definition: WebhookDefinition<TConfig, TInput>): WebhookHandler<TConfig, TInput>;
+/**
+ * Type guard to check if host context is webhook
+ */
+declare function isWebhookHost(hostContext: HostContext): hostContext is Extract<HostContext, {
+    host: 'webhook';
+}>;
+
+/**
+ * Define a WebSocket channel handler with enhanced DX
+ *
+ * Provides type-safe WebSocket handlers following the same pattern as defineCommand, defineRoute, etc.
+ */
+
+/**
+ * Typed sender with message builders
+ *
+ * Wraps WSSender to provide generic type support for outgoing messages.
+ */
+interface TypedSender<TOutgoing = WSMessage> extends Omit<WSSender, 'send' | 'broadcast' | 'sendTo'> {
+    /** Send typed message to this client */
+    send(message: TOutgoing): Promise<void>;
+    /** Broadcast typed message to all clients in channel */
+    broadcast(message: TOutgoing, excludeSelf?: boolean): Promise<void>;
+    /** Send typed message to specific connections */
+    sendTo(connectionIds: string[], message: TOutgoing): Promise<void>;
+    /** Original WSSender methods for raw messages */
+    raw: WSSender;
+}
+/**
+ * WebSocket handler with typed messages
+ */
+interface WebSocketHandler<TConfig = unknown, TIncoming = unknown, TOutgoing = WSMessage> {
+    /**
+     * Called when client connects
+     */
+    onConnect?(context: PluginContextV3<TConfig>, sender: TypedSender<TOutgoing>): Promise<void> | void;
+    /**
+     * Called when message received from client
+     */
+    onMessage?(context: PluginContextV3<TConfig>, message: TIncoming, sender: TypedSender<TOutgoing>): Promise<void> | void;
+    /**
+     * Called when client disconnects
+     */
+    onDisconnect?(context: PluginContextV3<TConfig>, code: number, reason: string): Promise<void> | void;
+    /**
+     * Called on error
+     */
+    onError?(context: PluginContextV3<TConfig>, error: Error, sender: TypedSender<TOutgoing>): Promise<void> | void;
+    /**
+     * Optional cleanup - called after any lifecycle event
+     */
+    cleanup?(): Promise<void> | void;
+}
+interface WebSocketDefinition<TConfig = unknown, TIncoming = unknown, TOutgoing = WSMessage> {
+    /**
+     * Channel path (e.g., "/live", "/chat")
+     */
+    path: string;
+    /**
+     * Channel description
+     */
+    description?: string;
+    /**
+     * Handler implementation
+     */
+    handler: WebSocketHandler<TConfig, TIncoming, TOutgoing>;
+    /**
+     * Optional message schema validation (future: use Zod/JSON Schema)
+     */
+    schema?: unknown;
+}
+/**
+ * Define a WebSocket channel handler
+ *
+ * @example Basic usage
+ * ```typescript
+ * export default defineWebSocket({
+ *   path: '/chat',
+ *   handler: {
+ *     async onConnect(ctx, sender) {
+ *       await sender.send({ type: 'ready', payload: {}, timestamp: Date.now() });
+ *     },
+ *     async onMessage(ctx, message, sender) {
+ *       console.log('Received:', message);
+ *     },
+ *   }
+ * });
+ * ```
+ *
+ * @example With typed messages
+ * ```typescript
+ * interface IncomingMsg {
+ *   type: 'start' | 'stop';
+ *   payload: { scope?: string };
+ * }
+ *
+ * interface OutgoingMsg {
+ *   type: 'progress' | 'complete';
+ *   payload: { progress: number; message: string };
+ * }
+ *
+ * export default defineWebSocket<unknown, IncomingMsg, OutgoingMsg>({
+ *   path: '/live',
+ *   handler: {
+ *     async onMessage(ctx, message, sender) {
+ *       if (message.type === 'start') {
+ *         await sender.send({
+ *           type: 'progress',
+ *           payload: { progress: 50, message: 'Processing...' },
+ *         });
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example With message router (advanced pattern matching)
+ * ```typescript
+ * import { defineMessage, MessageRouter } from '@kb-labs/sdk';
+ *
+ * // Define message types
+ * const StartMsg = defineMessage<{ scope?: string }>('start');
+ * const StopMsg = defineMessage<{}>('stop');
+ *
+ * // Create outgoing message builders
+ * const ProgressMsg = defineMessage<{ phase: string; progress: number }>('progress');
+ * const CompleteMsg = defineMessage<{ commits: any[] }>('complete');
+ *
+ * export default defineWebSocket({
+ *   path: '/live',
+ *   handler: {
+ *     async onMessage(ctx, message, sender) {
+ *       const router = new MessageRouter()
+ *         .on(StartMsg, async (ctx, payload, sender) => {
+ *           await sender.send(ProgressMsg.create({
+ *             phase: 'analyzing',
+ *             progress: 0,
+ *           }));
+ *         })
+ *         .on(StopMsg, async (ctx, payload, sender) => {
+ *           sender.close(1000, 'Stopped by user');
+ *         });
+ *
+ *       await router.handle(ctx, message, sender.raw);
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function defineWebSocket<TConfig = unknown, TIncoming = unknown, TOutgoing = WSMessage>(definition: WebSocketDefinition<TConfig, TIncoming, TOutgoing>): {
+    execute(context: PluginContextV3<TConfig>, input: WSInput): Promise<CommandResult$1 | void>;
+};
+/**
+ * Type guard to check if host context is WebSocket
+ */
+declare function isWSHost(hostContext: HostContext): hostContext is Extract<HostContext, {
+    host: 'ws';
+}>;
+
+/**
+ * Define a workflow action handler
+ */
+
+interface ActionHandler<TConfig = unknown, TInput = unknown> {
+    /**
+     * Execute the workflow action
+     */
+    execute(context: PluginContextV3<TConfig>, input: TInput): Promise<CommandResult$1 | void> | CommandResult$1 | void;
+    /**
+     * Optional cleanup - called after execute completes
+     */
+    cleanup?(): Promise<void> | void;
+}
+interface ActionDefinition<TConfig = unknown, TInput = unknown> {
+    /**
+     * Action ID (e.g., "send-email")
+     */
+    id: string;
+    /**
+     * Action description
+     */
+    description?: string;
+    /**
+     * Handler implementation
+     */
+    handler: ActionHandler<TConfig, TInput>;
+    /**
+     * Optional input schema validation (future: use Zod/JSON Schema)
+     */
+    schema?: unknown;
+}
+/**
+ * Define a workflow action
+ *
+ * @example
+ * ```typescript
+ * export default defineAction({
+ *   id: 'send-email',
+ *   description: 'Send an email notification',
+ *   handler: {
+ *     async execute(context, input: { to: string; subject: string; body: string }) {
+ *       // Access workflow context
+ *       const { workflowId, runId, stepId } = context.hostContext as WorkflowHost;
+ *
+ *       context.ui.info(`Sending email in workflow ${workflowId}`);
+ *
+ *       // Send email...
+ *
+ *       return {
+ *         data: { sent: true, messageId: '123' },
+ *         exitCode: 0,
+ *       };
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function defineAction<TConfig = unknown, TInput = unknown>(definition: ActionDefinition<TConfig, TInput>): ActionHandler<TConfig, TInput>;
+/**
+ * Type guard to check if host context is workflow
+ */
+declare function isWorkflowHost(hostContext: HostContext): hostContext is Extract<HostContext, {
+    host: 'workflow';
+}>;
+
+/**
+ * Enhanced WebSocket types for better DX
+ *
+ * Provides type-safe message builders and pattern matching utilities.
+ */
+
+/**
+ * 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 }
+ * ```
+ */
+declare class MessageBuilder<TPayload = unknown> {
+    private type;
+    constructor(type: string);
+    /**
+     * Create message with payload
+     */
+    create(payload: TPayload, messageId?: string): WSMessage;
+    /**
+     * Match against incoming message type (type guard)
+     */
+    is(message: WSMessage): message is WSMessage & {
+        payload: TPayload;
+    };
+}
+/**
+ * Helper to define typed messages
+ *
+ * @example
+ * ```typescript
+ * const StartMsg = defineMessage<{ scope?: string }>('start');
+ * const ProgressMsg = defineMessage<{ phase: string; progress: number }>('progress');
+ * ```
+ */
+declare function defineMessage<TPayload = unknown>(type: string): MessageBuilder<TPayload>;
+/**
+ * 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);
+ * ```
+ */
+declare class MessageRouter<TConfig = unknown> {
+    private handlers;
+    /**
+     * Register message handler
+     */
+    on<TPayload>(message: MessageBuilder<TPayload>, handler: (ctx: PluginContextV3<TConfig>, payload: TPayload, sender: WSSender) => Promise<void> | void): this;
+    /**
+     * Handle incoming message
+     *
+     * @returns true if message was handled, false otherwise
+     */
+    handle(ctx: PluginContextV3<TConfig>, message: WSMessage, sender: WSSender): Promise<boolean>;
+}
+
+/**
+ * @module @kb-labs/shared-command-kit
+ * Command Kit - High-level API and utilities for building CLI commands
+ */
+
+/**
+ * Command execution status
+ */
+type CommandStatus = 'success' | 'failed' | 'error' | 'cancelled' | 'skipped' | 'warning' | 'info';
+/**
+ * Helper types for command results (optional - use when convenient)
+ *
+ * These types make it easier to define command results without repeating `CommandResult &`.
+ * They are completely optional - you can still use `CommandResult & { ... }` directly.
+ *
+ * @example
+ * ```typescript
+ * // Using helper types (optional)
+ * type MyResult = SuccessResult<{ items: Item[]; total: number }>;
+ *
+ * // Direct usage (also works)
+ * type MyResult = CommandResult & { ok: true; items: Item[]; total: number };
+ * ```
+ */
+type SuccessResult<T extends Record<string, unknown> = Record<string, never>> = CommandResult & {
+    ok: true;
+} & T;
+type ErrorResult<T extends Record<string, unknown> = Record<string, never>> = CommandResult & {
+    ok: false;
+    error: string;
+} & T;
+type ResultWith<T extends Record<string, unknown>> = CommandResult & T;
+/**
+ * Base command result contract - all command results must extend this
+ *
+ * This defines the minimal contract that every command must fulfill.
+ * Every command MUST explicitly declare its result type via generic TResult parameter.
+ *
+ * Required fields:
+ * - `ok: boolean` - execution success status
+ *
+ * Recommended fields:
+ * - `error?: string` - error message when ok === false
+ * - `status?: CommandStatus` - execution status (auto-inferred if not provided)
+ *
+ * Additional fields should be added via generic TResult type parameter.
+ *
+ * @example
+ * ```typescript
+ * // Minimal result (not recommended - use explicit type)
+ * type MyResult = CommandResult; // { ok: boolean; error?: string; status?: CommandStatus }
+ *
+ * // Extended result with custom fields (RECOMMENDED)
+ * type WorkflowRunResult = CommandResult & {
+ *   run: WorkflowRun;
+ *   timingMs: number;
+ * };
+ *
+ * type ListResult = CommandResult & {
+ *   items: Item[];
+ *   total: number;
+ * };
+ * ```
+ */
+type CommandResult = {
+    /** Whether the command executed successfully - REQUIRED */
+    ok: boolean;
+    /** Error message if ok === false - RECOMMENDED for error cases */
+    error?: string;
+    /** Execution status - automatically inferred from ok if not provided */
+    status?: CommandStatus;
+};
+/**
+ * Command handler function signature
+ *
+ * TConfig is the product configuration type (auto-loaded from kb.config.json)
+ * TEnv is the environment variables type (validated at runtime)
+ * TResult must extend CommandResult ({ ok: boolean }) and represents the contract
+ * for what the command returns. This ensures type safety and enables future contract
+ * validation.
+ *
+ * TArgv is optional - by default it's `string[]`, but you can provide a tuple type
+ * for strict argument typing if needed.
+ *
+ * @example
+ * ```typescript
+ * // Default: argv is string[]
+ * handler: (ctx, argv, flags) => { ... }
+ *
+ * // With typed config
+ * handler: (ctx, argv, flags) => {
+ *   ctx.config?.llmProvider // TypeScript knows the config type
+ * }
+ *
+ * // With typed env
+ * handler: (ctx, argv, flags) => {
+ *   ctx.env.OPENAI_API_KEY // TypeScript knows it's a string
+ * }
+ *
+ * // Strict typing: argv is tuple ['workflow-id', ...string[]]
+ * handler: (ctx, argv: ['workflow-id', ...string[]], flags) => {
+ *   const workflowId = argv[0]; // TypeScript knows it's 'workflow-id'
+ * }
+ * ```
+ */
+type CommandHandler<_TConfig = any, TFlags extends Record<string, unknown> = Record<string, unknown>, TResult extends CommandResult = CommandResult, TArgv extends readonly string[] = string[], _TEnv = Record<string, string | undefined>> = (ctx: PluginContextV3, argv: TArgv, flags: TFlags) => Promise<number | TResult> | number | TResult;
+/**
+ * Command formatter function
+ *
+ * All type parameters are optional with defaults - same as CommandHandler.
+ * Use explicit types when you want type safety, skip them for simplicity.
+ *
+ * @example
+ * ```typescript
+ * // Default: argv is string[]
+ * formatter: (result, ctx, flags) => { ... }
+ *
+ * // With typed config
+ * formatter: (result, ctx, flags) => {
+ *   ctx.config?.llmProvider // TypeScript knows the config type
+ * }
+ *
+ * // With typed env
+ * formatter: (result, ctx, flags) => {
+ *   ctx.env.OPENAI_API_KEY // TypeScript knows it's a string
+ * }
+ *
+ * // Strict typing: argv is tuple ['workflow-id', ...string[]]
+ * formatter: (result, ctx, flags, argv: ['workflow-id', ...string[]]) => {
+ *   const workflowId = argv[0]; // TypeScript knows it's 'workflow-id'
+ * }
+ * ```
+ */
+type CommandFormatter<_TConfig = any, TFlags extends Record<string, unknown> = Record<string, unknown>, TResult extends CommandResult = CommandResult, TArgv extends readonly string[] = string[], _TEnv = Record<string, string | undefined>> = (result: TResult, ctx: PluginContextV3, flags: TFlags, argv?: TArgv) => void;
+/**
+ * Command configuration
+ *
+ * All type parameters are optional with sensible defaults:
+ * - TConfig defaults to any (product config type)
+ * - TFlags defaults to FlagSchemaDefinition (flags are Record<string, unknown>)
+ * - TResult defaults to CommandResult (basic { ok: boolean })
+ * - TArgv defaults to string[] (arguments are string[])
+ * - TEnv defaults to Record<string, string | undefined> (process.env)
+ *
+ * Use explicit types when you want better type safety, but everything works without them.
+ *
+ * @example
+ * ```typescript
+ * // Default: argv is string[]
+ * const cmd = defineCommand({
+ *   handler: (ctx, argv, flags) => { ... }
+ * });
+ *
+ * // Simple usage with flags and result only (RECOMMENDED)
+ * const cmd = defineCommand<MyFlags, MyResult>({
+ *   handler: (ctx, argv, flags) => {
+ *     // flags are typed as InferFlags<MyFlags>
+ *     return { ok: true, ...result };
+ *   }
+ * });
+ *
+ * // With typed config (third parameter)
+ * type MindConfig = { llmProvider: string; maxTokens: number };
+ * const cmd = defineCommand<Flags, Result, MindConfig>({
+ *   handler: (ctx, argv, flags) => {
+ *     ctx.config?.llmProvider // TypeScript knows it's a string
+ *   }
+ * });
+ *
+ * // With typed env (fifth parameter)
+ * type Env = { OPENAI_API_KEY: string; DEBUG?: string };
+ * const cmd = defineCommand<Flags, Result, Config, Argv, Env>({
+ *   handler: (ctx, argv, flags) => {
+ *     ctx.env.OPENAI_API_KEY // string (validated!)
+ *   }
+ * });
+ *
+ * // Strict typing: argv is tuple ['workflow-id', ...string[]]
+ * const cmd = defineCommand<Flags, Result, Config, ['workflow-id', ...string[]]>({
+ *   handler: (ctx, argv, flags) => {
+ *     const workflowId = argv[0]; // TypeScript knows it's 'workflow-id'
+ *   }
+ * });
+ * ```
+ */
+interface CommandConfig<TFlags extends FlagSchemaDefinition$1 = FlagSchemaDefinition$1, TResult extends CommandResult = CommandResult, TConfig = any, TArgv extends readonly string[] = string[], TEnv = Record<string, string | undefined>> {
+    /** Command name (for logging) */
+    name?: string;
+    /** Flag schema definition */
+    flags: TFlags;
+    /**
+     * Analytics configuration (legacy field, kept for backward compatibility)
+     * Use ctx.platform.analytics.track() or withAnalytics() helper instead
+     */
+    analytics?: {
+        command?: string;
+        startEvent?: string;
+        finishEvent?: string;
+        actor?: string;
+        context?: Record<string, unknown>;
+        includeFlags?: boolean;
+    };
+    /**
+     * Optional environment variable schema for validation.
+     * If provided, required env vars will be validated at runtime.
+     *
+     * @example
+     * ```typescript
+     * env: {
+     *   OPENAI_API_KEY: { required: true },
+     *   DEBUG: { required: false },
+     * }
+     * ```
+     */
+    env?: Record<string, {
+        required?: boolean;
+    }>;
+    /** Command handler - must return TResult */
+    handler: CommandHandler<TConfig, InferFlags<TFlags>, TResult, TArgv, TEnv>;
+    /** Optional formatter for output - receives TResult */
+    formatter?: CommandFormatter<TConfig, InferFlags<TFlags>, TResult, TArgv, TEnv>;
+}
+
+export { type ActionDefinition, type ActionHandler, type CLIInput, type Command, type CommandConfig, type CommandDefinition, type CommandFormatter, type CommandGroup, type CommandHandler, type CommandHandlerV3, type CommandResult, type CommandStatus, type ConfigUpdates, type DefinedJob, type DestroyHandlerDefinition, type ErrorResult, FlagSchemaDefinition$1 as FlagSchemaDefinition, type Handler, type HandlerDefinition, InferFlags, type JobDefinition, type JobHandler, type JobInput, type LifecycleContext, MessageBuilder, MessageRouter, type RestInput, type ResultWith, type RouteDefinition, type RouteHandler, type SetupHandlerDefinition, type SetupResult, type SuccessResult, type SystemCommandConfig, type TypedSender, type WebSocketDefinition, type WebSocketHandler, type WebhookDefinition, type WebhookHandler, type WorkspaceConfig, array, artifactId, boolean, commandId, cwd, datetime, defineAction, defineCommand, defineCommandFlags, defineDestroyHandler, defineHandler, defineJob, defineManifest, defineMessage, defineRoute, defineSetupHandler, defineSystemCommand, defineSystemCommandGroup, defineWebSocket, defineWebhook, email, enumSchema, filePath, isCLIHost, isRESTHost, isWSHost, isWebhookHost, isWorkflowHost, json, nonNegativeInt, object, pluginId, positiveInt, schema, scopeId, text, url, uuid };