@principal-ai/subsystems-core 0.29.0

package/dist/discovery/LibraryDiscovery.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Library Discovery System
+ *
+ * Discovers all library.yaml files across a monorepo's packages and loads their resources.
+ * This is the package-aware equivalent of LibraryLoader.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LibraryDiscovery = void 0;
+const codebase_composition_1 = require("@principal-ai/codebase-composition");
+const LibraryLoader_1 = require("../LibraryLoader");
+const utils_1 = require("../scopes/utils");
+/**
+ * Discovery system for finding and loading all library.yaml files in a monorepo
+ *
+ * @example
+ * ```typescript
+ * const discovery = new LibraryDiscovery(fsAdapter);
+ * const result = await discovery.discover(fileTree);
+ *
+ * console.log('Found libraries:', result.libraries.length);
+ * console.log('All services:', result.allServiceNames);
+ * ```
+ */
+class LibraryDiscovery {
+    constructor(fsAdapter) {
+        this.fsAdapter = fsAdapter;
+        this.packageCache = new Map();
+        this.packageModule = new codebase_composition_1.PackageLayerModule();
+        this.loader = new LibraryLoader_1.LibraryLoader(fsAdapter);
+    }
+    /**
+     * Discover all library.yaml files in the file tree
+     *
+     * @param fileTree - FileTree from repository-abstraction
+     * @param options - Discovery options
+     * @param options.fileReader - Optional function to read file contents (for package.json parsing)
+     * @param options.requireScopesCanvas - If true, validates that .scopes.canvas exists when owned-scopes is defined (default: true)
+     * @returns Discovery result with libraries, service names, and errors
+     */
+    async discover(fileTree, options) {
+        const { fileReader, requireScopesCanvas = true } = options || {};
+        const errors = [];
+        const libraries = [];
+        // 1. Discover packages (with caching by fileTree.sha)
+        const packages = await this.discoverPackagesWithCache(fileTree, fileReader);
+        // 2. For each package, try to load its library.yaml
+        // Note: pkg.packageData.path is relative (e.g., '' for root or 'packages/foo' for nested)
+        // We must resolve against fileTree.root.path to get absolute paths for fsAdapter calls
+        const rootPath = fileTree.root.path;
+        for (const pkg of packages) {
+            try {
+                // Resolve package path to absolute
+                const absolutePackagePath = pkg.packageData.path
+                    ? this.fsAdapter.join(rootPath, pkg.packageData.path)
+                    : rootPath;
+                // Check if this package has a .principal-views directory
+                const pvDir = this.fsAdapter.join(absolutePackagePath, LibraryDiscovery.CANVAS_DIR);
+                const pvDirExists = await this.fsAdapter.exists(pvDir);
+                if (!pvDirExists) {
+                    continue; // No .principal-views directory, skip
+                }
+                // Try to load library from this package
+                const loadResult = await this.loader.load(absolutePackagePath);
+                if (loadResult.success && loadResult.library) {
+                    // Extract service names and owned scopes from resources
+                    const { serviceNames, servicesWithScopes } = this.extractServicesInfo(loadResult.library);
+                    libraries.push({
+                        path: loadResult.path,
+                        packageName: pkg.packageData.name,
+                        packagePath: pkg.packageData.path,
+                        library: loadResult.library,
+                        serviceNames,
+                        servicesWithScopes,
+                    });
+                    // Validate scopes canvas requirement
+                    if (requireScopesCanvas) {
+                        await this.validateScopesCanvasRequirement(absolutePackagePath, servicesWithScopes, loadResult.path, errors);
+                    }
+                }
+                else if (loadResult.error && !loadResult.error.includes('No library file found')) {
+                    // Only report errors that aren't "file not found" (which is normal)
+                    errors.push({
+                        path: loadResult.path,
+                        message: loadResult.error,
+                        type: 'parse-error',
+                    });
+                }
+            }
+            catch (error) {
+                errors.push({
+                    path: pkg.packageData.path,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        // 3. Also check root directory for a library.yaml (non-package libraries)
+        try {
+            const rootPath = fileTree.root.path;
+            const hasRootLibrary = await this.loader.hasLibrary(rootPath);
+            if (hasRootLibrary) {
+                const loadResult = await this.loader.load(rootPath);
+                if (loadResult.success && loadResult.library) {
+                    const { serviceNames, servicesWithScopes } = this.extractServicesInfo(loadResult.library);
+                    // Check if we already loaded this from a package
+                    const alreadyLoaded = libraries.some(lib => lib.path === loadResult.path);
+                    if (!alreadyLoaded) {
+                        libraries.push({
+                            path: loadResult.path,
+                            packageName: 'root',
+                            packagePath: rootPath,
+                            library: loadResult.library,
+                            serviceNames,
+                            servicesWithScopes,
+                        });
+                        // Validate scopes canvas requirement for root library
+                        if (requireScopesCanvas) {
+                            await this.validateScopesCanvasRequirement(rootPath, servicesWithScopes, loadResult.path, errors);
+                        }
+                    }
+                }
+                else if (loadResult.error) {
+                    errors.push({
+                        path: loadResult.path,
+                        message: loadResult.error,
+                        type: 'parse-error',
+                    });
+                }
+            }
+        }
+        catch (error) {
+            // Ignore root library errors
+        }
+        // 4. Collect all service names
+        const allServiceNames = libraries.flatMap(lib => lib.serviceNames);
+        // 5. Build scope to service mapping
+        const scopeToServiceMap = new Map();
+        for (const lib of libraries) {
+            for (const service of lib.servicesWithScopes) {
+                // Map the service name to itself (service names are also valid scope names)
+                scopeToServiceMap.set(service.serviceName, service.serviceName);
+                // Map each owned scope to its owning service
+                for (const scope of service.ownedScopes) {
+                    scopeToServiceMap.set(scope, service.serviceName);
+                }
+            }
+        }
+        // 6. Sort libraries by package name
+        libraries.sort((a, b) => a.packageName.localeCompare(b.packageName));
+        return {
+            libraries,
+            allServiceNames,
+            scopeToServiceMap,
+            errors,
+        };
+    }
+    /**
+     * Clear package cache (useful when file tree changes)
+     */
+    clearCache() {
+        this.packageCache.clear();
+    }
+    /**
+     * Extract service names and owned scopes from a library's resources
+     */
+    extractServicesInfo(library) {
+        if (!library.resources) {
+            return { serviceNames: [], servicesWithScopes: [] };
+        }
+        const serviceNames = [];
+        const servicesWithScopes = [];
+        for (const attrs of Object.values(library.resources)) {
+            const serviceName = attrs['service.name'];
+            if (!serviceName)
+                continue;
+            serviceNames.push(serviceName);
+            // Extract owned-scopes (supports both legacy array and new record format)
+            const ownedScopes = attrs['owned-scopes'];
+            const scopeNames = (0, utils_1.getScopeNames)(ownedScopes);
+            servicesWithScopes.push({
+                serviceName,
+                ownedScopes: scopeNames,
+            });
+        }
+        return { serviceNames, servicesWithScopes };
+    }
+    /**
+     * Validate that a .scopes.canvas file exists when owned-scopes is defined
+     */
+    async validateScopesCanvasRequirement(packagePath, servicesWithScopes, libraryPath, errors) {
+        // Check if any service has owned-scopes
+        const hasOwnedScopes = servicesWithScopes.some(s => s.ownedScopes.length > 0);
+        if (!hasOwnedScopes) {
+            return; // No owned-scopes defined, no canvas required
+        }
+        // Collect all owned scopes
+        const allOwnedScopes = servicesWithScopes.flatMap(s => s.ownedScopes);
+        // Check if a .scopes.canvas file exists
+        // Look for any file matching *.scopes.canvas in .principal-views/
+        const pvDir = this.fsAdapter.join(packagePath, LibraryDiscovery.CANVAS_DIR);
+        const pvDirExists = await this.fsAdapter.exists(pvDir);
+        if (!pvDirExists) {
+            errors.push({
+                path: libraryPath,
+                message: `Scopes canvas required: library.yaml defines owned-scopes [${allOwnedScopes.join(', ')}] but no .principal-views/ directory exists. Create a .scopes.canvas file (e.g., architecture.scopes.canvas) documenting scope boundaries.`,
+                type: 'scopes-canvas-required',
+            });
+            return;
+        }
+        // Check for any .scopes.canvas file in the directory
+        const scopesCanvasExists = await this.checkScopesCanvasExists(pvDir);
+        if (!scopesCanvasExists) {
+            errors.push({
+                path: libraryPath,
+                message: `Scopes canvas required: library.yaml defines owned-scopes [${allOwnedScopes.join(', ')}] but no .scopes.canvas file found. Create a .scopes.canvas file (e.g., .principal-views/architecture.scopes.canvas) with nodes for each scope (set pv.otel.scope to the scope name).`,
+                type: 'scopes-canvas-required',
+            });
+        }
+    }
+    /**
+     * Check if any .scopes.canvas file exists in a directory
+     */
+    async checkScopesCanvasExists(dirPath) {
+        try {
+            const entries = await this.fsAdapter.readDir(dirPath);
+            for (const entry of entries) {
+                if (entry.endsWith('.scopes.canvas')) {
+                    return true;
+                }
+                // Also check subdirectories (for hierarchical structure)
+                const fullPath = this.fsAdapter.join(dirPath, entry);
+                const isDir = await this.fsAdapter.isDirectory(fullPath);
+                if (isDir) {
+                    const subEntries = await this.fsAdapter.readDir(fullPath);
+                    for (const subEntry of subEntries) {
+                        if (subEntry.endsWith('.scopes.canvas')) {
+                            return true;
+                        }
+                    }
+                }
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Discover packages with caching by fileTree SHA
+     */
+    async discoverPackagesWithCache(fileTree, fileReader) {
+        const cacheKey = fileTree.sha;
+        if (this.packageCache.has(cacheKey)) {
+            return this.packageCache.get(cacheKey);
+        }
+        const packages = await this.packageModule.discoverPackages(fileTree, fileReader);
+        this.packageCache.set(cacheKey, packages);
+        return packages;
+    }
+}
+LibraryDiscovery.CANVAS_DIR = '.principal-views';
+exports.LibraryDiscovery = LibraryDiscovery;
+//# sourceMappingURL=LibraryDiscovery.js.map

package/dist/discovery/LibraryDiscovery.js.map

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

package/dist/discovery/types.d.ts

@@ -0,0 +1,403 @@
+/**
+ * Type definitions for canvas and execution file discovery
+ */
+import type { ExtendedCanvas } from '../types/canvas';
+import type { ExecutionData } from '../execution/ExecutionValidator';
+import type { WorkflowTemplate } from '../workflow/types';
+/**
+ * Canvas file type discriminator
+ * - 'otel': OpenTelemetry canvas (.otel.canvas) for workflow/tracing visualization
+ * - 'scopes': Scopes canvas (.scopes.canvas) for documenting instrumentation scopes
+ * - 'resources': Resources canvas (.resources.canvas) for documenting OTel resources
+ * - 'spans': Spans canvas (.spans.canvas) for documenting span conventions
+ * - 'events': Events canvas (.events.canvas) for documenting event namespaces and adjacency
+ * - 'regular': Regular canvas (.canvas) for documentation/architecture diagrams
+ *
+ * Note: Dashboards (.dashboard.json) are NOT canvases - they live in .principal-views/dashboards/
+ * and are discovered separately as DiscoveredDashboard.
+ */
+export type CanvasType = 'otel' | 'scopes' | 'resources' | 'spans' | 'events' | 'regular';
+/**
+ * Test trace file type discriminator based on extension
+ * Only .otel.json files are supported
+ */
+export type TestTraceType = 'otel';
+/**
+ * Discovered canvas file with package metadata
+ */
+export interface DiscoveredCanvas {
+    /** Unique ID with package prefix (e.g., "core/my-flow" or "my-flow") */
+    id: string;
+    /** Display name (Title Case from basename) */
+    name: string;
+    /** Full relative path from repo root */
+    path: string;
+    /** Canvas basename (without .canvas/.otel.canvas extension) */
+    basename: string;
+    /** Canvas type */
+    type: CanvasType;
+    /** Package name if in a package (e.g., "core" from packages/subsystems-core) */
+    packageName?: string;
+    /** Package path if in a package (e.g., "packages/subsystems-core") */
+    packagePath?: string;
+    /** Whether this is from repo root vs package */
+    scope: 'root' | 'package';
+    /**
+     * Associated markdown documentation file path (relative to repo root)
+     * Only populated for otel.canvas files when canvas content is loaded
+     */
+    markdownPath?: string;
+}
+/**
+ * Discovered test trace file with package metadata
+ */
+export interface DiscoveredTestTrace {
+    /** Unique ID with package prefix (e.g., "core/api-tests" or "api-tests") */
+    id: string;
+    /** Display name (Title Case from basename) */
+    name: string;
+    /** Full relative path from repo root */
+    path: string;
+    /** Test trace basename (without .otel.json extension) */
+    basename: string;
+    /** Test trace file type */
+    type: TestTraceType;
+    /** Canvas basename this test trace is linked to */
+    canvasBasename: string;
+    /** Package name if in a package */
+    packageName?: string;
+    /** Package path if in a package */
+    packagePath?: string;
+    /** Whether this is from repo root vs package */
+    scope: 'root' | 'package';
+}
+/**
+ * Discovered dashboard file in .principal-views/dashboards/
+ */
+export interface DiscoveredDashboard {
+    /** Unique ID with package prefix (e.g., "core/auth-health" or "auth-health") */
+    id: string;
+    /** Display name (Title Case from basename) */
+    name: string;
+    /** Full relative path from repo root */
+    path: string;
+    /** Dashboard basename (without .dashboard.json extension) */
+    basename: string;
+    /** Package name if in a package */
+    packageName?: string;
+    /** Package path if in a package */
+    packagePath?: string;
+    /** Whether this is from repo root vs package */
+    scope: 'root' | 'package';
+}
+/**
+ * Discovered dashboard with parsed content
+ */
+export interface DiscoveredDashboardWithContent extends DiscoveredDashboard {
+    /** Parsed dashboard content (only when includeContent: true) */
+    content: import('../types/dashboard').DashboardDefinition;
+}
+/**
+ * A span convention (surface) referenced by a workflow
+ */
+export interface ReferencedSpan {
+    /** The span pattern (e.g., "canvas.load", "multi-canvas-panel.render") */
+    pattern: string;
+    /** Display label from the spans.canvas node, if found */
+    label?: string;
+    /** Instrumentation scope from the spans.canvas node otel.scope, if found */
+    scope?: string;
+}
+/**
+ * Discovered workflow file within a storyboard
+ */
+export interface DiscoveredWorkflow {
+    /** Workflow basename ID (e.g., "checkout" for checkout.workflow.json) */
+    id: string;
+    /** Display name (Title Case from basename) */
+    name: string;
+    /** Full relative path from repo root to workflow.json file */
+    path: string;
+    /** Workflow basename (without .workflow.json extension) */
+    basename: string;
+    /** Parent storyboard ID this workflow belongs to */
+    storyboardId: string;
+    /** Package name if in a package */
+    packageName?: string;
+    /** Package path if in a package */
+    packagePath?: string;
+    /** Whether this is from repo root vs package */
+    scope: 'root' | 'package';
+    /** Associated test trace files for this workflow */
+    testTraces: DiscoveredTestTrace[];
+    /**
+     * All span conventions (surfaces) referenced by this workflow.
+     * Includes rootSpan and any explicit span fields in event templates.
+     * Only populated when includeContent: true during discovery.
+     */
+    referencedSpans?: ReferencedSpan[];
+    /**
+     * The instrumentation scope this workflow belongs to.
+     * Derived from the rootSpan's scope in spans.canvas.
+     * Only populated when includeContent: true during discovery.
+     */
+    instrumentationScope?: string;
+    /**
+     * Display label for the workflow's instrumentation scope.
+     * Resolved from scopes.canvas using the scope name.
+     * Only populated when includeContent: true during discovery.
+     */
+    instrumentationScopeLabel?: string;
+}
+/**
+ * Discovered storyboard folder containing canvas, workflows, and executions
+ */
+export interface DiscoveredStoryboard {
+    /** Unique ID with package prefix (e.g., "core/checkout-flow" or "checkout-flow") */
+    id: string;
+    /** Display name (Title Case from basename) */
+    name: string;
+    /** Full relative path from repo root to storyboard folder */
+    path: string;
+    /** Storyboard basename (folder name) */
+    basename: string;
+    /** The main canvas file for this storyboard */
+    canvas: DiscoveredCanvas;
+    /** Workflows within this storyboard */
+    workflows: DiscoveredWorkflow[];
+    /** Package name if in a package */
+    packageName?: string;
+    /** Package path if in a package */
+    packagePath?: string;
+    /** Whether this is from repo root vs package */
+    scope: 'root' | 'package';
+}
+/**
+ * Result of canvas discovery operation
+ */
+export interface CanvasDiscoveryResult {
+    /** All discovered canvas files, sorted by package then name */
+    canvases: DiscoveredCanvas[];
+    /** All discovered test trace files, sorted by package then name */
+    testTraces: DiscoveredTestTrace[];
+    /** All discovered storyboards (hierarchical organization of canvas + workflows + test traces) */
+    storyboards: DiscoveredStoryboard[];
+    /** All discovered dashboard files from .principal-views/dashboards/ */
+    dashboards: DiscoveredDashboard[];
+    /** Any errors encountered during discovery */
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+    /** Deprecation warnings for legacy structures */
+    warnings: Array<{
+        path: string;
+        message: string;
+        type: 'deprecation';
+    }>;
+}
+/**
+ * Options for file discovery
+ */
+export interface DiscoveryOptions {
+    /**
+     * Optional function to read and parse canvas file contents
+     * Useful when you want parsed canvas objects, not just metadata
+     *
+     * @example
+     * // In CLI with filesystem access:
+     * fileReader: async (path) => fs.promises.readFile(path, 'utf-8')
+     *
+     * @example
+     * // In panels with cache:
+     * fileReader: async (path) => context.getSlice('fileCache').read(path)
+     */
+    fileReader?: (path: string) => Promise<string>;
+    /**
+     * Whether to include canvas content in results
+     * Requires fileReader to be provided
+     */
+    includeContent?: boolean;
+}
+/**
+ * Discovered canvas with parsed content
+ */
+export interface DiscoveredCanvasWithContent extends DiscoveredCanvas {
+    /** Parsed canvas content (only when includeContent: true) */
+    content: ExtendedCanvas;
+}
+/**
+ * Discovered test trace with parsed content
+ */
+export interface DiscoveredTestTraceWithContent extends DiscoveredTestTrace {
+    /** Parsed test trace artifact (only when includeContent: true) */
+    content: ExecutionData;
+}
+/**
+ * Discovered workflow with parsed content
+ */
+export interface DiscoveredWorkflowWithContent extends DiscoveredWorkflow {
+    /** Parsed workflow template (only when includeContent: true) */
+    content: WorkflowTemplate;
+    /** Test traces with parsed content */
+    testTraces: (DiscoveredTestTrace | DiscoveredTestTraceWithContent)[];
+}
+/**
+ * Discovered storyboard with parsed content
+ */
+export interface DiscoveredStoryboardWithContent extends DiscoveredStoryboard {
+    /** Canvas with parsed content */
+    canvas: DiscoveredCanvas | DiscoveredCanvasWithContent;
+    /** Workflows with parsed content */
+    workflows: (DiscoveredWorkflow | DiscoveredWorkflowWithContent)[];
+}
+/**
+ * Discovery result with content
+ */
+export interface CanvasDiscoveryResultWithContent {
+    canvases: (DiscoveredCanvas | DiscoveredCanvasWithContent)[];
+    testTraces: (DiscoveredTestTrace | DiscoveredTestTraceWithContent)[];
+    storyboards: (DiscoveredStoryboard | DiscoveredStoryboardWithContent)[];
+    dashboards: (DiscoveredDashboard | DiscoveredDashboardWithContent)[];
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+    warnings: Array<{
+        path: string;
+        message: string;
+        type: 'deprecation';
+    }>;
+}
+/**
+ * Classification of how a file relates to a canvas/workflow
+ */
+export type CanvasFileRole = 'instrumentation' | 'reference' | 'root-span';
+/**
+ * Origin of the file - internal to repo or external
+ */
+export type CanvasFileOrigin = 'internal' | 'external';
+/**
+ * Source level where the file was defined
+ */
+export type CanvasFileLevel = 'canvas-node' | 'workflow';
+/**
+ * A file referenced by a canvas, workflow, or scenario
+ */
+export interface CanvasFile {
+    /** File path (relative to repo root for internal, URL/package ref for external) */
+    path: string;
+    /** How this file relates to the canvas */
+    role: CanvasFileRole;
+    /** Whether the file is in this repo or external */
+    origin: CanvasFileOrigin;
+    /** Where this file reference was defined */
+    level: CanvasFileLevel;
+    /** IDs of nodes that reference this file (for canvas-node level) */
+    nodeIds: string[];
+    /** Node types that reference this file */
+    nodeTypes: string[];
+    /** Workflow IDs that reference this file (for workflow level) */
+    workflowIds: string[];
+    /** Event names associated with this file's nodes */
+    eventNames: string[];
+}
+/**
+ * Canvas-level statistics
+ */
+export interface CanvasFileStats {
+    totalFiles: number;
+    internalFiles: number;
+    externalFiles: number;
+    instrumentationFiles: number;
+    referenceFiles: number;
+    nodesWithFiles: number;
+    nodesWithoutFiles: number;
+    uniqueEventNames: number;
+}
+/**
+ * Storyboard-level statistics
+ */
+export interface StoryboardFileStats extends CanvasFileStats {
+    workflowCount: number;
+    scenarioCount: number;
+    rootSpanFiles: number;
+}
+/**
+ * File manifest for a single canvas (without workflows)
+ */
+export interface CanvasFileManifest {
+    /** Canvas ID */
+    canvasId: string;
+    /** Canvas path */
+    canvasPath: string;
+    /** Canvas type */
+    canvasType: CanvasType;
+    /** All files from canvas nodes, deduplicated */
+    files: CanvasFile[];
+    /** Quick lookup by role */
+    byRole: Record<CanvasFileRole, CanvasFile[]>;
+    /** Quick lookup by origin */
+    byOrigin: Record<CanvasFileOrigin, CanvasFile[]>;
+    /** Reverse mapping: file path -> node IDs */
+    fileToNodes: Map<string, string[]>;
+    /** Reverse mapping: node ID -> file paths */
+    nodeToFiles: Map<string, string[]>;
+    /** Reverse mapping: event name -> file paths */
+    eventToFiles: Map<string, string[]>;
+    /** Summary statistics */
+    stats: CanvasFileStats;
+}
+/**
+ * File manifest for a workflow (includes canvas + workflow-level files)
+ */
+export interface WorkflowFileManifest extends CanvasFileManifest {
+    /** Workflow ID */
+    workflowId: string;
+    /** Workflow path */
+    workflowPath: string;
+    /** Root span name */
+    rootSpan?: string;
+    /** Files from workflow.files property */
+    workflowFiles: CanvasFile[];
+    /** Merged files (canvas + workflow) */
+    allFiles: CanvasFile[];
+    /** Files filtered by scenario (scenario ID -> files) */
+    byScenario: Map<string, CanvasFile[]>;
+}
+/**
+ * File manifest for an entire storyboard
+ */
+export interface StoryboardFileManifest {
+    /** Storyboard ID */
+    storyboardId: string;
+    /** Storyboard path */
+    storyboardPath: string;
+    /** Main canvas manifest */
+    canvas: CanvasFileManifest;
+    /** Workflow manifests */
+    workflows: WorkflowFileManifest[];
+    /** All files across canvas and all workflows */
+    allFiles: CanvasFile[];
+    /** Summary statistics */
+    stats: StoryboardFileStats;
+}
+/**
+ * Discovered canvas with content AND file manifest
+ */
+export interface DiscoveredCanvasWithManifest extends DiscoveredCanvasWithContent {
+    manifest: CanvasFileManifest;
+}
+/**
+ * Discovered workflow with content AND file manifest
+ */
+export interface DiscoveredWorkflowWithManifest extends DiscoveredWorkflowWithContent {
+    manifest: WorkflowFileManifest;
+}
+/**
+ * Discovered storyboard with content AND file manifest
+ */
+export interface DiscoveredStoryboardWithManifest extends DiscoveredStoryboardWithContent {
+    manifest: StoryboardFileManifest;
+}
+//# sourceMappingURL=types.d.ts.map