@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/storyboard/builder.ts

@@ -1,308 +0,0 @@
-/**
- * Storyboard Context Builder
- *
- * Utilities for building StoryboardContextSliceData from canvas and workflow artifacts.
- * Used by hosts to create the context slice for panels like File City.
- */
-
-import type { ExtendedCanvas, ExtendedCanvasNode } from '../types/canvas';
-import { isOtelEventNode, isStandardCanvasNode } from '../types/canvas';
-import type { WorkflowTemplate, WorkflowScenario } from '../workflow/types';
-import type {
-  StoryboardReference,
-  WorkflowReference,
-  ScenarioReference,
-  StoryboardContextSliceData,
-} from './types';
-import type { CanvasType } from '../discovery/types';
-import { buildCanvasFileManifest } from '../discovery/CanvasFileManifest';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/**
- * Map of event name to canvas node IDs that emit that event.
- */
-export type EventNodeMap = Map<string, string[]>;
-
-/**
- * Options for building storyboard context.
- */
-export interface BuildStoryboardContextOptions {
-  /** The parsed canvas content */
-  canvas: ExtendedCanvas;
-
-  /** Storyboard metadata (id, name, path) */
-  storyboard: StoryboardReference;
-
-  /** Canvas type (defaults to 'otel') */
-  canvasType?: CanvasType;
-
-  /** Optional: Selected workflow template and its path */
-  workflow?: {
-    template: WorkflowTemplate;
-    path: string;
-  };
-
-  /** Optional: Selected scenario within the workflow */
-  scenario?: WorkflowScenario;
-
-  /** Optional: Additional supporting files to include */
-  additionalSupportingFiles?: string[];
-}
-
-// ============================================================================
-// Core Functions
-// ============================================================================
-
-/**
- * Build a map of event name to canvas node IDs.
- * Uses `pv.event.name` or `pv.eventRef` from each node.
- *
- * @param canvas - The extended canvas with nodes
- * @returns Map of event names to node IDs that emit those events
- *
- * @example
- * ```typescript
- * const eventMap = buildEventNodeMap(canvas);
- * // Map { 'auth.login' => ['node-abc'], 'api.fetch' => ['node-xyz', 'node-def'] }
- * ```
- */
-export function buildEventNodeMap(canvas: ExtendedCanvas): EventNodeMap {
-  const eventMap: EventNodeMap = new Map();
-
-  if (!canvas.nodes) {
-    return eventMap;
-  }
-
-  for (const node of canvas.nodes) {
-    const eventName = getNodeEventName(node);
-    if (eventName) {
-      const existing = eventMap.get(eventName) || [];
-      existing.push(node.id);
-      eventMap.set(eventName, existing);
-    }
-  }
-
-  return eventMap;
-}
-
-/**
- * Get the event name from a canvas node.
- *
- * Supports two schema locations:
- * 1. Top-level `event.name` / `eventRef` (OtelEventNode in .otel.canvas files)
- * 2. `pv.event.name` / `pv.eventRef` (PVNodeExtension for generic canvas nodes)
- *
- * @param node - The canvas node
- * @returns Event name or undefined if node doesn't emit events
- */
-export function getNodeEventName(node: ExtendedCanvasNode): string | undefined {
-  // 1. Top-level OtelEventNode format (newer .otel.canvas files)
-  const topLevelEvent = (node as { event?: { name?: string } }).event?.name;
-  if (topLevelEvent) return topLevelEvent;
-
-  // Check OTEL event node (top-level event/eventRef)
-  if (isOtelEventNode(node)) {
-    return node.event?.name || node.eventRef;
-  }
-
-  // Check standard node with pv.event/pv.eventRef
-  if (isStandardCanvasNode(node)) {
-    return node.pv?.event?.name || node.pv?.eventRef;
-  }
-
-  return undefined;
-}
-
-/**
- * Resolve workflow scenario event requirements to canvas node IDs.
- *
- * Given a scenario's required events, finds which canvas nodes emit those events.
- *
- * @param canvas - The extended canvas with nodes
- * @param scenario - The workflow scenario with event requirements
- * @returns Array of canvas node IDs involved in this scenario
- *
- * @example
- * ```typescript
- * const nodeIds = resolveScenarioNodeIds(canvas, scenario);
- * // ['node-abc', 'node-xyz'] - nodes that emit events required by the scenario
- * ```
- */
-export function resolveScenarioNodeIds(
-  canvas: ExtendedCanvas,
-  scenario: WorkflowScenario
-): string[] {
-  const eventMap = buildEventNodeMap(canvas);
-  const nodeIds = new Set<string>();
-
-  // Get required events from scenario template.events
-  const requiredEvents = Object.keys(scenario.template?.events || {});
-
-  for (const eventPattern of requiredEvents) {
-    // Handle glob patterns (e.g., "*.error", "auth.*")
-    const matchingNodes = findNodesMatchingEventPattern(eventMap, eventPattern);
-    for (const nodeId of matchingNodes) {
-      nodeIds.add(nodeId);
-    }
-  }
-
-  return Array.from(nodeIds);
-}
-
-/**
- * Resolve workflow template to canvas node IDs.
- *
- * Returns all unique node IDs that are involved in any scenario of the workflow.
- *
- * @param canvas - The extended canvas with nodes
- * @param workflow - The workflow template with scenarios
- * @returns Array of canvas node IDs involved in this workflow
- */
-export function resolveWorkflowNodeIds(
-  canvas: ExtendedCanvas,
-  workflow: WorkflowTemplate
-): string[] {
-  const nodeIds = new Set<string>();
-
-  for (const scenario of workflow.scenarios) {
-    const scenarioNodeIds = resolveScenarioNodeIds(canvas, scenario);
-    for (const nodeId of scenarioNodeIds) {
-      nodeIds.add(nodeId);
-    }
-  }
-
-  return Array.from(nodeIds);
-}
-
-/**
- * Find node IDs matching an event pattern (supports glob-style wildcards).
- *
- * @param eventMap - Map of event names to node IDs
- * @param pattern - Event pattern (e.g., "auth.login", "*.error", "api.*")
- * @returns Array of matching node IDs
- */
-export function findNodesMatchingEventPattern(
-  eventMap: EventNodeMap,
-  pattern: string
-): string[] {
-  const matchingNodes: string[] = [];
-
-  // Simple glob matching
-  const regexPattern = pattern
-    .replace(/\./g, '\\.') // Escape dots
-    .replace(/\*/g, '.*'); // Convert * to .*
-
-  const regex = new RegExp(`^${regexPattern}$`);
-
-  for (const [eventName, nodeIds] of eventMap) {
-    if (regex.test(eventName)) {
-      matchingNodes.push(...nodeIds);
-    }
-  }
-
-  return matchingNodes;
-}
-
-/**
- * Get all node IDs from a canvas.
- * Useful when no specific workflow/scenario is selected (widest scope).
- *
- * @param canvas - The extended canvas with nodes
- * @returns Array of all node IDs in the canvas
- */
-export function getAllNodeIds(canvas: ExtendedCanvas): string[] {
-  if (!canvas.nodes) {
-    return [];
-  }
-  return canvas.nodes.map((node) => node.id);
-}
-
-// ============================================================================
-// Context Builder
-// ============================================================================
-
-/**
- * Build a complete StoryboardContextSliceData from canvas and optional workflow/scenario.
- *
- * This is the main function for creating the context slice that panels consume.
- *
- * @param options - Build options with canvas, storyboard, and optional workflow/scenario
- * @returns Complete storyboard context slice data
- *
- * @example
- * ```typescript
- * // Just storyboard selected (widest scope)
- * const context = buildStoryboardContext({
- *   canvas: parsedCanvas,
- *   storyboard: { id: 'checkout-flow', name: 'Checkout Flow', path: 'canvas.otel.canvas' },
- * });
- *
- * // With workflow selected (medium scope)
- * const context = buildStoryboardContext({
- *   canvas: parsedCanvas,
- *   storyboard: { id: 'checkout-flow', name: 'Checkout Flow', path: 'canvas.otel.canvas' },
- *   workflow: { template: workflowTemplate, path: 'workflow.workflow.json' },
- * });
- *
- * // With scenario selected (narrowest scope)
- * const context = buildStoryboardContext({
- *   canvas: parsedCanvas,
- *   storyboard: { id: 'checkout-flow', name: 'Checkout Flow', path: 'canvas.otel.canvas' },
- *   workflow: { template: workflowTemplate, path: 'workflow.workflow.json' },
- *   scenario: selectedScenario,
- * });
- * ```
- */
-export function buildStoryboardContext(
-  options: BuildStoryboardContextOptions
-): StoryboardContextSliceData {
-  const { canvas, storyboard, canvasType = 'otel', workflow, scenario, additionalSupportingFiles = [] } = options;
-
-  // Build canvas file manifest
-  const manifest = buildCanvasFileManifest(canvas, storyboard.id, storyboard.path, canvasType);
-
-  // Build supporting files list
-  const supportingFiles: string[] = [storyboard.path];
-  if (workflow) {
-    supportingFiles.push(workflow.path);
-  }
-  // Add markdown doc if canvas has one
-  if (canvas.markdown) {
-    supportingFiles.push(canvas.markdown);
-  }
-  supportingFiles.push(...additionalSupportingFiles);
-
-  // Determine workflow reference
-  let workflowReference: WorkflowReference | null = null;
-  if (workflow) {
-    const workflowNodeIds = resolveWorkflowNodeIds(canvas, workflow.template);
-    workflowReference = {
-      id: `${storyboard.id}/${workflow.template.name.toLowerCase().replace(/\s+/g, '-')}`,
-      name: workflow.template.name,
-      path: workflow.path,
-      nodeIds: workflowNodeIds,
-    };
-  }
-
-  // Determine scenario reference
-  let scenarioReference: ScenarioReference | null = null;
-  if (scenario) {
-    const scenarioNodeIds = resolveScenarioNodeIds(canvas, scenario);
-    scenarioReference = {
-      id: scenario.id,
-      name: scenario.description,
-      nodeIds: scenarioNodeIds,
-    };
-  }
-
-  return {
-    storyboard,
-    workflow: workflowReference,
-    scenario: scenarioReference,
-    manifest,
-    supportingFiles,
-  };
-}

