@tensorify.io/sdk/src/types/plugin.ts

TypeScript SDK for developing Tensorify plugins with comprehensive validation, frontend enforcement, and publishing tools

/**
 * Plugin definition and manifest types for the Tensorify SDK
 * Combines all type definitions into the complete plugin structure
 */

import {
  NodeType,
  PluginCapability,
  PluginRequirements,
  PluginSettings,
  PluginCodeGenerationContext,
} from "./core";
import { NodeVisualConfig, InputHandle, OutputHandle } from "./visual";
import { SettingsField, SettingsGroup } from "./settings";

// ========================================
// PLUGIN DEFINITION
// ========================================

/**
 * Complete plugin definition interface
 * This is what developers use to define their plugins
 */
export interface IPluginDefinition {
  // Core Metadata (optional - will be derived from package.json if not provided)
  /** Unique plugin identifier (derived from package name if not provided) */
  id?: string;
  /** Human-readable plugin name (derived from package name if not provided) */
  name?: string;
  /** Plugin description (derived from package.json if not provided) */
  description?: string;
  /** Plugin version (derived from package.json if not provided) */
  version?: string;
  /** Plugin category/type (derived from package.json tensorify.pluginType if not provided) */
  nodeType?: NodeType;

  // Visual Configuration
  /** Visual appearance and behavior */
  visual: NodeVisualConfig;

  // Handle Definitions
  /** Input handles configuration */
  inputHandles: InputHandle[];
  /** Output handles configuration */
  outputHandles: OutputHandle[];

  // Settings Configuration
  /** Settings fields for the plugin */
  settingsFields: SettingsField[];
  /** Optional settings grouping */
  settingsGroups?: SettingsGroup[];

  // Capabilities & Requirements
  /** Plugin capabilities */
  capabilities: PluginCapability[];
  /** Plugin requirements */
  requirements: PluginRequirements;

  // Optional Metadata
  /** Plugin author information */
  author?: string;
  /** Plugin keywords for search */
  keywords?: string[];
  /** Plugin documentation URL */
  documentationUrl?: string;
  /** Plugin repository URL */
  repositoryUrl?: string;
}

// ========================================
// FRONTEND MANIFEST
// ========================================

/**
 * Package.json information required for manifest generation
 */
export interface PackageJsonInfo {
  name: string;
  version: string;
  description?: string;
  author?: string;
  main?: string;
  keywords?: string[];
  dependencies?: Record<string, string>;
  peerDependencies?: Record<string, string>;
  repository?: {
    type: string;
    url: string;
  };
  tensorify?: {
    pluginType?: string;
  };
}

/**
 * Frontend plugin manifest generated by the CLI
 * This is what gets sent to the backend and used by the frontend
 */
export interface FrontendPluginManifest {
  // Package Information (from package.json)
  /** Package name from package.json */
  name: string;
  /** Version from package.json */
  version: string;
  /** Description from package.json */
  description: string;
  /** Author from package.json */
  author: string;
  /** Main entry file from package.json */
  main: string;
  /** Exact class name for instantiation */
  entrypointClassName: string;
  /** Keywords from package.json */
  keywords: string[];
  /** Repository information */
  repository?: {
    type: string;
    url: string;
  };
  /** Plugin type from package.json tensorify section */
  pluginType?: string;
  /** Tensorify configuration from package.json */
  tensorify?: {
    pluginType?: string;
  };

  // Frontend Configuration (from plugin definition)
  frontendConfigs: {
    /** Plugin identifier */
    id: string;
    /** Plugin name */
    name: string;
    /** Plugin category */
    category: string;
    /** Node type */
    nodeType: NodeType;

    // Visual Configuration
    /** Visual configuration */
    visual: NodeVisualConfig;

    // Handle Configuration
    /** Input handles */
    inputHandles: InputHandle[];
    /** Output handles */
    outputHandles: OutputHandle[];

    // Settings Configuration
    /** Settings fields */
    settingsFields: SettingsField[];
    /** Settings groups */
    settingsGroups?: SettingsGroup[];
  };

  // Plugin Metadata
  /** Plugin capabilities */
  capabilities: PluginCapability[];
  /** Plugin requirements */
  requirements: PluginRequirements;

  // Generation Metadata
  /** SDK version used to generate this manifest */
  sdkVersion: string;
  /** Timestamp when manifest was generated */
  generatedAt: string;
  /** Manifest format version */
  manifestVersion: string;
}

// ========================================
// VALIDATION RESULT TYPES
// ========================================

/**
 * Plugin validation result
 */
export interface PluginValidationResult {
  /** Whether the plugin is valid */
  isValid: boolean;
  /** Array of validation errors */
  errors: PluginValidationError[];
  /** Array of validation warnings */
  warnings: PluginValidationWarning[];
}

/**
 * Plugin validation error
 */
export interface PluginValidationError {
  /** Error type */
  type:
    | "missing_property"
    | "invalid_type"
    | "invalid_value"
    | "duplicate_id"
    | "invalid_reference";
  /** Error message */
  message: string;
  /** Property path where error occurred */
  path?: string;
  /** Expected value or type */
  expected?: any;
  /** Actual value */
  actual?: any;
}

/**
 * Plugin validation warning
 */
export interface PluginValidationWarning {
  /** Warning type */
  type: "deprecated" | "performance" | "best_practice" | "compatibility";
  /** Warning message */
  message: string;
  /** Property path where warning occurred */
  path?: string;
  /** Suggested fix */
  suggestion?: string;
}

// ========================================
// PLUGIN INSTANCE TYPES
// ========================================

/**
 * Plugin validation and creation result
 */
export interface PluginCreationResult {
  /** Whether creation was successful */
  success: boolean;
  /** Plugin instance if successful */
  plugin?: any;
  /** Validation result */
  validation: PluginValidationResult;
  /** Generated manifest if successful */
  manifest?: FrontendPluginManifest;
}

/**
 * Plugin build options
 */
export interface PluginBuildOptions {
  /** Source directory */
  sourceDir?: string;
  /** Output directory */
  outputDir?: string;
  /** Package.json path */
  packageJsonPath?: string;
  /** Entrypoint class name */
  entrypointClassName?: string;
  /** Whether to minify output */
  minify?: boolean;
  /** Target environment */
  target?: "node" | "browser";
}

// ========================================
// RUNTIME TYPES
// ========================================

/**
 * Plugin execution context during runtime
 */
export interface PluginExecutionContext extends PluginCodeGenerationContext {
  /** Plugin instance ID */
  pluginInstanceId: string;
  /** Plugin version */
  pluginVersion: string;
  /** Execution environment */
  environment: "development" | "staging" | "production";
  /** Debug mode flag */
  debug: boolean;
}

/**
 * Plugin execution result
 */
export interface PluginExecutionResult {
  /** Whether execution was successful */
  success: boolean;
  /** Generated code */
  code?: string;
  /** Execution error if any */
  error?: PluginExecutionError;
  /** Execution metadata */
  metadata: {
    executionTime: number;
    memoryUsage?: number;
    warnings?: string[];
  };
}

/**
 * Plugin execution error
 */
export interface PluginExecutionError {
  /** Error type */
  type: "validation" | "generation" | "runtime" | "dependency";
  /** Error message */
  message: string;
  /** Error stack trace */
  stack?: string;
  /** Error context */
  context?: any;
}