@principal-ai/subsystems-core 0.29.0

package/src/storyboard/builder.ts

@@ -0,0 +1,308 @@
+/**
+ * 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

@@ -0,0 +1,26 @@
+/**
+ * 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

@@ -0,0 +1,117 @@
+/**
+ * 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[];
+}