@stream44.studio/encapsulate 0.2.0-rc.1

package/src/spine-contracts/CapsuleSpineContract.v0/Static.v0.ts

@@ -0,0 +1,290 @@
+import { CapsulePropertyTypes, join } from "../../encapsulate"
+
+export class ContractCapsuleInstanceFactory {
+
+    protected spineContractUri: string
+    protected capsule: any
+    protected self: any
+    protected encapsulatedApi: Record<string, any>
+    protected resolve?: (uri: string, parentFilepath: string) => Promise<string>
+    protected importCapsule?: (filepath: string) => Promise<any>
+    protected spineFilesystemRoot?: string
+    protected freezeCapsule?: (capsule: any) => Promise<any>
+
+    constructor({ spineContractUri, capsule, self, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule }: { spineContractUri: string, capsule: any, self: any, encapsulatedApi: Record<string, any>, resolve?: (uri: string, parentFilepath: string) => Promise<string>, importCapsule?: (filepath: string) => Promise<any>, spineFilesystemRoot?: string, freezeCapsule?: (capsule: any) => Promise<any> }) {
+        this.spineContractUri = spineContractUri
+        this.capsule = capsule
+        this.self = self
+        this.encapsulatedApi = encapsulatedApi
+        this.resolve = resolve
+        this.importCapsule = importCapsule
+        this.spineFilesystemRoot = spineFilesystemRoot
+        this.freezeCapsule = freezeCapsule
+    }
+
+    async mapProperty({ overrides, options, property }: { overrides: any, options: any, property: any }) {
+        if (property.definition.type === CapsulePropertyTypes.Mapping) {
+            await this.mapMappingProperty({ overrides, options, property })
+        } else if (
+            property.definition.type === CapsulePropertyTypes.String ||
+            property.definition.type === CapsulePropertyTypes.Literal
+        ) {
+            this.mapLiteralProperty({ property })
+        } else if (property.definition.type === CapsulePropertyTypes.Function) {
+            this.mapFunctionProperty({ property })
+        } else if (property.definition.type === CapsulePropertyTypes.GetterFunction) {
+            this.mapGetterFunctionProperty({ property })
+        }
+    }
+
+    protected getApiTarget({ property }: { property: any }) {
+        // Properties under '#' go directly on the API
+        // Properties under '#<uri>' go under api['#<uri>']
+        if (!property.propertyContractUri || property.propertyContractUri === '#') {
+            return this.encapsulatedApi
+        } else {
+            // Namespace under the property contract key
+            if (!this.encapsulatedApi[property.propertyContractUri]) {
+                this.encapsulatedApi[property.propertyContractUri] = {}
+            }
+            return this.encapsulatedApi[property.propertyContractUri]
+        }
+    }
+
+    protected async resolveMappedCapsule({ property }: { property: any }) {
+        let mappedCapsule
+
+        if (typeof property.definition.value === 'string') {
+            if (!this.resolve) throw new Error(`'resolve' not set!`)
+            if (!this.spineFilesystemRoot) throw new Error(`'spineFilesystemRoot' not set!`)
+            if (!this.importCapsule) throw new Error(`'importCapsule' not set!`)
+
+            const parentPath = join(this.spineFilesystemRoot, this.capsule.cst.source.moduleFilepath)
+            const filepath = await this.resolve(property.definition.value, parentPath)
+            mappedCapsule = await this.importCapsule(filepath)
+        } else if (
+            typeof property.definition.value === 'object' &&
+            typeof property.definition.value.capsuleSourceLineRef === 'string'
+        ) {
+            mappedCapsule = property.definition.value
+        } else {
+            throw new Error(`Unknown mapping value for property '${property.name}'!`)
+        }
+
+        return mappedCapsule
+    }
+
+    protected async extractConstants({ mappedCapsule }: { mappedCapsule: any }) {
+        const constants: Record<string, any> = {}
+
+        const spineContractDef = mappedCapsule.definition[this.spineContractUri]
+
+        if (!spineContractDef) {
+            throw new Error(`Spine contract definition not found for URI: ${this.spineContractUri}. Available keys: ${Object.keys(mappedCapsule.definition).join(', ')}`)
+        }
+
+        // Iterate through all keys in the spine contract definition
+        for (const [key, value] of Object.entries(spineContractDef)) {
+            if (key.startsWith('#')) {
+                // This is a property contract - iterate through its properties
+                for (const [prop, propDef] of Object.entries(value as Record<string, any>)) {
+                    const { type, value: propValue } = propDef as any
+
+                    if (typeof propValue === 'undefined') continue
+
+                    if (
+                        type === CapsulePropertyTypes.String ||
+                        type === CapsulePropertyTypes.Literal
+                    ) {
+                        constants[prop] = propValue
+                    }
+                }
+            } else {
+                // Regular property (backwards compatibility)
+                const { type, value: propValue } = value as any
+
+                if (typeof propValue === 'undefined') continue
+
+                if (
+                    type === CapsulePropertyTypes.String ||
+                    type === CapsulePropertyTypes.Literal
+                ) {
+                    constants[key] = propValue
+                }
+            }
+        }
+
+        return constants
+    }
+
+    protected async mapMappingProperty({ overrides, options, property }: { overrides: any, options: any, property: any }) {
+        const mappedCapsule = await this.resolveMappedCapsule({ property })
+        const constants = await this.extractConstants({ mappedCapsule })
+
+        const mappingOptions = await property.definition.options?.({
+            constants
+        })
+
+        // Transform overrides if this mapping has a propertyContractDelegate
+        let mappedOverrides = overrides
+        if (property.definition.propertyContractDelegate) {
+            // Extract overrides for the delegate property contract and map them to '#'
+            // Try both capsuleSourceLineRef and capsuleName
+            const delegateOverrides =
+                overrides?.[this.capsule.encapsulateOptions.capsuleSourceLineRef]?.[property.definition.propertyContractDelegate] ||
+                (this.capsule.encapsulateOptions.capsuleName && overrides?.[this.capsule.encapsulateOptions.capsuleName]?.[property.definition.propertyContractDelegate])
+
+            if (delegateOverrides) {
+                mappedOverrides = {
+                    ...overrides,
+                    [mappedCapsule.capsuleSourceLineRef]: {
+                        '#': delegateOverrides
+                    }
+                }
+                if (mappedCapsule.encapsulateOptions.capsuleName) {
+                    mappedOverrides[mappedCapsule.encapsulateOptions.capsuleName] = {
+                        '#': delegateOverrides
+                    }
+                }
+            }
+        }
+
+        const apiTarget = this.getApiTarget({ property })
+        const mappedInstance = await mappedCapsule.makeInstance({
+            overrides: mappedOverrides,
+            options: mappingOptions
+        })
+
+        apiTarget[property.name] = mappedInstance
+        // Use proxy to unwrap .api for this.self so internal references work
+        this.self[property.name] = mappedInstance.api ? new Proxy(mappedInstance.api, {
+            get: (target, prop) => {
+                const value = target[prop]
+                // Recursively unwrap nested .api objects
+                if (value && typeof value === 'object' && value.api) {
+                    return value.api
+                }
+                return value
+            }
+        }) : mappedInstance
+
+        // If this mapping has a propertyContractDelegate, also mount the mapped capsule's API
+        // to the property contract namespace for direct access
+        if (property.definition.propertyContractDelegate) {
+            // Create the property contract namespace if it doesn't exist
+            if (!this.encapsulatedApi[property.definition.propertyContractDelegate]) {
+                this.encapsulatedApi[property.definition.propertyContractDelegate] = {}
+            }
+
+            // Mount all properties from the mapped capsule's API to the property contract namespace
+            const delegateTarget = this.encapsulatedApi[property.definition.propertyContractDelegate]
+            for (const [key, value] of Object.entries(mappedInstance.api)) {
+                delegateTarget[key] = value
+            }
+        }
+    }
+
+    protected mapLiteralProperty({ property }: { property: any }) {
+        const apiTarget = this.getApiTarget({ property })
+        const value = typeof this.self[property.name] !== 'undefined'
+            ? this.self[property.name]
+            : property.definition.value
+
+        // Assign to both apiTarget and self so getter functions can access via this
+        apiTarget[property.name] = value
+        this.self[property.name] = value
+    }
+
+    protected mapFunctionProperty({ property }: { property: any }) {
+        const apiTarget = this.getApiTarget({ property })
+
+        // Create a proxy for this.self that intercepts property access
+        // Prefer this.self (which has unwrapped APIs) over encapsulatedApi
+        const selfProxy = new Proxy(this.self, {
+            get: (target: any, prop: string | symbol) => {
+                if (typeof prop === 'symbol') return target[prop]
+
+                // First check if the property exists in target (this.self)
+                if (prop in target) {
+                    return target[prop]
+                }
+
+                // Fall back to encapsulatedApi
+                if (prop in this.encapsulatedApi) {
+                    return this.encapsulatedApi[prop]
+                }
+
+                return undefined
+            }
+        })
+
+        apiTarget[property.name] = property.definition.value.bind(selfProxy)
+    }
+
+    protected mapGetterFunctionProperty({ property }: { property: any }) {
+        const apiTarget = this.getApiTarget({ property })
+        const getterFn = property.definition.value
+
+        // Create a proxy for this.self that intercepts property access
+        // Prefer this.self (which has unwrapped APIs) over encapsulatedApi
+        const selfProxy = new Proxy(this.self, {
+            get: (target: any, prop: string | symbol) => {
+                if (typeof prop === 'symbol') return target[prop]
+
+                // First check if the property exists in target (this.self)
+                if (prop in target) {
+                    return target[prop]
+                }
+
+                // Fall back to encapsulatedApi
+                if (prop in this.encapsulatedApi) {
+                    return this.encapsulatedApi[prop]
+                }
+
+                return undefined
+            }
+        })
+
+        // Define a lazy getter that calls the function only when accessed with proper this context
+        Object.defineProperty(apiTarget, property.name, {
+            get: () => {
+                return getterFn.call(selfProxy)
+            },
+            enumerable: true,
+            configurable: true
+        })
+    }
+
+    async freeze(options: any): Promise<any> {
+        return this.freezeCapsule?.(options) || {}
+    }
+
+}
+
+
+
+
+export function CapsuleSpineContract({ freezeCapsule, resolve, importCapsule, spineFilesystemRoot }: { freezeCapsule?: (capsule: any) => Promise<any>, resolve?: (uri: string, parentFilepath: string) => Promise<string>, importCapsule?: (filepath: string) => Promise<any>, spineFilesystemRoot?: string } = {}) {
+
+    return {
+        '#': CapsuleSpineContract['#'],
+        makeContractCapsuleInstance: ({ spineContractUri, capsule, self, encapsulatedApi }: { spineContractUri: string, capsule: any, self: any, encapsulatedApi: Record<string, any> }) => {
+            return new ContractCapsuleInstanceFactory({
+                spineContractUri,
+                capsule,
+                self,
+                encapsulatedApi,
+                resolve,
+                importCapsule,
+                spineFilesystemRoot,
+                freezeCapsule
+            })
+        },
+        hydrate: ({ capsuleSnapshot }: { capsuleSnapshot: any }): any => {
+
+            return capsuleSnapshot
+        }
+    }
+}
+
+CapsuleSpineContract['#'] = '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0'

