@principal-ai/subsystems-core 0.29.0 → 0.30.0

package/src/types/dashboard.ts

@@ -1,257 +0,0 @@
-/**
- * Dashboard Types
- *
- * Types for dashboard definition files (.dashboard.json) that define metrics,
- * layout, and data sources for observability dashboards.
- *
- * These types enable:
- * - Schema validation of dashboard files
- * - Metric source validation against workflow/canvas definitions
- * - Dashboard rendering in UI components
- */
-
-// ============================================================================
-// Dashboard Definition Types (from .dashboard.json files)
-// ============================================================================
-
-export interface DashboardDefinition {
-  $schema?: string;
-  id: string;
-  name: string;
-  description?: string;
-  owner?: string;
-
-  externalLinks?: {
-    grafana?: string;
-    datadog?: string;
-    runbook?: string;
-    [key: string]: string | undefined;
-  };
-
-  metrics: MetricDefinition[];
-
-  layout: DashboardLayout;
-}
-
-export interface MetricDefinition {
-  id: string;
-  name: string;
-  description?: string;
-  type: MetricType;
-  unit?: string;
-
-  sources: MetricSource[];
-
-  query: MetricQuery;
-
-  thresholds?: {
-    warning?: number;
-    critical?: number;
-  };
-
-  alerts?: AlertDefinition[];
-
-  /** Display hints for the renderer */
-  display?: MetricDisplay;
-
-  /** Mock data for prototyping (prefixed with _ to indicate non-production) */
-  _mockData?: MockMetricData;
-}
-
-export type MetricType = 'counter' | 'gauge' | 'histogram';
-
-export interface MetricSource {
-  /** Source type: event or span */
-  type?: 'event' | 'span';
-  /** Storyboard containing the workflow */
-  storyboard: string;
-  /** Workflow within the storyboard */
-  workflow: string;
-  /** Specific nodes within the workflow (optional) */
-  nodes?: string[];
-  /** Event name pattern (for event-based metrics) */
-  event?: string;
-}
-
-export interface MetricQuery {
-  /** How to derive the metric value */
-  derivation: Derivation;
-  /** Filter expression (e.g., "isMobile = true") */
-  filter?: string;
-  /** Attributes to group by (e.g., ["isMobile", "user.tier"]) */
-  groupBy?: string[];
-  /** Time bucket for aggregation */
-  timeGroup?: TimeGroup;
-  /** Time window for the query (e.g., "1h", "24h") */
-  window?: string;
-  /** Base expression for percentage calculations */
-  over?: string;
-  /** Percentile value for histogram metrics */
-  percentile?: number;
-}
-
-export type Derivation =
-  | 'count'
-  | 'rate'
-  | 'sum'
-  | 'avg'
-  | 'min'
-  | 'max'
-  | 'duration'
-  | 'error_rate'
-  | 'success_rate'
-  | 'percentage'
-  | 'p50'
-  | 'p95'
-  | 'p99';
-
-export type TimeGroup = 'minute' | 'hour' | 'day' | 'week' | 'month';
-
-export interface AlertDefinition {
-  name: string;
-  condition: string;
-  severity: 'info' | 'warning' | 'critical';
-  runbook?: string;
-}
-
-export interface MetricDisplay {
-  component?: DisplayComponent;
-  size?: 'small' | 'medium' | 'large';
-  showTrend?: boolean;
-  showSparkline?: boolean;
-  color?: string;
-}
-
-export type DisplayComponent =
-  | 'MetricCard'
-  | 'LineChart'
-  | 'BarChart'
-  | 'StackedBarChart'
-  | 'PieChart'
-  | 'GaugeChart'
-  | 'Histogram'
-  | 'DataTable';
-
-// ============================================================================
-// Dashboard Layout Types
-// ============================================================================
-
-export interface DashboardLayout {
-  /** Grid column count (e.g., 12 for 12-column grid) */
-  columns?: number;
-  /** Gap between panels in pixels */
-  gap?: number;
-
-  /** Responsive breakpoints */
-  breakpoints?: {
-    mobile?: number; // e.g., 768 - below this, single column
-    tablet?: number; // e.g., 1024 - below this, reduced columns
-  };
-
-  rows: DashboardRow[];
-}
-
-export interface DashboardRow {
-  title?: string;
-  panels: PanelPlacement[];
-}
-
-export interface PanelPlacement {
-  /** Metric ID to display */
-  id: string;
-
-  /** Grid span (how many columns this panel takes, 1-12 for 12-column grid) */
-  span?: number;
-
-  /** Responsive spans */
-  spanMobile?: number;
-  spanTablet?: number;
-  spanDesktop?: number;
-
-  /** Height control */
-  height?: number | 'auto';
-  minHeight?: number;
-}
-
-// ============================================================================
-// Mock Data Types (for prototyping without real OTEL data)
-// ============================================================================
-
-export interface MockMetricData {
-  current?: number;
-  previous?: number;
-  trend?: 'up' | 'down' | 'flat';
-  series?: TimeSeriesPoint[];
-  breakdown?: Record<string, number>;
-  histogram?: HistogramData;
-}
-
-export interface TimeSeriesPoint {
-  date: string;
-  value?: number;
-  /** For grouped data (e.g., { date: "2024-03-27", mobile: 10156, desktop: 18946 }) */
-  [key: string]: string | number | undefined;
-}
-
-export interface HistogramData {
-  buckets: string[];
-  counts: number[];
-}
-
-// ============================================================================
-// Time Range Types
-// ============================================================================
-
-export type TimeRangePreset =
-  | 'last_5m'
-  | 'last_15m'
-  | 'last_30m'
-  | 'last_1h'
-  | 'last_3h'
-  | 'last_6h'
-  | 'last_12h'
-  | 'last_24h'
-  | 'last_7d'
-  | 'last_30d'
-  | 'custom';
-
-export interface TimeRange {
-  preset?: TimeRangePreset;
-  /** For custom ranges */
-  start?: Date;
-  end?: Date;
-}
-
-export type RefreshInterval = 'off' | '10s' | '30s' | '1m' | '5m' | '10m';
-
-export interface TimeRangeConfig {
-  /** Available presets to show in the selector */
-  presets?: TimeRangePreset[];
-  /** Default time range */
-  defaultRange?: TimeRangePreset;
-  /** Available refresh intervals */
-  refreshIntervals?: RefreshInterval[];
-  /** Default refresh interval */
-  defaultRefresh?: RefreshInterval;
-}
-
-// ============================================================================
-// Runtime Data Types (for rendering)
-// ============================================================================
-
-export interface MetricData {
-  current?: number;
-  previous?: number;
-  trend?: 'up' | 'down' | 'flat';
-  changePercent?: number;
-  series?: TimeSeriesPoint[];
-  breakdown?: Record<string, number>;
-  histogram?: HistogramData;
-  loading?: boolean;
-  error?: string;
-}
-
-export interface DataProvider {
-  get(metricId: string): MetricData;
-  getAll(): Record<string, MetricData>;
-}

