@kb-labs/shared-command-kit 1.0.0

package/dist/index.js

@@ -0,0 +1,1543 @@
+import { platform } from '@kb-labs/core-runtime';
+import { z } from 'zod';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { existsSync } from 'fs';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/helpers/use-platform.ts
+var use_platform_exports = {};
+__export(use_platform_exports, {
+  isPlatformConfigured: () => isPlatformConfigured,
+  usePlatform: () => usePlatform
+});
+function usePlatform() {
+  return platform;
+}
+function isPlatformConfigured(adapterName) {
+  const platform = usePlatform();
+  const adapter = platform[adapterName];
+  if (!adapter) {
+    return false;
+  }
+  if ("hasAdapter" in platform && typeof platform.hasAdapter === "function") {
+    return platform.hasAdapter(adapterName);
+  }
+  if (typeof adapter === "object" && adapter.constructor) {
+    const constructorName = adapter.constructor.name;
+    return !constructorName.toLowerCase().includes("noop") && !constructorName.toLowerCase().includes("fallback");
+  }
+  return true;
+}
+var init_use_platform = __esm({
+  "src/helpers/use-platform.ts"() {
+  }
+});
+
+// src/flags/types.ts
+var FlagValidationError = class extends Error {
+  constructor(flag, message, value, schema2, commandName) {
+    super(message);
+    this.flag = flag;
+    this.value = value;
+    this.schema = schema2;
+    this.commandName = commandName;
+    this.name = "FlagValidationError";
+  }
+};
+
+// src/flags/define.ts
+function defineFlags(definition) {
+  return {
+    schema: definition,
+    infer: {}
+  };
+}
+
+// src/flags/validate.ts
+function coerceValue(value, type) {
+  if (value === void 0 || value === null) {
+    return value;
+  }
+  switch (type) {
+    case "boolean":
+      if (typeof value === "boolean") {
+        return value;
+      }
+      if (typeof value === "string") {
+        const lower = value.toLowerCase().trim();
+        if (lower === "true" || lower === "1" || lower === "yes") {
+          return true;
+        }
+        if (lower === "false" || lower === "0" || lower === "no" || lower === "") {
+          return false;
+        }
+      }
+      return Boolean(value);
+    case "number":
+      if (typeof value === "number") {
+        return value;
+      }
+      if (typeof value === "string") {
+        const parsed = Number(value);
+        if (!Number.isNaN(parsed) && Number.isFinite(parsed)) {
+          return parsed;
+        }
+      }
+      return Number(value);
+    case "array":
+      if (Array.isArray(value)) {
+        return value;
+      }
+      if (typeof value === "string") {
+        return value.split(",").map((item) => item.trim());
+      }
+      return [value];
+    case "string":
+      return String(value);
+    default:
+      return value;
+  }
+}
+async function validateFlag(flagName, value, schema2) {
+  const { type, required } = schema2;
+  const choices = "choices" in schema2 ? schema2.choices : void 0;
+  const pattern = "pattern" in schema2 ? schema2.pattern : void 0;
+  const min = "min" in schema2 ? schema2.min : void 0;
+  const max = "max" in schema2 ? schema2.max : void 0;
+  const validate = "validate" in schema2 ? schema2.validate : void 0;
+  const minLength = "minLength" in schema2 ? schema2.minLength : void 0;
+  const maxLength = "maxLength" in schema2 ? schema2.maxLength : void 0;
+  const items = "items" in schema2 ? schema2.items : void 0;
+  if (required && (value === void 0 || value === null || value === "")) {
+    return `Flag --${flagName} is required`;
+  }
+  if (value === void 0 || value === null) {
+    return true;
+  }
+  const coerced = coerceValue(value, type);
+  switch (type) {
+    case "boolean":
+      if (typeof coerced !== "boolean") {
+        return `Flag --${flagName} must be a boolean`;
+      }
+      break;
+    case "string":
+      if (typeof coerced !== "string") {
+        return `Flag --${flagName} must be a string`;
+      }
+      if (minLength !== void 0 && coerced.length < minLength) {
+        return `Flag --${flagName} must be at least ${minLength} characters long`;
+      }
+      if (maxLength !== void 0 && coerced.length > maxLength) {
+        return `Flag --${flagName} must be at most ${maxLength} characters long`;
+      }
+      if (choices && !choices.includes(coerced)) {
+        return `Flag --${flagName} must be one of: ${choices.join(", ")} (got: ${coerced})`;
+      }
+      if (pattern && !pattern.test(coerced)) {
+        return `Flag --${flagName} must match pattern ${pattern.toString()}`;
+      }
+      if (validate) {
+        const stringValidate = validate;
+        const result = await stringValidate(coerced);
+        if (result !== true) {
+          return result;
+        }
+      }
+      break;
+    case "number":
+      if (typeof coerced !== "number" || !Number.isFinite(coerced)) {
+        return `Flag --${flagName} must be a number`;
+      }
+      if (min !== void 0 && coerced < min) {
+        return `Flag --${flagName} must be >= ${min} (got: ${coerced})`;
+      }
+      if (max !== void 0 && coerced > max) {
+        return `Flag --${flagName} must be <= ${max} (got: ${coerced})`;
+      }
+      if (validate) {
+        const numberValidate = validate;
+        const result = await numberValidate(coerced);
+        if (result !== true) {
+          return result;
+        }
+      }
+      break;
+    case "array":
+      if (!Array.isArray(coerced)) {
+        return `Flag --${flagName} must be an array`;
+      }
+      if (minLength !== void 0 && coerced.length < minLength) {
+        return `Flag --${flagName} must have at least ${minLength} items`;
+      }
+      if (maxLength !== void 0 && coerced.length > maxLength) {
+        return `Flag --${flagName} must have at most ${maxLength} items`;
+      }
+      if (items) {
+        for (let i = 0; i < coerced.length; i++) {
+          const item = coerced[i];
+          if (items === "string" && typeof item !== "string") {
+            return `Flag --${flagName}[${i}] must be a string`;
+          }
+          if (items === "number" && typeof item !== "number") {
+            return `Flag --${flagName}[${i}] must be a number`;
+          }
+          if (items === "boolean" && typeof item !== "boolean") {
+            return `Flag --${flagName}[${i}] must be a boolean`;
+          }
+        }
+      }
+      break;
+  }
+  return true;
+}
+async function validateFlags(rawFlags, schemaDefinition) {
+  const schema2 = "schema" in schemaDefinition ? schemaDefinition.schema : schemaDefinition;
+  const errors = [];
+  const result = {};
+  const flagValues = { ...rawFlags };
+  for (const [flagName, flagSchema] of Object.entries(schema2)) {
+    const value = flagValues[flagName];
+    if (value !== void 0 && value !== null && value !== false && value !== "") {
+      const implies = flagSchema.implies;
+      if (implies) {
+        for (const implied of implies) {
+          if (Array.isArray(implied) && implied.length === 2) {
+            const [impliedFlag, impliedValue] = implied;
+            if (flagValues[impliedFlag] === void 0) {
+              flagValues[impliedFlag] = impliedValue;
+            }
+          } else if (typeof implied === "string") {
+            if (flagValues[implied] === void 0) {
+              flagValues[implied] = true;
+            }
+          }
+        }
+      }
+    }
+  }
+  for (const [flagName, flagSchema] of Object.entries(schema2)) {
+    const value = flagValues[flagName];
+    const schemaWithName = { ...flagSchema, name: flagName };
+    const conflicts = flagSchema.conflicts;
+    if (conflicts && value !== void 0 && value !== null && value !== false && value !== "") {
+      for (const conflictingFlag of conflicts) {
+        const conflictingValue = flagValues[conflictingFlag];
+        if (conflictingValue !== void 0 && conflictingValue !== null && conflictingValue !== false && conflictingValue !== "") {
+          errors.push({
+            flag: flagName,
+            message: `Flag --${flagName} conflicts with --${conflictingFlag}`,
+            value
+          });
+          break;
+        }
+      }
+      if (errors.some((e) => e.flag === flagName)) {
+        continue;
+      }
+    }
+    const dependsOn = flagSchema.dependsOn;
+    if (dependsOn && value !== void 0 && value !== null && value !== "") {
+      for (const dependency of dependsOn) {
+        const dependencyValue = flagValues[dependency];
+        if (dependencyValue === void 0 || dependencyValue === null || dependencyValue === "") {
+          errors.push({
+            flag: flagName,
+            message: `Flag --${flagName} depends on --${dependency}`,
+            value
+          });
+          break;
+        }
+      }
+      if (errors.some((e) => e.flag === flagName)) {
+        continue;
+      }
+    }
+    if (flagSchema.required && (value === void 0 || value === null || value === "")) {
+      errors.push({
+        flag: flagName,
+        message: `Flag --${flagName} is required`,
+        value
+      });
+      continue;
+    }
+    const finalValue = value !== void 0 ? value : flagSchema.default;
+    if (finalValue === void 0 && !flagSchema.required) {
+      continue;
+    }
+    const validationResult = await validateFlag(flagName, finalValue, schemaWithName);
+    if (validationResult !== true) {
+      errors.push({
+        flag: flagName,
+        message: validationResult,
+        value: finalValue
+      });
+      continue;
+    }
+    let transformedValue = coerceValue(finalValue, flagSchema.type);
+    const transform = flagSchema.transform;
+    if (transform) {
+      transformedValue = await transform(transformedValue);
+    }
+    result[flagName] = transformedValue;
+  }
+  if (errors.length > 0) {
+    const firstError = errors[0];
+    throw new FlagValidationError(
+      firstError.flag,
+      firstError.message,
+      firstError.value,
+      schema2
+      // Pass schema for usage generation
+    );
+  }
+  return result;
+}
+async function validateFlagsSafe(rawFlags, schemaDefinition) {
+  try {
+    const data = await validateFlags(rawFlags, schemaDefinition);
+    return {
+      success: true,
+      data,
+      errors: []
+    };
+  } catch (error) {
+    if (error instanceof FlagValidationError) {
+      return {
+        success: false,
+        errors: [
+          {
+            flag: error.flag,
+            message: error.message,
+            value: error.value
+          }
+        ]
+      };
+    }
+    throw error;
+  }
+}
+
+// src/analytics/with-analytics.ts
+async function withAnalytics(ctx, eventName, events, operation) {
+  const analytics = ctx.platform?.analytics;
+  const startTime = Date.now();
+  if (analytics && events.started) {
+    await analytics.track(`${eventName}.started`, {
+      ...events.started,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  try {
+    const result = await operation();
+    if (analytics && events.completed) {
+      const completedProps = typeof events.completed === "function" ? events.completed(result) : events.completed;
+      await analytics.track(`${eventName}.completed`, {
+        ...completedProps,
+        durationMs: Date.now() - startTime,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    return result;
+  } catch (error) {
+    if (analytics && events.failed) {
+      const failedProps = typeof events.failed === "function" ? events.failed(error) : events.failed;
+      await analytics.track(`${eventName}.failed`, {
+        ...failedProps,
+        durationMs: Date.now() - startTime,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    throw error;
+  }
+}
+function createAnalyticsWrapper(eventName, defaultEvents) {
+  return async (ctx, additionalEvents, operation) => {
+    const mergedEvents = {
+      started: { ...defaultEvents.started, ...additionalEvents.started },
+      completed: additionalEvents.completed || defaultEvents.completed,
+      failed: additionalEvents.failed || defaultEvents.failed
+    };
+    return withAnalytics(ctx, eventName, mergedEvents, operation);
+  };
+}
+async function trackEvent(ctx, eventName, properties) {
+  const analytics = ctx.platform?.analytics;
+  if (analytics) {
+    await analytics.track(eventName, {
+      ...properties,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+}
+
+// src/errors/format-validation.ts
+function formatValidationError(error, options = {}) {
+  const { commandName, schema: schema2 } = options;
+  const lines = [];
+  const errorMsg = error.message;
+  if (errorMsg.includes("is required")) {
+    lines.push(`\u274C Missing required flag: --${error.flag}`);
+  } else if (errorMsg.includes("must be one of")) {
+    const valueStr = error.value !== void 0 ? ` ${error.value}` : "";
+    lines.push(`\u274C Invalid value for --${error.flag}:${valueStr}`);
+  } else if (errorMsg.includes("must be a")) {
+    lines.push(`\u274C Invalid type for --${error.flag}`);
+  } else if (errorMsg.includes("conflicts with")) {
+    lines.push(`\u274C Flag conflict: --${error.flag}`);
+  } else if (errorMsg.includes("depends on")) {
+    lines.push(`\u274C Missing dependency for --${error.flag}`);
+  } else {
+    lines.push(`\u274C ${errorMsg}`);
+  }
+  lines.push("");
+  if (commandName && schema2) {
+    const usageLine = generateUsageLine(commandName, schema2, error.flag);
+    if (usageLine) {
+      lines.push(`Usage: ${usageLine}`);
+    }
+  }
+  if (commandName) {
+    lines.push(`Hint: Try ${commandName} --help`);
+  } else {
+    lines.push("Hint: Try --help for more information");
+  }
+  return lines.join("\n");
+}
+function generateUsageLine(commandName, schema2, errorFlag) {
+  const parts = [commandName];
+  const errorFlagSchema = schema2[errorFlag];
+  if (errorFlagSchema) {
+    const flagStr = formatFlagForUsage(errorFlag, errorFlagSchema);
+    parts.push(flagStr);
+  }
+  const otherRequiredFlags = Object.entries(schema2).filter(
+    ([name, flagSchema]) => name !== errorFlag && flagSchema.required
+  );
+  if (otherRequiredFlags.length > 0) {
+    for (const [name, flagSchema] of otherRequiredFlags) {
+      parts.push(formatFlagForUsage(name, flagSchema));
+    }
+  }
+  const hasOptionalFlags = Object.values(schema2).some((s) => !s.required);
+  if (hasOptionalFlags) {
+    parts.push("[options]");
+  }
+  return parts.join(" ");
+}
+function formatFlagForUsage(name, schema2) {
+  let valueHint;
+  if ("choices" in schema2 && schema2.choices && schema2.choices.length > 0) {
+    valueHint = `<${schema2.choices.join("|")}>`;
+  } else if (schema2.type === "boolean") {
+    return schema2.required ? `--${name}` : `[--${name}]`;
+  } else {
+    valueHint = `<${name}>`;
+  }
+  const flagPart = `--${name} ${valueHint}`;
+  return schema2.required ? flagPart : `[${flagPart}]`;
+}
+
+// src/errors/format.ts
+function formatError(error, options = {}) {
+  const { showStack = false, timingMs } = options;
+  if (error instanceof FlagValidationError) {
+    const friendlyMessage = formatValidationError(error, {
+      commandName: error.commandName,
+      schema: error.schema
+    });
+    const json3 = {
+      ok: false,
+      error: error.message
+    };
+    if (timingMs !== void 0) {
+      json3.timingMs = timingMs;
+    }
+    if (showStack && error.stack) {
+      json3.stack = error.stack;
+    }
+    let message2 = friendlyMessage;
+    if (showStack && error.stack) {
+      message2 = `${friendlyMessage}
+
+Stack trace:
+${error.stack}`;
+    }
+    return {
+      message: message2,
+      json: json3
+    };
+  }
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const errorStack = error instanceof Error ? error.stack : void 0;
+  const json2 = {
+    ok: false,
+    error: errorMessage
+  };
+  if (timingMs !== void 0) {
+    json2.timingMs = timingMs;
+  }
+  if (showStack && errorStack) {
+    json2.stack = errorStack;
+  }
+  let message = errorMessage;
+  if (showStack && errorStack) {
+    message = `${errorMessage}
+
+${errorStack}`;
+  }
+  return {
+    message,
+    json: json2
+  };
+}
+
+// src/errors/factory.ts
+var PluginError = class _PluginError extends Error {
+  statusCode;
+  errorCode;
+  details;
+  constructor(errorCode, message, statusCode, details) {
+    super(message);
+    this.name = "PluginError";
+    this.errorCode = errorCode;
+    this.statusCode = statusCode;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _PluginError);
+    }
+  }
+  /**
+   * Convert error to JSON for logging/serialization
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      errorCode: this.errorCode,
+      message: this.message,
+      statusCode: this.statusCode,
+      details: this.details,
+      stack: this.stack
+    };
+  }
+  /**
+   * Check if error is a PluginError
+   */
+  static isPluginError(error) {
+    return error instanceof _PluginError;
+  }
+};
+function defineError(prefix, definitions) {
+  const errorNamespace = {};
+  for (const [key, def] of Object.entries(definitions)) {
+    const errorCode = `${prefix}_${key.toUpperCase()}`;
+    class DefinedError extends PluginError {
+      constructor(...args) {
+        const { message, details } = buildMessageAndDetails(def, args);
+        super(errorCode, message, def.code, details);
+        this.name = `${prefix}Error`;
+      }
+    }
+    errorNamespace[key] = DefinedError;
+  }
+  errorNamespace.is = (error) => {
+    return PluginError.isPluginError(error) && error.errorCode.startsWith(prefix + "_");
+  };
+  errorNamespace.hasCode = (error, code) => {
+    const errorCode = `${prefix}_${String(code).toUpperCase()}`;
+    return PluginError.isPluginError(error) && error.errorCode === errorCode;
+  };
+  return errorNamespace;
+}
+function buildMessageAndDetails(def, args) {
+  let message;
+  let details;
+  if (typeof def.message === "function") {
+    const lastArg = args[args.length - 1];
+    const hasDetails = lastArg && typeof lastArg === "object" && "details" in lastArg;
+    if (hasDetails) {
+      const templateArgs = args.slice(0, -1);
+      message = def.message(...templateArgs);
+      details = { ...def.details, ...lastArg.details };
+    } else {
+      message = def.message(...args);
+      details = def.details;
+    }
+  } else {
+    message = def.message;
+    if (args.length > 0 && typeof args[0] === "object" && args[0] !== null) {
+      details = { ...def.details, ...args[0].details };
+    } else {
+      details = def.details;
+    }
+  }
+  return { message, details };
+}
+var commonErrors = {
+  /**
+   * Validation error (400)
+   */
+  ValidationFailed: {
+    code: 400,
+    message: "Validation failed"
+  },
+  /**
+   * Resource not found (404)
+   */
+  NotFound: {
+    code: 404,
+    message: (resource) => `${resource} not found`
+  },
+  /**
+   * Unauthorized access (401)
+   */
+  Unauthorized: {
+    code: 401,
+    message: "Unauthorized"
+  },
+  /**
+   * Forbidden access (403)
+   */
+  Forbidden: {
+    code: 403,
+    message: "Forbidden"
+  },
+  /**
+   * Internal server error (500)
+   */
+  InternalError: {
+    code: 500,
+    message: "Internal server error"
+  },
+  /**
+   * Service unavailable (503)
+   */
+  ServiceUnavailable: {
+    code: 503,
+    message: (service) => `Service '${service}' is unavailable`
+  },
+  /**
+   * Timeout error (504)
+   */
+  Timeout: {
+    code: 504,
+    message: (operation) => `Operation '${operation}' timed out`
+  },
+  /**
+   * Conflict error (409)
+   */
+  Conflict: {
+    code: 409,
+    message: (resource) => `${resource} already exists`
+  }
+};
+
+// src/helpers/index.ts
+init_use_platform();
+
+// src/helpers/use-config.ts
+async function useConfig(productId, profileId) {
+  let effectiveProductId = productId;
+  if (!effectiveProductId) {
+    effectiveProductId = globalThis.__KB_CONFIG_SECTION__;
+  }
+  if (!effectiveProductId) {
+    return void 0;
+  }
+  const { usePlatform: usePlatform2 } = await Promise.resolve().then(() => (init_use_platform(), use_platform_exports));
+  const platform = usePlatform2();
+  if (!platform) {
+    return void 0;
+  }
+  return await platform.config.getConfig(effectiveProductId, profileId);
+}
+
+// src/helpers/use-logger.ts
+init_use_platform();
+function useLogger() {
+  const platform = usePlatform();
+  return platform.logger;
+}
+function useLoggerWithContext(context) {
+  const logger = useLogger();
+  return logger.child(context);
+}
+
+// src/helpers/use-llm.ts
+init_use_platform();
+function useLLM(options) {
+  const platform = usePlatform();
+  const llm = platform.llm;
+  if (!llm) {
+    return void 0;
+  }
+  if (options && isLLMRouter(llm)) {
+    return new LazyBoundLLM(llm, options);
+  }
+  return llm;
+}
+var LazyBoundLLM = class {
+  constructor(router, options) {
+    this.router = router;
+    this.options = options;
+  }
+  _resolved = null;
+  resolve() {
+    if (!this._resolved) {
+      this._resolved = this.router.resolveAdapter(this.options);
+    }
+    return this._resolved;
+  }
+  mergeExecutionPolicy(callOptions) {
+    const globalPolicy = this.options.execution;
+    const localPolicy = callOptions?.execution;
+    if (!globalPolicy && !localPolicy) {
+      return void 0;
+    }
+    return {
+      ...globalPolicy,
+      ...localPolicy,
+      cache: { ...globalPolicy?.cache, ...localPolicy?.cache },
+      stream: { ...globalPolicy?.stream, ...localPolicy?.stream }
+    };
+  }
+  async resolveProtocolCapabilities(adapter) {
+    if (!adapter.getProtocolCapabilities) {
+      return {
+        cache: { supported: false },
+        stream: { supported: true }
+      };
+    }
+    return adapter.getProtocolCapabilities();
+  }
+  enforceCachePolicy(caps, execution) {
+    if (execution?.cache?.mode === "require" && !caps.cache.supported) {
+      throw new Error("CACHE_NOT_SUPPORTED: adapter does not support required cache policy");
+    }
+  }
+  buildDecisionTrace(caps, execution, streamAppliedMode, streamFallback, reason) {
+    const requestedCacheMode = execution?.cache?.mode ?? "prefer";
+    const requestedStreamMode = execution?.stream?.mode ?? "prefer";
+    return {
+      cacheRequestedMode: requestedCacheMode,
+      cacheSupported: caps.cache.supported,
+      cacheAppliedMode: requestedCacheMode === "require" || requestedCacheMode === "bypass" ? requestedCacheMode : caps.cache.supported ? "prefer" : "bypass",
+      streamRequestedMode: requestedStreamMode,
+      streamSupported: caps.stream.supported,
+      streamAppliedMode,
+      streamFallback,
+      reason
+    };
+  }
+  withDecisionMetadata(options, trace) {
+    if (!options) {
+      return { metadata: { cacheDecisionTrace: trace } };
+    }
+    return {
+      ...options,
+      metadata: {
+        ...options.metadata,
+        cacheDecisionTrace: trace
+      }
+    };
+  }
+  async complete(prompt, options) {
+    const { adapter, model } = await this.resolve();
+    const execution = this.mergeExecutionPolicy(options);
+    const caps = await this.resolveProtocolCapabilities(adapter);
+    this.enforceCachePolicy(caps, execution);
+    const trace = this.buildDecisionTrace(caps, execution, "off");
+    const optionsWithTrace = this.withDecisionMetadata(options, trace);
+    return adapter.complete(prompt, { ...optionsWithTrace, model, execution });
+  }
+  async *stream(prompt, options) {
+    const { adapter, model } = await this.resolve();
+    const execution = this.mergeExecutionPolicy(options);
+    const caps = await this.resolveProtocolCapabilities(adapter);
+    this.enforceCachePolicy(caps, execution);
+    const streamMode = execution?.stream?.mode ?? "prefer";
+    const canStream = caps.stream.supported;
+    const allowFallback = execution?.stream?.fallbackToComplete ?? true;
+    if (streamMode === "off" || !canStream && streamMode === "prefer" && allowFallback) {
+      const fallbackReason = streamMode === "off" ? "STREAM_OFF" : "STREAM_UNSUPPORTED_FALLBACK_TO_COMPLETE";
+      const trace2 = this.buildDecisionTrace(caps, execution, "off", "complete", fallbackReason);
+      const optionsWithTrace2 = this.withDecisionMetadata(options, trace2);
+      const response = await adapter.complete(prompt, { ...optionsWithTrace2, model, execution });
+      if (response.content) {
+        yield response.content;
+      }
+      return;
+    }
+    if (!canStream && streamMode === "require") {
+      throw new Error("STREAM_NOT_SUPPORTED: adapter does not support required streaming");
+    }
+    const trace = this.buildDecisionTrace(caps, execution, streamMode);
+    const optionsWithTrace = this.withDecisionMetadata(options, trace);
+    yield* adapter.stream(prompt, { ...optionsWithTrace, model, execution });
+  }
+  async chatWithTools(messages, options) {
+    const { adapter, model, tier } = await this.resolve();
+    const execution = this.mergeExecutionPolicy(options);
+    const caps = await this.resolveProtocolCapabilities(adapter);
+    this.enforceCachePolicy(caps, execution);
+    if (!adapter.chatWithTools) {
+      throw new Error("Current adapter does not support chatWithTools");
+    }
+    const trace = this.buildDecisionTrace(caps, execution, "off");
+    const optionsWithTrace = this.withDecisionMetadata(options, trace);
+    return adapter.chatWithTools(messages, {
+      ...optionsWithTrace,
+      model,
+      execution,
+      metadata: { ...optionsWithTrace.metadata, tier }
+    });
+  }
+};
+function isLLMAvailable() {
+  const llm = useLLM();
+  return !!llm;
+}
+function getLLMTier() {
+  const platform = usePlatform();
+  const llm = platform.llm;
+  if (llm && isLLMRouter(llm)) {
+    return llm.getConfiguredTier();
+  }
+  return void 0;
+}
+function isLLMRouter(llm) {
+  return typeof llm.getConfiguredTier === "function" && typeof llm.resolve === "function";
+}
+
+// src/helpers/use-embeddings.ts
+init_use_platform();
+function useEmbeddings() {
+  const platform = usePlatform();
+  return platform.embeddings;
+}
+function isEmbeddingsAvailable() {
+  const embeddings = useEmbeddings();
+  return !!embeddings;
+}
+
+// src/helpers/use-vector-store.ts
+init_use_platform();
+function useVectorStore() {
+  const platform = usePlatform();
+  return platform.vectorStore;
+}
+function isVectorStoreAvailable() {
+  const vectorStore = useVectorStore();
+  return !!vectorStore;
+}
+
+// src/helpers/use-analytics.ts
+init_use_platform();
+function useAnalytics() {
+  const platform = usePlatform();
+  return platform.analytics;
+}
+async function trackAnalyticsEvent(event, properties) {
+  const analytics = useAnalytics();
+  if (analytics) {
+    await analytics.track(event, properties);
+  }
+}
+
+// src/helpers/use-storage.ts
+init_use_platform();
+function useStorage() {
+  const platform = usePlatform();
+  return platform.storage;
+}
+
+// src/helpers/use-cache.ts
+init_use_platform();
+function useCache() {
+  const platform = usePlatform();
+  return platform.cache;
+}
+function isCacheAvailable() {
+  const cache = useCache();
+  return !!cache;
+}
+
+// src/define-system-command.ts
+function convertFlagSchema(schema2) {
+  return Object.entries(schema2).map(([name, def]) => {
+    const result = {
+      name,
+      type: def.type,
+      alias: def.alias,
+      description: def.description,
+      default: def.default,
+      required: def.required
+    };
+    if (def.type === "string" && "choices" in def && Array.isArray(def.choices)) {
+      result.choices = [...def.choices];
+    }
+    return result;
+  });
+}
+function defineSystemCommand(config) {
+  const { name, description, longDescription, category, aliases, examples, flags, handler, formatter } = config;
+  return {
+    name,
+    describe: description,
+    longDescription,
+    category: category || "system",
+    aliases: aliases || [],
+    flags: flags ? convertFlagSchema(flags) : [],
+    examples: examples || [],
+    run: async (ctx, argv, rawFlags) => {
+      const jsonMode = Boolean(rawFlags.json);
+      ctx.platform?.logger?.info?.(`Command ${name} started`);
+      let validatedFlags;
+      if (flags) {
+        const flagSchema = defineFlags(flags);
+        try {
+          validatedFlags = await validateFlags(rawFlags, flagSchema);
+        } catch (error) {
+          if (error instanceof FlagValidationError && name && !error.commandName) {
+            error.commandName = name;
+          }
+          const showStack = Boolean(rawFlags.debug);
+          const formatted = formatError(error, { showStack});
+          if (jsonMode) {
+            ctx.ui?.json(formatted.json);
+          } else {
+            ctx.ui?.error(formatted.message);
+          }
+          return 3;
+        }
+      } else {
+        validatedFlags = rawFlags;
+      }
+      let result;
+      try {
+        result = await handler(ctx, argv, validatedFlags);
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        ctx.platform?.logger?.error?.(`Command ${name} failed: ${errorMessage}`);
+        if (jsonMode) {
+          ctx.ui?.json({ ok: false, error: errorMessage });
+        } else {
+          ctx.ui?.error(errorMessage);
+        }
+        return 1;
+      }
+      if (formatter && typeof result !== "number") {
+        formatter(result, ctx, validatedFlags, argv);
+      }
+      ctx.platform?.logger?.info?.(`Command ${name} completed`);
+      if (typeof result === "number") {
+        return result;
+      }
+      return result.ok ? 0 : 1;
+    }
+  };
+}
+function defineSystemCommandGroup(name, describe, commands) {
+  return {
+    name,
+    describe,
+    commands
+  };
+}
+
+// src/manifest.ts
+function defineManifest(manifest) {
+  return manifest;
+}
+function defineCommandFlags(flags) {
+  return Object.entries(flags).map(([name, flag]) => ({
+    name,
+    type: flag.type,
+    ...flag.alias !== void 0 && { alias: flag.alias },
+    ...flag.default !== void 0 && { default: flag.default },
+    ...flag.description !== void 0 && { description: flag.description },
+    ...flag.choices !== void 0 && { choices: flag.choices },
+    ...flag.required !== void 0 && { required: flag.required }
+  }));
+}
+function cwd() {
+  return z.string().optional().describe("Current working directory path");
+}
+function scopeId() {
+  return z.string().min(1).describe("Scope identifier");
+}
+function text(options) {
+  let schema2 = z.string();
+  if (options?.min !== void 0) {
+    schema2 = schema2.min(options.min);
+  }
+  if (options?.max !== void 0) {
+    schema2 = schema2.max(options.max);
+  }
+  if (options?.default !== void 0) {
+    return schema2.default(options.default).describe("Text string");
+  }
+  return schema2.describe("Text string");
+}
+function positiveInt(options) {
+  let schema2 = z.number().int().positive();
+  if (options?.min !== void 0) {
+    schema2 = schema2.min(options.min);
+  }
+  if (options?.max !== void 0) {
+    schema2 = schema2.max(options.max);
+  }
+  if (options?.default !== void 0) {
+    return schema2.default(options.default).describe("Positive integer");
+  }
+  return schema2.describe("Positive integer");
+}
+function nonNegativeInt(options) {
+  let schema2 = z.number().int().min(0);
+  if (options?.max !== void 0) {
+    schema2 = schema2.max(options.max);
+  }
+  if (options?.default !== void 0) {
+    return schema2.default(options.default).describe("Non-negative integer");
+  }
+  return schema2.describe("Non-negative integer");
+}
+function enumSchema(values, options) {
+  const schema2 = z.enum(values);
+  if (options?.default !== void 0) {
+    return schema2.default(options.default);
+  }
+  return schema2;
+}
+function pluginId() {
+  return z.string().regex(/^@kb-labs\/[a-z][a-z0-9-]*$/, "Must be in format @kb-labs/package-name").describe("Plugin ID");
+}
+function commandId() {
+  return z.string().regex(/^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$/, "Must be in format plugin:command").describe("Command ID");
+}
+function artifactId() {
+  return z.string().regex(/^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/, "Must be in format plugin.artifact.id").describe("Artifact ID");
+}
+function filePath(options) {
+  const schema2 = z.string().describe("File path");
+  if (options?.optional) {
+    return schema2.optional();
+  }
+  return schema2;
+}
+function url(options) {
+  const schema2 = z.string().url().describe("URL");
+  if (options?.optional) {
+    return schema2.optional();
+  }
+  return schema2;
+}
+function email(options) {
+  const schema2 = z.string().email().describe("Email address");
+  if (options?.optional) {
+    return schema2.optional();
+  }
+  return schema2;
+}
+function uuid(options) {
+  const schema2 = z.string().uuid().describe("UUID");
+  if (options?.optional) {
+    return schema2.optional();
+  }
+  return schema2;
+}
+function datetime(options) {
+  const schema2 = z.string().datetime().describe("ISO datetime");
+  if (options?.optional) {
+    return schema2.optional();
+  }
+  return schema2;
+}
+function json() {
+  return z.record(z.unknown()).describe("JSON object");
+}
+function boolean(options) {
+  const schema2 = z.boolean();
+  if (options?.default !== void 0) {
+    return schema2.default(options.default);
+  }
+  return schema2;
+}
+function array(itemSchema, options) {
+  let schema2 = z.array(itemSchema);
+  if (options?.min !== void 0) {
+    schema2 = schema2.min(options.min);
+  }
+  if (options?.max !== void 0) {
+    schema2 = schema2.max(options.max);
+  }
+  return schema2;
+}
+function object(shape) {
+  return z.object(shape);
+}
+var schema = {
+  // Path and ID builders
+  cwd,
+  scopeId,
+  pluginId,
+  commandId,
+  artifactId,
+  filePath,
+  // String builders
+  text,
+  url,
+  email,
+  uuid,
+  datetime,
+  // Number builders
+  positiveInt,
+  nonNegativeInt,
+  // Other builders
+  enum: enumSchema,
+  boolean,
+  json,
+  array,
+  object
+};
+
+// src/rest/define-handler.ts
+function defineHandler(definition) {
+  return {
+    execute: async (ctx, input) => {
+      return await definition.execute(ctx, input);
+    }
+  };
+}
+function defineSetupHandler(definition) {
+  return async (ctx) => {
+    const log = ctx.log || ((level, msg, meta) => {
+      console.log(`[${level}] ${msg}`, meta || "");
+    });
+    try {
+      log("info", "Setup started", { handler: definition.name, outdir: ctx.outdir });
+      if (definition.workspace) {
+        await setupWorkspace(ctx.outdir, definition.workspace, log);
+      }
+      if (definition.config) {
+        await updateConfigFiles(ctx.outdir, definition.config, log);
+      }
+      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) {
+      log("error", "Setup failed", {
+        handler: definition.name,
+        error: error.message,
+        stack: error.stack
+      });
+      return { ok: false, message: `Setup failed: ${error.message}` };
+    }
+  };
+}
+function defineDestroyHandler(definition) {
+  return async (ctx) => {
+    const log = ctx.log || ((level, msg, meta) => {
+      console.log(`[${level}] ${msg}`, meta || "");
+    });
+    try {
+      log("info", "Destroy started", { handler: definition.name, outdir: ctx.outdir });
+      if (definition.config) {
+        await cleanupConfigFiles(ctx.outdir, definition.config, log);
+      }
+      if (definition.workspace) {
+        await cleanupWorkspace(ctx.outdir, definition.workspace, log);
+      }
+      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) {
+      log("error", "Destroy failed", {
+        handler: definition.name,
+        error: error.message,
+        stack: error.stack
+      });
+      return { ok: false, message: `Destroy failed: ${error.message}` };
+    }
+  };
+}
+async function setupWorkspace(outdir, config, log) {
+  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 });
+    }
+  }
+  if (config.files) {
+    for (const [filePath2, content] of Object.entries(config.files)) {
+      const fullPath = path.resolve(outdir, filePath2);
+      const dirPath = path.dirname(fullPath);
+      await fs.mkdir(dirPath, { recursive: true });
+      await fs.writeFile(fullPath, content, "utf-8");
+      log("debug", "Created file", { path: fullPath });
+    }
+  }
+}
+async function updateConfigFiles(outdir, updates, log) {
+  for (const [configFile, configUpdates] of Object.entries(updates)) {
+    const configPath = path.resolve(outdir, configFile);
+    let config = {};
+    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 });
+      }
+    }
+    config = { ...config, ...configUpdates };
+    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 });
+  }
+}
+async function cleanupWorkspace(outdir, config, log) {
+  if (!config) {
+    return;
+  }
+  if (config.files) {
+    for (const file of config.files) {
+      const filePath2 = path.resolve(outdir, file);
+      if (existsSync(filePath2)) {
+        await fs.unlink(filePath2);
+        log("debug", "Removed file", { path: filePath2 });
+      }
+    }
+  }
+  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 });
+      }
+    }
+  }
+}
+async function cleanupConfigFiles(outdir, cleanups, log) {
+  for (const [configFile, keysToRemove] of Object.entries(cleanups)) {
+    const configPath = path.resolve(outdir, configFile);
+    if (!existsSync(configPath)) {
+      continue;
+    }
+    const content = await fs.readFile(configPath, "utf-8");
+    let config;
+    try {
+      config = JSON.parse(content);
+    } catch (error) {
+      log("warn", "Failed to parse config for cleanup", { path: configPath });
+      continue;
+    }
+    for (const key of keysToRemove) {
+      delete config[key];
+    }
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2), "utf-8");
+    log("debug", "Cleaned up config file", { path: configPath, removed: keysToRemove });
+  }
+}
+
+// src/jobs.ts
+function defineJob(definition) {
+  const { handler, ...config } = definition;
+  return {
+    config: { ...config, handler: "" },
+    // handler path will be set in toManifest()
+    handler,
+    toManifest(handlerPath) {
+      return {
+        id: config.id,
+        schedule: config.schedule,
+        job: {
+          type: config.id,
+          // Use job id as type
+          payload: {}
+          // Empty payload by default
+        },
+        describe: config.describe,
+        enabled: config.enabled,
+        permissions: definition.permissions
+      };
+    }
+  };
+}
+
+// src/define-command.ts
+function defineCommand(definition) {
+  return {
+    execute: (context, input) => {
+      if (context.host !== "cli" && context.host !== "workflow") {
+        throw new Error(
+          `Command ${definition.id} can only run in CLI or workflow host (current: ${context.host})`
+        );
+      }
+      return definition.handler.execute(context, input);
+    },
+    cleanup: definition.handler.cleanup
+  };
+}
+function isCLIHost(hostContext) {
+  return hostContext.host === "cli";
+}
+
+// src/define-route.ts
+function defineRoute(definition) {
+  const wrappedHandler = {
+    execute: async (context, input) => {
+      if (context.host !== "rest") {
+        throw new Error(
+          `Route ${definition.path} can only run in REST host (current: ${context.host})`
+        );
+      }
+      if (isRESTHost(context.hostContext)) {
+        const expectedMethod = definition.method.toUpperCase();
+        const actualMethod = context.hostContext.method.toUpperCase();
+        if (actualMethod !== expectedMethod) {
+          throw new Error(
+            `Route ${definition.path} expects ${expectedMethod} but got ${actualMethod}`
+          );
+        }
+      }
+      try {
+        return await definition.handler.execute(context, input);
+      } finally {
+        await definition.handler.cleanup?.();
+      }
+    },
+    cleanup: definition.handler.cleanup
+  };
+  return wrappedHandler;
+}
+function isRESTHost(hostContext) {
+  return hostContext.host === "rest";
+}
+
+// src/define-webhook.ts
+function defineWebhook(definition) {
+  const wrappedHandler = {
+    execute: async (context, input) => {
+      if (context.host !== "webhook") {
+        throw new Error(
+          `Webhook ${definition.event} can only run in webhook host (current: ${context.host})`
+        );
+      }
+      if (isWebhookHost(context.hostContext)) {
+        const expectedEvent = definition.event;
+        const actualEvent = context.hostContext.event;
+        if (actualEvent !== expectedEvent) {
+          throw new Error(
+            `Webhook expects event ${expectedEvent} but got ${actualEvent}`
+          );
+        }
+      }
+      try {
+        return await definition.handler.execute(context, input);
+      } finally {
+        await definition.handler.cleanup?.();
+      }
+    },
+    cleanup: definition.handler.cleanup
+  };
+  return wrappedHandler;
+}
+function isWebhookHost(hostContext) {
+  return hostContext.host === "webhook";
+}
+
+// src/define-websocket.ts
+function validateWSMessage(message) {
+  if (!message || typeof message !== "object") {
+    throw new Error("Invalid WebSocket message: must be an object");
+  }
+  const msg = message;
+  if (typeof msg.type !== "string" || msg.type.length === 0) {
+    throw new Error("Invalid WebSocket message: type must be a non-empty string");
+  }
+  if (msg.timestamp !== void 0 && typeof msg.timestamp !== "number") {
+    throw new Error("Invalid WebSocket message: timestamp must be a number");
+  }
+  if (msg.messageId !== void 0 && typeof msg.messageId !== "string") {
+    throw new Error("Invalid WebSocket message: messageId must be a string");
+  }
+}
+function createTypedSender(raw) {
+  return {
+    send: (msg) => raw.send(msg),
+    broadcast: (msg, exclude) => raw.broadcast(msg, exclude),
+    sendTo: (ids, msg) => raw.sendTo(ids, msg),
+    close: raw.close.bind(raw),
+    getConnectionId: raw.getConnectionId.bind(raw),
+    raw
+  };
+}
+function defineWebSocket(definition) {
+  return {
+    async execute(context, input) {
+      if (context.host !== "ws") {
+        throw new Error(
+          `WebSocket channel ${definition.path} can only run in ws host (current: ${context.host})`
+        );
+      }
+      if (isWSHost(context.hostContext)) {
+        const expectedPath = definition.path;
+        const actualPath = context.hostContext.channelPath;
+        if (actualPath !== expectedPath) {
+          throw new Error(
+            `WebSocket expects channel ${expectedPath} but got ${actualPath}`
+          );
+        }
+      }
+      const sender = input.sender;
+      if (!sender && input.event !== "disconnect") {
+        throw new Error("WebSocket sender not provided in input");
+      }
+      const typedSender = sender ? createTypedSender(sender) : void 0;
+      try {
+        switch (input.event) {
+          case "connect":
+            if (typedSender) {
+              await definition.handler.onConnect?.(context, typedSender);
+            }
+            break;
+          case "message":
+            if (input.message && typedSender && sender) {
+              try {
+                validateWSMessage(input.message);
+              } catch (error) {
+                context.platform.logger.error("Invalid WebSocket message received", error, {
+                  connectionId: sender.getConnectionId(),
+                  message: input.message
+                });
+                await sender.send({
+                  type: "error",
+                  payload: { error: "Invalid message format" },
+                  timestamp: Date.now()
+                });
+                break;
+              }
+              const incomingMessage = input.message;
+              await definition.handler.onMessage?.(context, incomingMessage, typedSender);
+            }
+            break;
+          case "disconnect":
+            await definition.handler.onDisconnect?.(
+              context,
+              input.disconnectCode ?? 1e3,
+              input.disconnectReason ?? ""
+            );
+            break;
+          case "error":
+            if (input.error && typedSender) {
+              await definition.handler.onError?.(context, input.error, typedSender);
+            }
+            break;
+        }
+      } finally {
+        await definition.handler.cleanup?.();
+      }
+      return { exitCode: 0 };
+    }
+  };
+}
+function isWSHost(hostContext) {
+  return hostContext.host === "ws";
+}
+
+// src/define-action.ts
+function defineAction(definition) {
+  const wrappedHandler = {
+    execute: (context, input) => {
+      if (context.host !== "workflow") {
+        throw new Error(
+          `Action ${definition.id} can only run in workflow host (current: ${context.host})`
+        );
+      }
+      return definition.handler.execute(context, input);
+    },
+    cleanup: definition.handler.cleanup
+  };
+  return wrappedHandler;
+}
+function isWorkflowHost(hostContext) {
+  return hostContext.host === "workflow";
+}
+
+// src/ws-types.ts
+var MessageBuilder = class {
+  constructor(type) {
+    this.type = type;
+  }
+  /**
+   * Create message with payload
+   */
+  create(payload, messageId) {
+    return {
+      type: this.type,
+      payload,
+      messageId,
+      timestamp: Date.now()
+    };
+  }
+  /**
+   * Match against incoming message type (type guard)
+   */
+  is(message) {
+    return message.type === this.type;
+  }
+};
+function defineMessage(type) {
+  return new MessageBuilder(type);
+}
+var MessageRouter = class {
+  handlers = /* @__PURE__ */ new Map();
+  /**
+   * Register message handler
+   */
+  on(message, handler) {
+    this.handlers.set(message["type"], handler);
+    return this;
+  }
+  /**
+   * Handle incoming message
+   *
+   * @returns true if message was handled, false otherwise
+   */
+  async handle(ctx, message, sender) {
+    const handler = this.handlers.get(message.type);
+    if (handler) {
+      await handler(ctx, message.payload, sender);
+      return true;
+    }
+    return false;
+  }
+};
+
+export { FlagValidationError, MessageBuilder, MessageRouter, PluginError, array, artifactId, boolean, commandId, commonErrors, createAnalyticsWrapper, cwd, datetime, defineAction, defineCommand, defineCommandFlags, defineDestroyHandler, defineError, defineFlags, defineHandler, defineJob, defineManifest, defineMessage, defineRoute, defineSetupHandler, defineSystemCommand, defineSystemCommandGroup, defineWebSocket, defineWebhook, email, enumSchema, filePath, formatError, getLLMTier, isCLIHost, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isRESTHost, isVectorStoreAvailable, isWSHost, isWebhookHost, isWorkflowHost, json, nonNegativeInt, object, pluginId, positiveInt, schema, scopeId, text, trackAnalyticsEvent, trackEvent, url, useAnalytics, useCache, useConfig, useEmbeddings, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore, uuid, validateFlags, validateFlagsSafe, withAnalytics };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map