package/src/spine-factories/CapsuleSpineFactory.v0.ts

@@ -0,0 +1,299 @@
+import { join, dirname } from 'path'
+import { writeFile, mkdir, readFile, stat } from 'fs/promises'
+import { Spine, SpineRuntime, CapsulePropertyTypes, makeImportStack, merge } from "../encapsulate"
+import { StaticAnalyzer } from "../../src/static-analyzer.v0"
+import { CapsuleModuleProjector } from "../../src/capsule-projectors/CapsuleModuleProjector.v0"
+
+
+export { merge }
+
+// TODO: Make portable so we can run on other runtimes
+const resolve = Bun.resolve
+
+
+export async function CapsuleSpineFactory({
+    spineFilesystemRoot,
+    capsuleModuleProjectionRoot,
+    capsuleModuleProjectionPackage,
+    staticAnalysisEnabled = true,
+    onMembraneEvent,
+    enableCallerStackInference = false,
+    spineContracts,
+    timing: timingParam
+}: {
+    spineFilesystemRoot: string,
+    capsuleModuleProjectionRoot?: string,
+    capsuleModuleProjectionPackage?: string,
+    staticAnalysisEnabled?: boolean,
+    onMembraneEvent?: (event: any) => void,
+    enableCallerStackInference?: boolean,
+    spineContracts: Record<string, any>,
+    timing?: { record: (step: string) => void, recordMajor: (step: string) => void, chalk?: any }
+}) {
+
+    if (capsuleModuleProjectionRoot) capsuleModuleProjectionRoot = capsuleModuleProjectionRoot.replace(/^file:\/\//, '')
+    if (spineFilesystemRoot) spineFilesystemRoot = spineFilesystemRoot.replace(/^file:\/\//, '')
+
+    const timing = timingParam
+
+    timing?.recordMajor('CAPSULE SPINE FACTORY: INITIALIZATION')
+
+    const SingletonRegistry = () => {
+        const registry = new Map<string, Promise<any>>()
+
+        return {
+            async ensure(id: string, createHandler: () => Promise<any>) {
+                if (!registry.has(id)) {
+                    registry.set(id, createHandler())
+                }
+                return registry.get(id)!
+            }
+        }
+    }
+
+    const registry = SingletonRegistry()
+
+    const spineContractInstances: {
+        encapsulation: Record<string, any>,
+        runtime: Record<string, any>
+    } = {
+        encapsulation: {},
+        runtime: {}
+    }
+
+    const sourceSpine: { encapsulate?: any } = {}
+    const commonSpineContractOpts = {
+        spineFilesystemRoot,
+        resolve: async (uri: string, parentFilepath: string) => {
+            // For relative paths, join with parent directory first
+            if (/^\.\.?\//.test(uri)) {
+                return await resolve(join(parentFilepath, '..', uri), spineFilesystemRoot)
+            }
+            // For absolute/package paths, use Bun.resolve directly
+            return await resolve(uri, parentFilepath)
+        },
+        importCapsule: async (filepath: string) => {
+            const shortPath = filepath.replace(/^.*\/genesis\//, '')
+            timing?.record(`importCapsule: Called for ${shortPath}`)
+            const result = await registry.ensure(filepath, async () => {
+                timing?.recordMajor(`importCapsule: Starting import for ${shortPath}`)
+                const importStart = Date.now()
+                const exports = await import(filepath)
+                const importDuration = Date.now() - importStart
+                timing?.recordMajor(`importCapsule: import() took ${importDuration}ms for ${shortPath}`)
+
+                if (importDuration > 10) {
+                    if (timing) {
+                        console.log(timing.chalk.red(`\n⚠️  WARNING: Slow module load detected!`))
+                        console.log(timing.chalk.red(`   Module: ${filepath}`))
+                        console.log(timing.chalk.red(`   Load time: ${importDuration}ms`))
+                        console.log(timing.chalk.red(`   Consider using dynamic imports to load heavy dependencies only when needed.\n`))
+                    }
+                }
+
+                if (typeof exports.capsule !== 'function') throw new Error(`Module at '${filepath}' does not export 'capsule'!`)
+
+                const capsuleStart = Date.now()
+                const capsule = await exports.capsule({
+                    encapsulate: sourceSpine.encapsulate,
+                    CapsulePropertyTypes,
+                    makeImportStack
+                })
+                const capsuleDuration = Date.now() - capsuleStart
+                timing?.recordMajor(`importCapsule: exports.capsule() took ${capsuleDuration}ms for ${shortPath}`)
+
+                timing?.record(`importCapsule: Returning result for ${shortPath}`)
+
+                return capsule
+            })
+            return result
+        },
+        encapsulateOpts: {
+            CapsulePropertyTypes
+        }
+    }
+
+    timing?.recordMajor('SPINE CONTRACTS: INITIALIZATION')
+
+    for (const spineContractUri in spineContracts) {
+        spineContractInstances.encapsulation[spineContractUri] = spineContracts[spineContractUri]({
+            ...commonSpineContractOpts,
+            freezeCapsule: async ({ spineContractUri, capsule }: { spineContractUri: string, capsule: any }): Promise<any> => {
+
+                if (!projector) {
+                    throw new Error('capsuleModuleProjectionRoot must be provided to enable freezing')
+                }
+
+                let snapshotValues = {}
+
+                const projected = await projector.projectCapsule({
+                    capsule,
+                    capsules,
+                    snapshotValues,
+                    spineContractUri
+                })
+
+                return snapshotValues
+            }
+        })
+        spineContractInstances.runtime[spineContractUri] = spineContracts[spineContractUri]({
+            ...commonSpineContractOpts,
+            enableCallerStackInference,
+            onMembraneEvent,
+        })
+    }
+
+    timing?.recordMajor('CAPSULE MODULE PROJECTOR: INITIALIZATION')
+
+    const projector = capsuleModuleProjectionRoot ? CapsuleModuleProjector({
+        spineStore: {
+            writeFile: async (filepath: string, content: string) => {
+                filepath = join(spineFilesystemRoot, filepath)
+                await mkdir(dirname(filepath), { recursive: true })
+                await writeFile(filepath, content, 'utf-8')
+            },
+            getStats: async (filepath: string) => {
+                filepath = join(spineFilesystemRoot, filepath)
+                try {
+                    const stats = await stat(filepath)
+                    return { mtime: stats.mtime }
+                } catch (error) {
+                    return null
+                }
+            },
+        },
+        projectionStore: {
+            writeFile: async (filepath: string, content: string) => {
+                filepath = join(capsuleModuleProjectionRoot, filepath)
+                await mkdir(dirname(filepath), { recursive: true })
+                await writeFile(filepath, content, 'utf-8')
+            },
+            getStats: async (filepath: string) => {
+                filepath = join(capsuleModuleProjectionRoot, filepath)
+                try {
+                    const stats = await stat(filepath)
+                    return { mtime: stats.mtime }
+                } catch (error) {
+                    return null
+                }
+            },
+        },
+        projectionCacheStore: {
+            writeFile: async (filepath: string, content: string) => {
+                filepath = join(spineFilesystemRoot, '.~o/encapsulate.dev/projection-cache', filepath)
+                await mkdir(dirname(filepath), { recursive: true })
+                await writeFile(filepath, content, 'utf-8')
+            },
+            readFile: async (filepath: string) => {
+                filepath = join(spineFilesystemRoot, '.~o/encapsulate.dev/projection-cache', filepath)
+                return readFile(filepath, 'utf-8')
+            },
+            getStats: async (filepath: string) => {
+                filepath = join(spineFilesystemRoot, '.~o/encapsulate.dev/projection-cache', filepath)
+                try {
+                    const stats = await stat(filepath)
+                    return { mtime: stats.mtime }
+                } catch (error) {
+                    return null
+                }
+            },
+        },
+        spineFilesystemRoot,
+        capsuleModuleProjectionPackage,
+        timing
+    }) : undefined
+
+    timing?.recordMajor('SPINE: INITIALIZATION')
+
+    let { encapsulate, freeze, capsules } = await Spine({
+        spineFilesystemRoot,
+        timing,
+        staticAnalyzer: staticAnalysisEnabled ? StaticAnalyzer({
+            timing,
+            cacheStore: {
+                writeFile: async (filepath: string, content: string) => {
+                    filepath = join(spineFilesystemRoot, '.~o/encapsulate.dev/static-analysis', filepath)
+                    await mkdir(dirname(filepath), { recursive: true })
+                    await writeFile(filepath, content, 'utf-8')
+                },
+                readFile: async (filepath: string) => {
+                    filepath = join(spineFilesystemRoot, '.~o/encapsulate.dev/static-analysis', filepath)
+                    return readFile(filepath, 'utf-8')
+                },
+                getStats: async (filepath: string) => {
+                    filepath = join(spineFilesystemRoot, '.~o/encapsulate.dev/static-analysis', filepath)
+                    try {
+                        const stats = await stat(filepath)
+                        return { mtime: stats.mtime }
+                    } catch (error) {
+                        // File doesn't exist
+                        return null
+                    }
+                },
+            },
+            spineStore: {
+                getStats: async (filepath: string) => {
+                    filepath = join(spineFilesystemRoot, filepath)
+                    try {
+                        const stats = await stat(filepath)
+                        return { mtime: stats.mtime }
+                    } catch (error) {
+                        // File doesn't exist
+                        return null
+                    }
+                },
+            },
+        }) : undefined,
+        spineContracts: spineContractInstances.encapsulation
+    })
+    sourceSpine.encapsulate = encapsulate
+
+    timing?.recordMajor('SPINE RUNTIME: INITIALIZATION')
+
+    let { run } = await SpineRuntime({
+        spineFilesystemRoot,
+        spineContracts: spineContractInstances.runtime,
+        capsules
+    })
+
+    timing?.recordMajor('CAPSULE SPINE FACTORY: READY')
+
+    const loadCapsule = async ({ capsuleSnapshot }: { capsuleSourceLineRef: string, capsuleSnapshot: any }) => {
+
+        if (!capsuleModuleProjectionRoot) {
+            throw new Error('capsuleModuleProjectionRoot must be provided to enable dynamic loading of capsules')
+        }
+
+        let filepath = capsuleSnapshot.spineContracts?.['#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0']?.['#@stream44.studio/encapsulate/structs/Capsule.v0']?.projectedCapsuleFilepath
+
+        if (!filepath) throw new Error(`Cannot load capsule. No 'filepath' found at 'spineContracts["#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0"]["#@stream44.studio/encapsulate/structs/Capsule.v0"].projectedCapsuleFilepath'!`)
+
+        const { capsule } = await import(join(capsuleModuleProjectionRoot, filepath))
+
+        return capsule
+    }
+
+    return {
+        commonSpineContractOpts,
+        CapsulePropertyTypes,
+        makeImportStack,
+        encapsulate,
+        run,
+        freeze,
+        loadCapsule,
+        hoistSnapshot: async ({ snapshot }: { snapshot: any }) => {
+
+            timing?.recordMajor('HOIST SNAPSHOT: START')
+
+            const result = await SpineRuntime({
+                snapshot,
+                spineContracts: spineContractInstances.runtime,
+                loadCapsule
+            })
+
+            timing?.recordMajor('HOIST SNAPSHOT: COMPLETE')
+
+            return result
+        }
+    }
+}

package/src/spine-factories/TimingObserver.ts

@@ -0,0 +1,26 @@
+
+import chalk from 'chalk';
+
+export function TimingObserver({ startTime }: { startTime: number }) {
+    let lastTime = startTime
+
+    return {
+        chalk,
+        record: (step: string) => {
+            const now = Date.now()
+            const diff = now - lastTime
+            lastTime = now
+
+            const line = `[+${diff}ms]   ${step}`
+            console.log(diff > 10 ? chalk.red(line) : line)
+        },
+        recordMajor: (step: string) => {
+            const now = Date.now()
+            const diff = now - lastTime
+            lastTime = now
+
+            const line = `[+${diff}ms] ${step}`
+            console.log(diff > 10 ? chalk.red(line) : chalk.cyan(line))
+        }
+    }
+}