package/src/types/library.ts

@@ -1,283 +0,0 @@
-/**
- * Component Library Types
- *
- * Defines the structure for component libraries (.yaml/.json files)
- * that contain reusable node and edge type definitions.
- *
- * Libraries are separate from canvas files:
- * - Canvas files (.canvas) = actual graph layouts that get rendered
- * - Library files (.yaml/.json) = collections of reusable type definitions
- *
- * When a user adds a component from the library to a canvas,
- * the type definition gets embedded into the node's `pv` field.
- */
-
-import type {
-  PVNodeShape,
-  PVEdgeStyle,
-  PVAnimationType,
-  // PVActionPattern removed - see docs/LEGACY_PATH_BASED_PATTERNS.md
-  PVNodeState,
-  PVEventSchema,
-} from './canvas';
-
-// ============================================================================
-// Resource Types
-// ============================================================================
-
-/**
- * Definition for an instrumentation scope
- *
- * Describes a scope with its color and optional metadata.
- * Used for consistent visual representation across canvases.
- *
- * @deprecated Scope visual metadata is now defined in .scopes.canvas files using OtelScopeNode type.
- * This type is kept for backward compatibility during migration but will be removed in a future version.
- * Use .scopes.canvas files instead of the top-level scopes section in library.yaml.
- */
-export interface ScopeDefinition {
-  /** Color for nodes belonging to this scope (hex format). Required unless external. */
-  color?: string;
-
-  /** Icon identifier (Lucide icons) */
-  icon?: string;
-
-  /** Human-readable description of what this scope covers */
-  description?: string;
-
-  /**
-   * Mark this scope as external - defined in another library/package.
-   * External scopes don't require color (they inherit from the defining library).
-   */
-  external?: boolean;
-}
-
-/**
- * Owned scopes: array of scope names that reference top-level scopes
- *
- * Scope definitions are declared in the top-level `scopes` section of library.yaml.
- * Resources reference those scopes by name.
- */
-export type OwnedScopes = string[];
-
-/**
- * OTEL resource attributes for a service/component
- *
- * Represents the actual resource attribute values (not match patterns).
- * These are the attributes that would be set when instrumenting the service.
- *
- * @see https://opentelemetry.io/docs/specs/semconv/resource/
- */
-export interface ResourceAttributes {
-  /** Service identification (required) */
-  'service.name': string;
-
-  /** Service version (recommended) */
-  'service.version'?: string;
-
-  /** Service namespace (optional) */
-  'service.namespace'?: string;
-
-  /** Service instance ID (optional) */
-  'service.instance.id'?: string;
-
-  /** Deployment environment (recommended) */
-  'deployment.environment'?: string;
-
-  /** Kubernetes namespace */
-  'k8s.namespace.name'?: string;
-
-  /** Kubernetes deployment name */
-  'k8s.deployment.name'?: string;
-
-  /** Kubernetes pod name */
-  'k8s.pod.name'?: string;
-
-  /** Kubernetes container name */
-  'k8s.container.name'?: string;
-
-  /** Kubernetes node name */
-  'k8s.node.name'?: string;
-
-  /** Database system */
-  'db.system'?: string;
-
-  /** Database name */
-  'db.name'?: string;
-
-  /** Host name */
-  'host.name'?: string;
-
-  /** Host ID */
-  'host.id'?: string;
-
-  /** Cloud provider */
-  'cloud.provider'?: string;
-
-  /** Cloud region */
-  'cloud.region'?: string;
-
-  /** Messaging system */
-  'messaging.system'?: string;
-
-  /** Messaging destination name */
-  'messaging.destination.name'?: string;
-
-  /**
-   * Instrumentation scopes owned by this service
-   *
-   * Lists the tracer/instrumentation scope names that belong to this service.
-   * Spans from these scopes will be matched against this service's storyboards
-   * rather than looking up external registries.
-   *
-   * Scope names must reference scopes defined in the top-level `scopes` section.
-   *
-   * @example
-   * ```yaml
-   * scopes:
-   *   auth-flow:
-   *     color: "#DC2626"
-   *     description: "Authentication flow instrumentation"
-   *
-   * resources:
-   *   auth-service:
-   *     service.name: "auth-service"
-   *     owned-scopes:
-   *       - "auth-flow"
-   * ```
-   */
-  'owned-scopes'?: OwnedScopes;
-
-  /** Allow arbitrary OTEL resource attributes */
-  [key: string]: string | string[] | undefined;
-}
-
-
-// ============================================================================
-// Component Library Root Type
-// ============================================================================
-
-/**
- * Root type for a component library file (.yaml or .json).
- *
- * Example library.yaml:
- * ```yaml
- * version: "1.0.0"
- * name: "My Service"
- * description: "OTEL instrumentation configuration"
- *
- * resources:
- *   auth-service:
- *     service.name: "auth-service"
- *     service.version: "1.0.0"
- *     deployment.environment: "production"
- *     owned-scopes:
- *       - "auth-flow"
- *
- * eventSchemas:
- *   user.login.success:
- *     description: "User successfully logged in"
- *     attributes:
- *       user.id:
- *         type: string
- *         required: true
- *       session.id:
- *         type: string
- *         required: true
- * ```
- *
- * Note: Scope visual metadata (colors, icons) are now defined in .scopes.canvas files.
- * The `owned-scopes` field in resources is used for telemetry routing only.
- */
-export interface ComponentLibrary {
-  /** Library schema version */
-  version: string;
-
-  /** Library name */
-  name: string;
-
-  /** Library description */
-  description?: string;
-
-  /**
-   * Service resource registry
-   *
-   * Defines the services in this package and their expected OTEL resource attributes.
-   * Each service configures its own resources at runtime (via env vars or SDK),
-   * but declaring them here provides:
-   * - Service documentation/registry
-   * - Expected resource schema for validation
-   * - Dev instrumentation defaults
-   * - Canvas node generation
-   *
-   * The key is a service identifier (used for reference), and the value contains
-   * the OTEL resource attributes for that service.
-   *
-   * @example
-   * ```yaml
-   * resources:
-   *   payment-api:
-   *     service.name: "payment-api"
-   *     service.version: "1.0.0"
-   *     deployment.environment: "development"
-   *
-   *   payment-worker:
-   *     service.name: "payment-worker"
-   *     service.version: "1.0.0"
-   *     deployment.environment: "development"
-   * ```
-   */
-  resources?: Record<string, ResourceAttributes>;
-
-  /**
-   * Reusable event schema definitions
-   *
-   * Defines event schemas that can be referenced by canvas nodes via `pv.eventRef`.
-   * This promotes reusability and consistency across canvases.
-   *
-   * @example
-   * ```yaml
-   * eventSchemas:
-   *   auth.callback.started:
-   *     description: "Authentication callback initiated"
-   *     attributes:
-   *       session.id:
-   *         type: string
-   *         required: true
-   *         description: "Session identifier"
-   * ```
-   */
-  eventSchemas?: Record<string, Omit<PVEventSchema, 'name'>>;
-}
-
-// ============================================================================
-// Utility Types
-// ============================================================================
-
-/**
- * Result of loading a component library
- */
-export interface LibraryLoadResult {
-  /** Whether the library was loaded successfully */
-  success: boolean;
-
-  /** The loaded library (if successful) */
-  library?: ComponentLibrary;
-
-  /** Error message (if failed) */
-  error?: string;
-
-  /** Path the library was loaded from */
-  path: string;
-}
-
-/**
- * Options for the library loader
- */
-export interface LibraryLoaderOptions {
-  /** Base directory to search for library files */
-  baseDir?: string;
-
-  /** Custom library file name (default: "library.yaml" or "library.json") */
-  fileName?: string;
-}