@principal-ai/principal-view-core 0.5.17 → 0.6.1

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export { PathBasedEventProcessor } from './PathBasedEventProcessor';
 export type { LogEntry } from './PathBasedEventProcessor';
 export { PathMatcher } from './utils/PathMatcher';
 export { GraphConverter } from './utils/GraphConverter';
+export { ExecutionFileDiscovery } from './utils/ExecutionFileDiscovery';
+export type { ExecutionFile, CanvasFile, PackageContext, ExecutionMetadata, ExecutionSpan, ExecutionArtifact, FileTreeEntry, DiscoveryOptions, } from './utils/ExecutionFileDiscovery';
 export * from './types/canvas';
 export { CanvasConverter } from './utils/CanvasConverter';
 export type { ReactFlowNode, ReactFlowEdge } from './utils/CanvasConverter';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EACV,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAGlF,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,YAAY,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAG1D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG5E,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAC3G,YAAY,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAGpE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,UAAU,IAAI,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG5G,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACjG,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAG7F,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACzE,YAAY,EACV,SAAS,EACT,WAAW,EACX,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,WAAW,EACX,WAAW,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,eAAe,EACf,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,0BAA0B,GAC3B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACtF,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGrF,YAAY,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAGjF,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -15,6 +15,8 @@ export { PathBasedEventProcessor } from './PathBasedEventProcessor';
 // Export path utilities
 export { PathMatcher } from './utils/PathMatcher';
 export { GraphConverter } from './utils/GraphConverter';
+// Export execution file discovery
+export { ExecutionFileDiscovery } from './utils/ExecutionFileDiscovery';
 // Export Canvas types and converter
 export * from './types/canvas';
 export { CanvasConverter } from './utils/CanvasConverter';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,mBAAmB;AACnB,cAAc,SAAS,CAAC;AAExB,sBAAsB;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAMlE,iBAAiB;AACjB,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAElF,iDAAiD;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAGpE,wBAAwB;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,oCAAoC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,oCAAoC;AACpC,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAG3G,qCAAqC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,yBAAyB;AACzB,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGjG,oCAAoC;AACpC,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAQzE,qDAAqD;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAYlD,gCAAgC;AAChC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAqB9D,+DAA+D;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAGtF,mCAAmC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAK5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAEjF,sBAAsB;AACtB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,mBAAmB;AACnB,cAAc,SAAS,CAAC;AAExB,sBAAsB;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAMlE,iBAAiB;AACjB,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAElF,iDAAiD;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAGpE,wBAAwB;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,kCAAkC;AAClC,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAYxE,oCAAoC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,oCAAoC;AACpC,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAG3G,qCAAqC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,yBAAyB;AACzB,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGjG,oCAAoC;AACpC,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAQzE,qDAAqD;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAYlD,gCAAgC;AAChC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAqB9D,+DAA+D;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAGtF,mCAAmC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAK5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAEjF,sBAAsB;AACtB,cAAc,SAAS,CAAC"}