package/src/storyboard/index.ts

@@ -1,26 +0,0 @@
-/**
- * Storyboard Context Module
- *
- * Types and utilities for building storyboard context data that panels consume.
- */
-
-// Types
-export type {
-  StoryboardReference,
-  WorkflowReference,
-  ScenarioReference,
-  StoryboardContextSliceData,
-} from './types';
-
-// Builder utilities
-export {
-  buildStoryboardContext,
-  buildEventNodeMap,
-  getNodeEventName,
-  resolveScenarioNodeIds,
-  resolveWorkflowNodeIds,
-  findNodesMatchingEventPattern,
-  getAllNodeIds,
-} from './builder';
-
-export type { EventNodeMap, BuildStoryboardContextOptions } from './builder';

package/src/storyboard/types.ts

@@ -1,117 +0,0 @@
-/**
- * Storyboard Context Types
- *
- * Types for representing storyboard context data that panels consume.
- * Used to communicate which storyboard/workflow/scenario is selected
- * and provide file manifests for visualization.
- */
-
-import type { CanvasFileManifest } from '../discovery/types';
-
-// ============================================================================
-// Reference Types
-// ============================================================================
-
-/**
- * Reference to a storyboard (canvas) in the storyboard context.
- * Represents the top-level selection in the storyboard hierarchy.
- */
-export interface StoryboardReference {
-  /** Unique storyboard identifier (e.g., "core/checkout-flow") */
-  id: string;
-  /** Display name (e.g., "Checkout Flow") */
-  name: string;
-  /** Path to the canvas file (e.g., ".principal-views/checkout-flow.otel.canvas") */
-  path: string;
-}
-
-/**
- * Reference to a workflow within a storyboard.
- * Workflows define a subset of nodes from the parent canvas.
- */
-export interface WorkflowReference {
-  /** Unique workflow identifier (e.g., "core/checkout-flow/complete-checkout") */
-  id: string;
-  /** Display name (e.g., "Complete Checkout") */
-  name: string;
-  /** Path to the workflow file (e.g., ".principal-views/checkout-flow/complete-checkout.workflow.json") */
-  path: string;
-  /** Canvas node IDs involved in this workflow (resolved from event requirements) */
-  nodeIds: string[];
-}
-
-/**
- * Reference to a scenario within a workflow.
- * Scenarios represent specific execution paths through a workflow.
- */
-export interface ScenarioReference {
-  /** Unique scenario identifier (e.g., "payment-success") */
-  id: string;
-  /** Display name (e.g., "Payment Success") */
-  name: string;
-  /** Canvas node IDs involved in this scenario (subset of workflow nodes) */
-  nodeIds: string[];
-}
-
-// ============================================================================
-// Slice Data Type
-// ============================================================================
-
-/**
- * Storyboard context slice data.
- *
- * Provides context about the currently selected storyboard, workflow, and scenario.
- * Used by panels (like File City) to highlight files associated with the selection.
- *
- * Hierarchy: Storyboard → Workflow → Scenario
- * - 1 Storyboard = 1 Canvas
- * - Workflows contain a subset of nodes from the canvas
- * - Scenarios contain a subset of nodes from their parent workflow
- *
- * @example
- * ```typescript
- * const storyboardContext: StoryboardContextSliceData = {
- *   storyboard: {
- *     id: 'checkout-flow',
- *     name: 'Checkout Flow',
- *     path: '.principal-views/checkout-flow.otel.canvas',
- *   },
- *   workflow: {
- *     id: 'checkout-flow/complete-checkout',
- *     name: 'Complete Checkout',
- *     path: '.principal-views/checkout-flow/complete-checkout.workflow.json',
- *     nodeIds: ['node-cart', 'node-payment', 'node-confirm'],
- *   },
- *   scenario: null,
- *   manifest: { ... }, // CanvasFileManifest with file mappings
- *   supportingFiles: [
- *     '.principal-views/checkout-flow.otel.canvas',
- *     '.principal-views/checkout-flow/complete-checkout.workflow.json',
- *   ],
- * };
- * ```
- */
-export interface StoryboardContextSliceData {
-  /** Currently selected storyboard (1 storyboard = 1 canvas) */
-  storyboard: StoryboardReference | null;
-
-  /** Currently selected workflow (optional, narrower scope than storyboard) */
-  workflow: WorkflowReference | null;
-
-  /** Currently selected scenario (optional, narrowest scope) */
-  scenario: ScenarioReference | null;
-
-  /**
-   * Canvas file manifest with bidirectional mappings.
-   * Use `manifest.nodeToFiles.get(nodeId)` to get files for a node.
-   * Use `manifest.fileToNodes.get(path)` to get nodes for a file.
-   * Use `manifest.byRole.instrumentation` for instrumented files.
-   */
-  manifest: CanvasFileManifest | null;
-
-  /**
-   * Additional files associated with the storyboard context.
-   * Includes canvas files, workflow definitions, and related documentation.
-   */
-  supportingFiles: string[];
-}