package/dist/utils/ExecutionFileDiscovery.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Execution File Discovery
+ *
+ * Discovers execution artifacts and canvas files in a repository with monorepo awareness.
+ * Uses codebase-composition (browser-safe export) to intelligently detect package boundaries
+ * and workspace patterns.
+ */
+/**
+ * Represents a discovered execution artifact file
+ */
+export interface ExecutionFile {
+    /** Unique identifier for this execution */
+    id: string;
+    /** Display name for this execution */
+    name: string;
+    /** Full file path (relative to repository root) */
+    path: string;
+    /** Canvas basename (without extension) that this execution is linked to */
+    canvasBasename: string;
+    /** Package context if this execution belongs to a specific package */
+    packageContext?: PackageContext;
+}
+/**
+ * Represents a discovered canvas file
+ */
+export interface CanvasFile {
+    /** Unique identifier for this canvas */
+    id: string;
+    /** Display name for this canvas */
+    name: string;
+    /** Full file path (relative to repository root) */
+    path: string;
+    /** Canvas basename (without .otel.canvas or .canvas extension) */
+    basename: string;
+    /** Package context if this canvas belongs to a specific package */
+    packageContext?: PackageContext;
+}
+/**
+ * Package context for execution/canvas files
+ */
+export interface PackageContext {
+    /** Package name (from package.json, Cargo.toml, etc.) */
+    name: string;
+    /** Package directory path (relative to repository root) */
+    packagePath: string;
+    /** Package type (npm, cargo, go, etc.) */
+    packageType?: string;
+}
+/**
+ * Execution artifact metadata
+ */
+export interface ExecutionMetadata {
+    name: string;
+    canvasName?: string;
+    exportedAt?: string;
+    source?: string;
+    framework?: string;
+    status?: 'success' | 'error' | 'OK';
+    spanCount: number;
+    eventCount: number;
+}
+/**
+ * Execution span structure
+ */
+export interface ExecutionSpan {
+    id: string;
+    name: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    status?: string;
+    attributes?: Record<string, any>;
+    events: Array<{
+        time: number;
+        name: string;
+        attributes?: Record<string, any>;
+    }>;
+}
+/**
+ * Execution artifact file structure
+ */
+export interface ExecutionArtifact {
+    metadata?: {
+        canvasName?: string;
+        exportedAt?: string;
+        source?: string;
+        framework?: string;
+        status?: 'success' | 'error';
+    };
+    spans: ExecutionSpan[];
+}
+/**
+ * File tree entry for discovery
+ */
+export interface FileTreeEntry {
+    path?: string;
+    relativePath?: string;
+    name?: string;
+}
+/**
+ * Options for execution file discovery
+ */
+export interface DiscoveryOptions {
+    /** Whether to include package-level .principal-views folders */
+    includePackagePrincipalViews?: boolean;
+    /** Custom execution folder names (defaults to ['__executions__']) */
+    executionFolders?: string[];
+    /** Custom canvas extensions (defaults to ['.otel.canvas']) */
+    canvasExtensions?: string[];
+}
+/**
+ * Execution File Discovery Engine
+ *
+ * Discovers execution artifacts and canvas files using monorepo-aware logic.
+ */
+export declare class ExecutionFileDiscovery {
+    private packageLayerModule;
+    private options;
+    constructor(options?: DiscoveryOptions);
+    /**
+     * Find all execution artifact files in the repository
+     */
+    findExecutionFiles(files: FileTreeEntry[]): Promise<ExecutionFile[]>;
+    /**
+     * Find all canvas files in the repository
+     */
+    findCanvasFiles(files: FileTreeEntry[]): Promise<CanvasFile[]>;
+    /**
+     * Find execution artifact for a given canvas
+     * Now package-aware - can disambiguate between packages
+     */
+    findExecutionForCanvas(canvas: CanvasFile, executionFiles: ExecutionFile[]): ExecutionFile | null;
+    /**
+     * Find canvas file for a given execution
+     */
+    findCanvasForExecution(execution: ExecutionFile, canvasFiles: CanvasFile[]): CanvasFile | null;
+    /**
+     * Parse execution artifact JSON
+     */
+    static parseExecutionArtifact(content: string): ExecutionArtifact;
+    /**
+     * Get spans from an artifact
+     */
+    static getSpans(artifact: ExecutionArtifact): ExecutionSpan[];
+    /**
+     * Extract metadata from an execution artifact
+     */
+    static getExecutionMetadata(artifact: ExecutionArtifact): ExecutionMetadata;
+    /**
+     * Detect packages using codebase-composition
+     */
+    private detectPackages;
+    /**
+     * Convert file entries to file tree format for codebase-composition
+     */
+    private convertToFileTree;
+    /**
+     * Find executions in a specific package
+     */
+    private findExecutionsInPackage;
+    /**
+     * Find executions in root-level locations
+     */
+    private findExecutionsInRoot;
+    /**
+     * Find canvas files in a specific directory
+     */
+    private findCanvasesInDirectory;
+    /**
+     * Create package context from PackageLayer
+     */
+    private createPackageContext;
+    /**
+     * Check if filename is an execution file
+     */
+    private isExecutionFile;
+    /**
+     * Check if filename is a canvas file
+     */
+    private isCanvasFile;
+    /**
+     * Extract basename from execution filename
+     */
+    private extractExecutionBasename;
+    /**
+     * Extract basename from canvas filename
+     */
+    private extractCanvasBasename;
+    /**
+     * Format display name from basename (kebab-case to Title Case)
+     */
+    private formatDisplayName;
+    /**
+     * Generate unique ID for execution file
+     */
+    private generateExecutionId;
+    /**
+     * Generate unique ID for canvas file
+     */
+    private generateCanvasId;
+    /**
+     * Sort execution files by package name, then by basename
+     */
+    private sortExecutionFiles;
+}
+//# sourceMappingURL=ExecutionFileDiscovery.d.ts.map

package/dist/utils/ExecutionFileDiscovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionFileDiscovery.d.ts","sourceRoot":"","sources":["../../src/utils/ExecutionFileDiscovery.ts"],"names":[],"mappings":"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"}

package/dist/utils/ExecutionFileDiscovery.js

@@ -0,0 +1,340 @@
+/**
+ * Execution File Discovery
+ *
+ * Discovers execution artifacts and canvas files in a repository with monorepo awareness.
+ * Uses codebase-composition (browser-safe export) to intelligently detect package boundaries
+ * and workspace patterns.
+ */
+import { PackageLayerModule } from '@principal-ai/codebase-composition/browser';
+/**
+ * Execution File Discovery Engine
+ *
+ * Discovers execution artifacts and canvas files using monorepo-aware logic.
+ */
+export class ExecutionFileDiscovery {
+    constructor(options = {}) {
+        this.packageLayerModule = new PackageLayerModule();
+        this.options = {
+            includePackagePrincipalViews: options.includePackagePrincipalViews ?? true,
+            executionFolders: options.executionFolders ?? ['__executions__'],
+            canvasExtensions: options.canvasExtensions ?? ['.otel.canvas'],
+        };
+    }
+    /**
+     * Find all execution artifact files in the repository
+     */
+    async findExecutionFiles(files) {
+        const executionFiles = [];
+        // Detect packages in the repository
+        const packages = await this.detectPackages(files);
+        // Search for execution files in each package
+        for (const pkg of packages) {
+            const pkgExecutions = this.findExecutionsInPackage(pkg, files);
+            executionFiles.push(...pkgExecutions);
+        }
+        // Search in root-level locations
+        const rootExecutions = this.findExecutionsInRoot(files);
+        executionFiles.push(...rootExecutions);
+        // Sort by package name, then by basename
+        return this.sortExecutionFiles(executionFiles);
+    }
+    /**
+     * Find all canvas files in the repository
+     */
+    async findCanvasFiles(files) {
+        const canvasFiles = [];
+        // Detect packages in the repository
+        const packages = await this.detectPackages(files);
+        // Search for canvas files in root .principal-views/
+        const rootCanvases = this.findCanvasesInDirectory('.principal-views', files);
+        canvasFiles.push(...rootCanvases);
+        // Search for canvas files in package-level .principal-views/ if enabled
+        if (this.options.includePackagePrincipalViews) {
+            for (const pkg of packages) {
+                const pkgCanvases = this.findCanvasesInDirectory(`${pkg.packageData.path}/.principal-views`, files, this.createPackageContext(pkg));
+                canvasFiles.push(...pkgCanvases);
+            }
+        }
+        // Sort by name
+        return canvasFiles.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /**
+     * Find execution artifact for a given canvas
+     * Now package-aware - can disambiguate between packages
+     */
+    findExecutionForCanvas(canvas, executionFiles) {
+        // First, try exact package match if canvas has package context
+        if (canvas.packageContext) {
+            const exactMatch = executionFiles.find(exec => exec.canvasBasename === canvas.basename &&
+                exec.packageContext?.name === canvas.packageContext?.name);
+            if (exactMatch)
+                return exactMatch;
+        }
+        // Fallback to basename-only match (for root-level canvases)
+        return executionFiles.find(exec => exec.canvasBasename === canvas.basename) || null;
+    }
+    /**
+     * Find canvas file for a given execution
+     */
+    findCanvasForExecution(execution, canvasFiles) {
+        // First, try exact package match if execution has package context
+        if (execution.packageContext) {
+            const exactMatch = canvasFiles.find(canvas => canvas.basename === execution.canvasBasename &&
+                canvas.packageContext?.name === execution.packageContext?.name);
+            if (exactMatch)
+                return exactMatch;
+        }
+        // Fallback to basename-only match (for root-level executions)
+        return canvasFiles.find(canvas => canvas.basename === execution.canvasBasename) || null;
+    }
+    /**
+     * Parse execution artifact JSON
+     */
+    static parseExecutionArtifact(content) {
+        try {
+            const parsed = JSON.parse(content);
+            return parsed;
+        }
+        catch (error) {
+            throw new Error(`Failed to parse execution artifact JSON: ${error.message}`);
+        }
+    }
+    /**
+     * Get spans from an artifact
+     */
+    static getSpans(artifact) {
+        return artifact.spans || [];
+    }
+    /**
+     * Extract metadata from an execution artifact
+     */
+    static getExecutionMetadata(artifact) {
+        const spans = ExecutionFileDiscovery.getSpans(artifact);
+        const spanCount = spans.length;
+        const eventCount = spans.reduce((total, span) => {
+            return total + (span.events?.length || 0);
+        }, 0);
+        const metadata = artifact.metadata;
+        let status = 'success';
+        if (metadata?.status) {
+            status = metadata.status;
+        }
+        else if (spans.length > 0) {
+            const hasError = spans.some(s => s.status === 'ERROR' || s.status === 'error' || s.status === 'FAILED');
+            status = hasError ? 'error' : 'OK';
+        }
+        return {
+            name: metadata?.canvasName || 'Untitled Execution',
+            canvasName: metadata?.canvasName,
+            exportedAt: metadata?.exportedAt,
+            source: metadata?.source,
+            framework: metadata?.framework,
+            status,
+            spanCount,
+            eventCount,
+        };
+    }
+    // Private helper methods
+    /**
+     * Detect packages using codebase-composition
+     */
+    async detectPackages(files) {
+        try {
+            // Convert files to the format expected by codebase-composition
+            const fileTree = this.convertToFileTree(files);
+            const packages = await this.packageLayerModule.discoverPackages(fileTree);
+            return packages || [];
+        }
+        catch (error) {
+            // If package detection fails, continue with fallback patterns
+            console.warn('Package detection failed, using fallback patterns:', error);
+            return [];
+        }
+    }
+    /**
+     * Convert file entries to file tree format for codebase-composition
+     */
+    convertToFileTree(files) {
+        // This is a simplified conversion - codebase-composition expects a specific format
+        // In practice, the caller should provide a proper FileTree from repository-abstraction
+        return {
+            files: files.map(f => ({
+                path: f.relativePath || f.path || '',
+                name: f.name || (f.relativePath || f.path || '').split('/').pop() || '',
+            })),
+        };
+    }
+    /**
+     * Find executions in a specific package
+     */
+    findExecutionsInPackage(pkg, files) {
+        const executions = [];
+        const pkgPath = pkg.packageData.path || '';
+        const packageContext = this.createPackageContext(pkg);
+        for (const execFolder of this.options.executionFolders) {
+            const execPath = pkgPath ? `${pkgPath}/${execFolder}` : execFolder;
+            for (const file of files) {
+                const filePath = file.relativePath || file.path || '';
+                const fileName = file.name || filePath.split('/').pop() || '';
+                if (filePath.startsWith(execPath + '/') && this.isExecutionFile(fileName)) {
+                    const basename = this.extractExecutionBasename(fileName);
+                    executions.push({
+                        id: this.generateExecutionId(basename, packageContext),
+                        name: this.formatDisplayName(basename),
+                        path: filePath,
+                        canvasBasename: basename,
+                        packageContext,
+                    });
+                }
+            }
+        }
+        return executions;
+    }
+    /**
+     * Find executions in root-level locations
+     */
+    findExecutionsInRoot(files) {
+        const executions = [];
+        // Root __executions__/
+        for (const execFolder of this.options.executionFolders) {
+            for (const file of files) {
+                const filePath = file.relativePath || file.path || '';
+                const fileName = file.name || filePath.split('/').pop() || '';
+                if (filePath.startsWith(`${execFolder}/`) && this.isExecutionFile(fileName)) {
+                    const basename = this.extractExecutionBasename(fileName);
+                    executions.push({
+                        id: `root-${basename}`,
+                        name: this.formatDisplayName(basename),
+                        path: filePath,
+                        canvasBasename: basename,
+                    });
+                }
+            }
+        }
+        // .principal-views/__executions__/
+        const pvExecPath = '.principal-views/__executions__';
+        for (const file of files) {
+            const filePath = file.relativePath || file.path || '';
+            const fileName = file.name || filePath.split('/').pop() || '';
+            if (filePath.startsWith(pvExecPath + '/') && this.isExecutionFile(fileName)) {
+                const basename = this.extractExecutionBasename(fileName);
+                executions.push({
+                    id: `pv-${basename}`,
+                    name: this.formatDisplayName(basename),
+                    path: filePath,
+                    canvasBasename: basename,
+                });
+            }
+        }
+        return executions;
+    }
+    /**
+     * Find canvas files in a specific directory
+     */
+    findCanvasesInDirectory(directory, files, packageContext) {
+        const canvases = [];
+        for (const file of files) {
+            const filePath = file.relativePath || file.path || '';
+            const fileName = file.name || filePath.split('/').pop() || '';
+            if (filePath.startsWith(directory + '/') && this.isCanvasFile(fileName)) {
+                const basename = this.extractCanvasBasename(fileName);
+                canvases.push({
+                    id: this.generateCanvasId(basename, packageContext),
+                    name: this.formatDisplayName(basename),
+                    path: filePath,
+                    basename,
+                    packageContext,
+                });
+            }
+        }
+        return canvases;
+    }
+    /**
+     * Create package context from PackageLayer
+     */
+    createPackageContext(pkg) {
+        return {
+            name: pkg.packageData.name || 'unknown',
+            packagePath: pkg.packageData.path || '',
+            packageType: pkg.type,
+        };
+    }
+    /**
+     * Check if filename is an execution file
+     */
+    isExecutionFile(filename) {
+        return /\.(spans|execution|events)\.json$/.test(filename);
+    }
+    /**
+     * Check if filename is a canvas file
+     */
+    isCanvasFile(filename) {
+        return this.options.canvasExtensions.some(ext => filename.endsWith(ext));
+    }
+    /**
+     * Extract basename from execution filename
+     */
+    extractExecutionBasename(filename) {
+        return filename.replace(/\.(spans|execution|events)\.json$/, '');
+    }
+    /**
+     * Extract basename from canvas filename
+     */
+    extractCanvasBasename(filename) {
+        for (const ext of this.options.canvasExtensions) {
+            if (filename.endsWith(ext)) {
+                return filename.slice(0, -ext.length);
+            }
+        }
+        return filename;
+    }
+    /**
+     * Format display name from basename (kebab-case to Title Case)
+     */
+    formatDisplayName(basename) {
+        return basename
+            .split('-')
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    }
+    /**
+     * Generate unique ID for execution file
+     */
+    generateExecutionId(basename, packageContext) {
+        if (packageContext) {
+            return `${packageContext.name}-${basename}`;
+        }
+        return basename;
+    }
+    /**
+     * Generate unique ID for canvas file
+     */
+    generateCanvasId(basename, packageContext) {
+        if (packageContext) {
+            return `${packageContext.name}-${basename}`;
+        }
+        return basename;
+    }
+    /**
+     * Sort execution files by package name, then by basename
+     */
+    sortExecutionFiles(files) {
+        return files.sort((a, b) => {
+            // Sort by package name first
+            if (a.packageContext && b.packageContext) {
+                const pkgCompare = a.packageContext.name.localeCompare(b.packageContext.name);
+                if (pkgCompare !== 0)
+                    return pkgCompare;
+            }
+            else if (a.packageContext) {
+                return -1;
+            }
+            else if (b.packageContext) {
+                return 1;
+            }
+            // Then by basename
+            return a.canvasBasename.localeCompare(b.canvasBasename);
+        });
+    }
+}
+//# sourceMappingURL=ExecutionFileDiscovery.js.map

package/dist/utils/ExecutionFileDiscovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionFileDiscovery.js","sourceRoot":"","sources":["../../src/utils/ExecutionFileDiscovery.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/principal-view-core",
-  "version": "0.5.17",
+  "version": "0.6.1",
   "description": "Core logic and types for graph-based principal view framework",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -28,6 +28,7 @@
     "zod": "^3.22.0",
     "date-fns": "^3.0.0",
     "@principal-ai/repository-abstraction": "^0.2.5",
+    "@principal-ai/codebase-composition": "^0.2.32",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -29,6 +29,19 @@ export type { LogEntry } from './PathBasedEventProcessor';
 export { PathMatcher } from './utils/PathMatcher';
 export { GraphConverter } from './utils/GraphConverter';
 
+// Export execution file discovery
+export { ExecutionFileDiscovery } from './utils/ExecutionFileDiscovery';
+export type {
+  ExecutionFile,
+  CanvasFile,
+  PackageContext,
+  ExecutionMetadata,
+  ExecutionSpan,
+  ExecutionArtifact,
+  FileTreeEntry,
+  DiscoveryOptions,
+} from './utils/ExecutionFileDiscovery';
+
 // Export Canvas types and converter
 export * from './types/canvas';
 export { CanvasConverter } from './utils/CanvasConverter';

package/src/utils/ExecutionFileDiscovery.ts

@@ -0,0 +1,522 @@
+/**
+ * Execution File Discovery
+ *
+ * Discovers execution artifacts and canvas files in a repository with monorepo awareness.
+ * Uses codebase-composition (browser-safe export) to intelligently detect package boundaries
+ * and workspace patterns.
+ */
+
+import { PackageLayerModule } from '@principal-ai/codebase-composition/browser';
+import type { PackageLayer } from '@principal-ai/codebase-composition/browser';
+
+/**
+ * Represents a discovered execution artifact file
+ */
+export interface ExecutionFile {
+  /** Unique identifier for this execution */
+  id: string;
+  /** Display name for this execution */
+  name: string;
+  /** Full file path (relative to repository root) */
+  path: string;
+  /** Canvas basename (without extension) that this execution is linked to */
+  canvasBasename: string;
+  /** Package context if this execution belongs to a specific package */
+  packageContext?: PackageContext;
+}
+
+/**
+ * Represents a discovered canvas file
+ */
+export interface CanvasFile {
+  /** Unique identifier for this canvas */
+  id: string;
+  /** Display name for this canvas */
+  name: string;
+  /** Full file path (relative to repository root) */
+  path: string;
+  /** Canvas basename (without .otel.canvas or .canvas extension) */
+  basename: string;
+  /** Package context if this canvas belongs to a specific package */
+  packageContext?: PackageContext;
+}
+
+/**
+ * Package context for execution/canvas files
+ */
+export interface PackageContext {
+  /** Package name (from package.json, Cargo.toml, etc.) */
+  name: string;
+  /** Package directory path (relative to repository root) */
+  packagePath: string;
+  /** Package type (npm, cargo, go, etc.) */
+  packageType?: string;
+}
+
+/**
+ * Execution artifact metadata
+ */
+export interface ExecutionMetadata {
+  name: string;
+  canvasName?: string;
+  exportedAt?: string;
+  source?: string;
+  framework?: string;
+  status?: 'success' | 'error' | 'OK';
+  spanCount: number;
+  eventCount: number;
+}
+
+/**
+ * Execution span structure
+ */
+export interface ExecutionSpan {
+  id: string;
+  name: string;
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  status?: string;
+  attributes?: Record<string, any>;
+  events: Array<{
+    time: number;
+    name: string;
+    attributes?: Record<string, any>;
+  }>;
+}
+
+/**
+ * Execution artifact file structure
+ */
+export interface ExecutionArtifact {
+  metadata?: {
+    canvasName?: string;
+    exportedAt?: string;
+    source?: string;
+    framework?: string;
+    status?: 'success' | 'error';
+  };
+  spans: ExecutionSpan[];
+}
+
+/**
+ * File tree entry for discovery
+ */
+export interface FileTreeEntry {
+  path?: string;
+  relativePath?: string;
+  name?: string;
+}
+
+/**
+ * Options for execution file discovery
+ */
+export interface DiscoveryOptions {
+  /** Whether to include package-level .principal-views folders */
+  includePackagePrincipalViews?: boolean;
+  /** Custom execution folder names (defaults to ['__executions__']) */
+  executionFolders?: string[];
+  /** Custom canvas extensions (defaults to ['.otel.canvas']) */
+  canvasExtensions?: string[];
+}
+
+/**
+ * Execution File Discovery Engine
+ *
+ * Discovers execution artifacts and canvas files using monorepo-aware logic.
+ */
+export class ExecutionFileDiscovery {
+  private packageLayerModule: PackageLayerModule;
+  private options: Required<DiscoveryOptions>;
+
+  constructor(options: DiscoveryOptions = {}) {
+    this.packageLayerModule = new PackageLayerModule();
+    this.options = {
+      includePackagePrincipalViews: options.includePackagePrincipalViews ?? true,
+      executionFolders: options.executionFolders ?? ['__executions__'],
+      canvasExtensions: options.canvasExtensions ?? ['.otel.canvas'],
+    };
+  }
+
+  /**
+   * Find all execution artifact files in the repository
+   */
+  async findExecutionFiles(files: FileTreeEntry[]): Promise<ExecutionFile[]> {
+    const executionFiles: ExecutionFile[] = [];
+
+    // Detect packages in the repository
+    const packages = await this.detectPackages(files);
+
+    // Search for execution files in each package
+    for (const pkg of packages) {
+      const pkgExecutions = this.findExecutionsInPackage(pkg, files);
+      executionFiles.push(...pkgExecutions);
+    }
+
+    // Search in root-level locations
+    const rootExecutions = this.findExecutionsInRoot(files);
+    executionFiles.push(...rootExecutions);
+
+    // Sort by package name, then by basename
+    return this.sortExecutionFiles(executionFiles);
+  }
+
+  /**
+   * Find all canvas files in the repository
+   */
+  async findCanvasFiles(files: FileTreeEntry[]): Promise<CanvasFile[]> {
+    const canvasFiles: CanvasFile[] = [];
+
+    // Detect packages in the repository
+    const packages = await this.detectPackages(files);
+
+    // Search for canvas files in root .principal-views/
+    const rootCanvases = this.findCanvasesInDirectory('.principal-views', files);
+    canvasFiles.push(...rootCanvases);
+
+    // Search for canvas files in package-level .principal-views/ if enabled
+    if (this.options.includePackagePrincipalViews) {
+      for (const pkg of packages) {
+        const pkgCanvases = this.findCanvasesInDirectory(
+          `${pkg.packageData.path}/.principal-views`,
+          files,
+          this.createPackageContext(pkg)
+        );
+        canvasFiles.push(...pkgCanvases);
+      }
+    }
+
+    // Sort by name
+    return canvasFiles.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /**
+   * Find execution artifact for a given canvas
+   * Now package-aware - can disambiguate between packages
+   */
+  findExecutionForCanvas(
+    canvas: CanvasFile,
+    executionFiles: ExecutionFile[]
+  ): ExecutionFile | null {
+    // First, try exact package match if canvas has package context
+    if (canvas.packageContext) {
+      const exactMatch = executionFiles.find(
+        exec =>
+          exec.canvasBasename === canvas.basename &&
+          exec.packageContext?.name === canvas.packageContext?.name
+      );
+      if (exactMatch) return exactMatch;
+    }
+
+    // Fallback to basename-only match (for root-level canvases)
+    return executionFiles.find(exec => exec.canvasBasename === canvas.basename) || null;
+  }
+
+  /**
+   * Find canvas file for a given execution
+   */
+  findCanvasForExecution(
+    execution: ExecutionFile,
+    canvasFiles: CanvasFile[]
+  ): CanvasFile | null {
+    // First, try exact package match if execution has package context
+    if (execution.packageContext) {
+      const exactMatch = canvasFiles.find(
+        canvas =>
+          canvas.basename === execution.canvasBasename &&
+          canvas.packageContext?.name === execution.packageContext?.name
+      );
+      if (exactMatch) return exactMatch;
+    }
+
+    // Fallback to basename-only match (for root-level executions)
+    return canvasFiles.find(canvas => canvas.basename === execution.canvasBasename) || null;
+  }
+
+  /**
+   * Parse execution artifact JSON
+   */
+  static parseExecutionArtifact(content: string): ExecutionArtifact {
+    try {
+      const parsed = JSON.parse(content);
+      return parsed as ExecutionArtifact;
+    } catch (error) {
+      throw new Error(`Failed to parse execution artifact JSON: ${(error as Error).message}`);
+    }
+  }
+
+  /**
+   * Get spans from an artifact
+   */
+  static getSpans(artifact: ExecutionArtifact): ExecutionSpan[] {
+    return artifact.spans || [];
+  }
+
+  /**
+   * Extract metadata from an execution artifact
+   */
+  static getExecutionMetadata(artifact: ExecutionArtifact): ExecutionMetadata {
+    const spans = ExecutionFileDiscovery.getSpans(artifact);
+    const spanCount = spans.length;
+
+    const eventCount = spans.reduce((total, span) => {
+      return total + (span.events?.length || 0);
+    }, 0);
+
+    const metadata = artifact.metadata;
+
+    let status: 'success' | 'error' | 'OK' = 'success';
+    if (metadata?.status) {
+      status = metadata.status;
+    } else if (spans.length > 0) {
+      const hasError = spans.some(
+        s => s.status === 'ERROR' || s.status === 'error' || s.status === 'FAILED'
+      );
+      status = hasError ? 'error' : 'OK';
+    }
+
+    return {
+      name: metadata?.canvasName || 'Untitled Execution',
+      canvasName: metadata?.canvasName,
+      exportedAt: metadata?.exportedAt,
+      source: metadata?.source,
+      framework: metadata?.framework,
+      status,
+      spanCount,
+      eventCount,
+    };
+  }
+
+  // Private helper methods
+
+  /**
+   * Detect packages using codebase-composition
+   */
+  private async detectPackages(files: FileTreeEntry[]): Promise<PackageLayer[]> {
+    try {
+      // Convert files to the format expected by codebase-composition
+      const fileTree = this.convertToFileTree(files);
+      const packages = await this.packageLayerModule.discoverPackages(fileTree);
+      return packages || [];
+    } catch (error) {
+      // If package detection fails, continue with fallback patterns
+      console.warn('Package detection failed, using fallback patterns:', error);
+      return [];
+    }
+  }
+
+  /**
+   * Convert file entries to file tree format for codebase-composition
+   */
+  private convertToFileTree(files: FileTreeEntry[]): any {
+    // This is a simplified conversion - codebase-composition expects a specific format
+    // In practice, the caller should provide a proper FileTree from repository-abstraction
+    return {
+      files: files.map(f => ({
+        path: f.relativePath || f.path || '',
+        name: f.name || (f.relativePath || f.path || '').split('/').pop() || '',
+      })),
+    };
+  }
+
+  /**
+   * Find executions in a specific package
+   */
+  private findExecutionsInPackage(
+    pkg: PackageLayer,
+    files: FileTreeEntry[]
+  ): ExecutionFile[] {
+    const executions: ExecutionFile[] = [];
+    const pkgPath = pkg.packageData.path || '';
+    const packageContext = this.createPackageContext(pkg);
+
+    for (const execFolder of this.options.executionFolders) {
+      const execPath = pkgPath ? `${pkgPath}/${execFolder}` : execFolder;
+
+      for (const file of files) {
+        const filePath = file.relativePath || file.path || '';
+        const fileName = file.name || filePath.split('/').pop() || '';
+
+        if (filePath.startsWith(execPath + '/') && this.isExecutionFile(fileName)) {
+          const basename = this.extractExecutionBasename(fileName);
+          executions.push({
+            id: this.generateExecutionId(basename, packageContext),
+            name: this.formatDisplayName(basename),
+            path: filePath,
+            canvasBasename: basename,
+            packageContext,
+          });
+        }
+      }
+    }
+
+    return executions;
+  }
+
+  /**
+   * Find executions in root-level locations
+   */
+  private findExecutionsInRoot(files: FileTreeEntry[]): ExecutionFile[] {
+    const executions: ExecutionFile[] = [];
+
+    // Root __executions__/
+    for (const execFolder of this.options.executionFolders) {
+      for (const file of files) {
+        const filePath = file.relativePath || file.path || '';
+        const fileName = file.name || filePath.split('/').pop() || '';
+
+        if (filePath.startsWith(`${execFolder}/`) && this.isExecutionFile(fileName)) {
+          const basename = this.extractExecutionBasename(fileName);
+          executions.push({
+            id: `root-${basename}`,
+            name: this.formatDisplayName(basename),
+            path: filePath,
+            canvasBasename: basename,
+          });
+        }
+      }
+    }
+
+    // .principal-views/__executions__/
+    const pvExecPath = '.principal-views/__executions__';
+    for (const file of files) {
+      const filePath = file.relativePath || file.path || '';
+      const fileName = file.name || filePath.split('/').pop() || '';
+
+      if (filePath.startsWith(pvExecPath + '/') && this.isExecutionFile(fileName)) {
+        const basename = this.extractExecutionBasename(fileName);
+        executions.push({
+          id: `pv-${basename}`,
+          name: this.formatDisplayName(basename),
+          path: filePath,
+          canvasBasename: basename,
+        });
+      }
+    }
+
+    return executions;
+  }
+
+  /**
+   * Find canvas files in a specific directory
+   */
+  private findCanvasesInDirectory(
+    directory: string,
+    files: FileTreeEntry[],
+    packageContext?: PackageContext
+  ): CanvasFile[] {
+    const canvases: CanvasFile[] = [];
+
+    for (const file of files) {
+      const filePath = file.relativePath || file.path || '';
+      const fileName = file.name || filePath.split('/').pop() || '';
+
+      if (filePath.startsWith(directory + '/') && this.isCanvasFile(fileName)) {
+        const basename = this.extractCanvasBasename(fileName);
+        canvases.push({
+          id: this.generateCanvasId(basename, packageContext),
+          name: this.formatDisplayName(basename),
+          path: filePath,
+          basename,
+          packageContext,
+        });
+      }
+    }
+
+    return canvases;
+  }
+
+  /**
+   * Create package context from PackageLayer
+   */
+  private createPackageContext(pkg: PackageLayer): PackageContext {
+    return {
+      name: pkg.packageData.name || 'unknown',
+      packagePath: pkg.packageData.path || '',
+      packageType: pkg.type,
+    };
+  }
+
+  /**
+   * Check if filename is an execution file
+   */
+  private isExecutionFile(filename: string): boolean {
+    return /\.(spans|execution|events)\.json$/.test(filename);
+  }
+
+  /**
+   * Check if filename is a canvas file
+   */
+  private isCanvasFile(filename: string): boolean {
+    return this.options.canvasExtensions.some(ext => filename.endsWith(ext));
+  }
+
+  /**
+   * Extract basename from execution filename
+   */
+  private extractExecutionBasename(filename: string): string {
+    return filename.replace(/\.(spans|execution|events)\.json$/, '');
+  }
+
+  /**
+   * Extract basename from canvas filename
+   */
+  private extractCanvasBasename(filename: string): string {
+    for (const ext of this.options.canvasExtensions) {
+      if (filename.endsWith(ext)) {
+        return filename.slice(0, -ext.length);
+      }
+    }
+    return filename;
+  }
+
+  /**
+   * Format display name from basename (kebab-case to Title Case)
+   */
+  private formatDisplayName(basename: string): string {
+    return basename
+      .split('-')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+
+  /**
+   * Generate unique ID for execution file
+   */
+  private generateExecutionId(basename: string, packageContext?: PackageContext): string {
+    if (packageContext) {
+      return `${packageContext.name}-${basename}`;
+    }
+    return basename;
+  }
+
+  /**
+   * Generate unique ID for canvas file
+   */
+  private generateCanvasId(basename: string, packageContext?: PackageContext): string {
+    if (packageContext) {
+      return `${packageContext.name}-${basename}`;
+    }
+    return basename;
+  }
+
+  /**
+   * Sort execution files by package name, then by basename
+   */
+  private sortExecutionFiles(files: ExecutionFile[]): ExecutionFile[] {
+    return files.sort((a, b) => {
+      // Sort by package name first
+      if (a.packageContext && b.packageContext) {
+        const pkgCompare = a.packageContext.name.localeCompare(b.packageContext.name);
+        if (pkgCompare !== 0) return pkgCompare;
+      } else if (a.packageContext) {
+        return -1;
+      } else if (b.packageContext) {
+        return 1;
+      }
+
+      // Then by basename
+      return a.canvasBasename.localeCompare(b.canvasBasename);
+    });
+  }
+}