@stream44.studio/t44 0.4.0-rc.24

package/lib/schema-console-renderer.ts

@@ -0,0 +1,181 @@
+import chalk from 'chalk'
+
+export interface RenderOptions {
+    indent?: number
+    maxDepth?: number
+    currentDepth?: number
+    showTypes?: boolean
+}
+
+/**
+ * Generic schema-based console renderer that formats data based on JSON Schema properties
+ */
+export class SchemaConsoleRenderer {
+    /**
+     * Render entity data based on its schema
+     */
+    static renderEntity(
+        data: any,
+        schema: any,
+        options: RenderOptions = {}
+    ): string {
+        const {
+            indent = 0,
+            maxDepth = 5,
+            currentDepth = 0,
+            showTypes = false
+        } = options
+
+        // maxDepth of -1 means unlimited depth
+        if (maxDepth !== -1 && currentDepth >= maxDepth) {
+            return chalk.gray('  '.repeat(indent) + '[max depth reached]')
+        }
+
+        const lines: string[] = []
+        const properties = schema?.properties || {}
+        const required = new Set(schema?.required || [])
+
+        // If data is primitive, render directly
+        if (typeof data !== 'object' || data === null) {
+            return chalk.yellow(String(data))
+        }
+
+        // Render each property based on schema
+        for (const [key, value] of Object.entries(data)) {
+            const propSchema = properties[key]
+            const isRequired = required.has(key)
+            const prefix = '  '.repeat(indent)
+
+            // Format key with required indicator
+            const keyDisplay = isRequired
+                ? chalk.bold.cyan(key)
+                : chalk.cyan(key)
+
+            // Add type annotation if requested
+            const typeAnnotation = showTypes && propSchema?.type
+                ? chalk.gray(` (${propSchema.type})`)
+                : ''
+
+            // Render value based on type
+            if (value === null || value === undefined) {
+                lines.push(`${prefix}${keyDisplay}${typeAnnotation}: ${chalk.gray('null')}`)
+            } else if (Array.isArray(value)) {
+                lines.push(`${prefix}${keyDisplay}${typeAnnotation}: ${chalk.gray(`[${value.length} items]`)}`)
+
+                // Render array items if not too deep
+                if ((maxDepth === -1 || currentDepth < maxDepth - 1) && value.length > 0) {
+                    const itemSchema = propSchema?.items
+                    value.forEach((item, idx) => {
+                        if (typeof item === 'object' && item !== null) {
+                            lines.push(`${prefix}  ${chalk.gray(`${idx}`)}:`)
+                            lines.push(this.renderEntity(item, itemSchema, {
+                                indent: indent + 3,
+                                maxDepth,
+                                currentDepth: currentDepth + 1,
+                                showTypes
+                            }))
+                        } else {
+                            lines.push(`${prefix}  ${chalk.gray(`${idx}`)}: ${this.formatValue(item, propSchema)}`)
+                        }
+                    })
+                }
+            } else if (typeof value === 'object') {
+                const description = propSchema?.description
+                const descSuffix = description ? chalk.gray(` // ${description}`) : ''
+                lines.push(`${prefix}${keyDisplay}${typeAnnotation}:${descSuffix}`)
+
+                // Recursively render nested object
+                lines.push(this.renderEntity(value, propSchema, {
+                    indent: indent + 1,
+                    maxDepth,
+                    currentDepth: currentDepth + 1,
+                    showTypes
+                }))
+            } else {
+                const description = propSchema?.description
+                const descSuffix = description ? chalk.gray(` // ${description}`) : ''
+                lines.push(`${prefix}${keyDisplay}${typeAnnotation}: ${this.formatValue(value, propSchema)}${descSuffix}`)
+            }
+        }
+
+        return lines.join('\n')
+    }
+
+    /**
+     * Format a primitive value based on its schema
+     */
+    private static formatValue(value: any, schema?: any): string {
+        if (value === null || value === undefined) {
+            return chalk.gray('null')
+        }
+
+        const type = schema?.type || typeof value
+        const format = schema?.format
+
+        switch (type) {
+            case 'string':
+                if (format === 'date-time') {
+                    return chalk.green(value)
+                } else if (format === 'uri' || format === 'url') {
+                    return chalk.blue.underline(value)
+                } else if (schema?.enum) {
+                    return chalk.magenta(value)
+                }
+                return chalk.yellow(JSON.stringify(value))
+
+            case 'number':
+            case 'integer':
+                return chalk.cyan(String(value))
+
+            case 'boolean':
+                return value ? chalk.green('true') : chalk.red('false')
+
+            default:
+                return chalk.yellow(JSON.stringify(value))
+        }
+    }
+
+    /**
+     * Render a summary line for an entity
+     */
+    static renderSummary(
+        entityName: string,
+        data: any,
+        schema: any
+    ): string {
+        const properties = schema?.properties || {}
+        const parts: string[] = []
+
+        // Try to find key identifying properties
+        const identifiers = ['name', 'identifier', 'id', 'title']
+        for (const key of identifiers) {
+            if (data[key] && properties[key]) {
+                parts.push(chalk.yellow(data[key]))
+                break
+            }
+        }
+
+        // Add status if present
+        if (data.status && properties.status) {
+            const statusColor = data.status === 'READY' ? chalk.green :
+                data.status === 'ERROR' ? chalk.red :
+                    chalk.yellow
+            parts.push(statusColor(`[${data.status}]`))
+        }
+
+        return parts.length > 0 ? parts.join(' ') : ''
+    }
+
+    /**
+     * Render validation errors
+     */
+    static renderErrors(errors: any[]): string {
+        if (errors.length === 0) return ''
+
+        const lines: string[] = [chalk.red.bold('Validation Errors:')]
+        for (const err of errors) {
+            lines.push(chalk.red(`  ${err.path}: ${err.message}`))
+        }
+        return lines.join('\n')
+    }
+}

package/lib/schema-resolver.ts

@@ -0,0 +1,349 @@
+
+import { join, relative } from 'path'
+import { readdir, readFile } from 'fs/promises'
+import { RefResolver } from 'json-schema-ref-resolver'
+import Ajv from 'ajv'
+import addFormats from 'ajv-formats'
+
+export interface ResolvedEntity {
+    schemaId: string
+    name: string
+    data: any
+    filePath: string
+    relPath: string
+    line?: number
+    valid: boolean
+    errors: any[]
+}
+
+export interface ResolverContext {
+    workspaceRootDir: string
+    workspaceName: string
+    schemasDir: string
+    factsDir: string
+    metaCacheDir: string
+    homeRegistryConnectionsDir: string
+}
+
+export interface WorkspaceResolverResult {
+    schemas: Map<string, any>
+    entities: Map<string, ResolvedEntity[]>
+    configEntities: Map<string, any>
+    factEntities: Map<string, ResolvedEntity[]>
+    connectionEntities: Map<string, ResolvedEntity[]>
+    refResolver: RefResolver
+}
+
+function createAjvInstance(): Ajv {
+    const ajv = new Ajv({
+        allErrors: true,
+        strict: false,
+        validateFormats: true,
+        logger: false
+    })
+    addFormats(ajv)
+    return ajv
+}
+
+export function Resolver(context: ResolverContext) {
+    const refResolver = new RefResolver()
+    const ajv = createAjvInstance()
+    const schemas = new Map<string, any>()
+
+    return {
+        async loadSchemas(): Promise<Map<string, any>> {
+            await loadSchemasInternal(context.schemasDir, refResolver, schemas)
+            return schemas
+        },
+
+        async loadConfigEntities(): Promise<{ configEntities: Map<string, any>; entities: Map<string, ResolvedEntity[]> }> {
+            const configEntities = new Map<string, any>()
+            const entities = new Map<string, ResolvedEntity[]>()
+            await loadConfigFileEntities(context.metaCacheDir, ajv, schemas, configEntities, entities)
+            return { configEntities, entities }
+        },
+
+        async loadFactEntities(): Promise<{ factEntities: Map<string, ResolvedEntity[]>; entities: Map<string, ResolvedEntity[]> }> {
+            const factEntities = new Map<string, ResolvedEntity[]>()
+            const entities = new Map<string, ResolvedEntity[]>()
+            await loadEntityFiles({
+                entityDir: context.factsDir,
+                workspaceRootDir: context.workspaceRootDir,
+                ajv,
+                schemas,
+                entityMap: factEntities,
+                allEntities: entities
+            })
+            return { factEntities, entities }
+        },
+
+        async loadConnectionEntities(): Promise<{ connectionEntities: Map<string, ResolvedEntity[]>; entities: Map<string, ResolvedEntity[]> }> {
+            const connectionEntities = new Map<string, ResolvedEntity[]>()
+            const entities = new Map<string, ResolvedEntity[]>()
+            await loadEntityFiles({
+                entityDir: context.homeRegistryConnectionsDir,
+                workspaceRootDir: context.workspaceRootDir,
+                ajv,
+                schemas,
+                entityMap: connectionEntities,
+                allEntities: entities,
+                isFlat: true
+            })
+            return { connectionEntities, entities }
+        },
+
+        getRefResolver(): RefResolver {
+            return refResolver
+        },
+
+        getSchemas(): Map<string, any> {
+            return schemas
+        }
+    }
+}
+
+async function loadSchemasInternal(
+    schemasDir: string,
+    refResolver: RefResolver,
+    schemas: Map<string, any>
+): Promise<void> {
+    let files: string[]
+    try {
+        files = await readdir(schemasDir)
+    } catch {
+        return
+    }
+
+    for (const file of files) {
+        if (!file.endsWith('.json')) continue
+        const filePath = join(schemasDir, file)
+        try {
+            const content = await readFile(filePath, 'utf-8')
+            const schema = JSON.parse(content)
+            if (schema.$id) {
+                refResolver.addSchema(schema)
+                // Store by $id (with version)
+                schemas.set(schema.$id, schema)
+                // Also store by entity name (without version) for easier lookup
+                const entityName = schema.$id.replace(/\.v\d+$/, '')
+                schemas.set(entityName, schema)
+            }
+        } catch {
+            // Skip files that can't be parsed
+        }
+    }
+}
+
+async function loadConfigFileEntities(
+    metaCacheDir: string,
+    ajv: Ajv,
+    schemas: Map<string, any>,
+    configEntities: Map<string, any>,
+    entities: Map<string, ResolvedEntity[]>
+): Promise<void> {
+
+    let metaFiles: string[]
+    try {
+        metaFiles = await readdir(metaCacheDir)
+    } catch {
+        return
+    }
+
+    for (const metaFile of metaFiles) {
+        if (!metaFile.endsWith('.json')) continue
+
+        try {
+            const metaPath = join(metaCacheDir, metaFile)
+            const metaContent = await readFile(metaPath, 'utf-8')
+            const metadata = JSON.parse(metaContent)
+
+            if (!metadata.entities || typeof metadata.entities !== 'object') continue
+
+            for (const [entityKey, entityMeta] of Object.entries(metadata.entities as Record<string, any>)) {
+                if (!entityKey.startsWith('#')) continue
+                const entityName = entityKey.substring(1)
+
+                configEntities.set(entityKey, entityMeta.data)
+
+                // Try to validate against schema
+                const schemaId = entityName + '.v0'
+                const schema = schemas.get(schemaId)
+
+                const resolved: ResolvedEntity = {
+                    schemaId,
+                    name: entityName,
+                    data: entityMeta.data,
+                    filePath: metadata.filePath,
+                    relPath: metadata.relPath,
+                    line: entityMeta.line,
+                    valid: true,
+                    errors: []
+                }
+
+                if (schema) {
+                    try {
+                        const validate = ajv.compile(schema)
+                        if (!validate(entityMeta.data)) {
+                            resolved.valid = false
+                            resolved.errors = validate.errors?.map(e => ({
+                                path: e.instancePath || '/',
+                                message: e.message,
+                                keyword: e.keyword
+                            })) || []
+                        }
+                    } catch {
+                        // Schema compilation failed
+                    }
+                }
+
+                if (!entities.has(entityKey)) entities.set(entityKey, [])
+                entities.get(entityKey)!.push(resolved)
+            }
+        } catch {
+            // Skip unparseable metadata files
+        }
+    }
+}
+
+interface LoadEntityFilesOptions {
+    entityDir: string
+    workspaceRootDir: string
+    ajv: Ajv
+    schemas: Map<string, any>
+    entityMap: Map<string, ResolvedEntity[]>
+    allEntities: Map<string, ResolvedEntity[]>
+    isFlat?: boolean // true for connections (flat .json files), false for facts (subdirectories)
+}
+
+async function loadEntityFiles(options: LoadEntityFilesOptions): Promise<void> {
+    const { entityDir, workspaceRootDir, ajv, schemas, entityMap, allEntities, isFlat = false } = options
+
+    let items: string[]
+    try {
+        items = await readdir(entityDir)
+    } catch {
+        return
+    }
+
+    if (isFlat) {
+        // Flat structure: files are directly in entityDir (e.g., connections)
+        for (const file of items) {
+            if (!file.startsWith('@') || !file.endsWith('.json')) continue
+
+            const entityTypeDir = file.replace(/\.json$/, '')
+            const entityName = entityTypeDir.replace(/~/g, '/')
+            const schema = schemas.get(entityName)
+            const filePath = join(entityDir, file)
+            const fileName = file.replace(/\.json$/, '')
+
+            try {
+                const content = await readFile(filePath, 'utf-8')
+                const data = JSON.parse(content)
+                const cleanData = { ...data }
+                delete cleanData.$schema
+                delete cleanData.$defs
+                delete cleanData.$id
+
+                const resolved: ResolvedEntity = {
+                    schemaId: entityName,
+                    name: fileName,
+                    data: cleanData,
+                    filePath,
+                    relPath: relative(workspaceRootDir, filePath),
+                    valid: true,
+                    errors: []
+                }
+
+                if (schema) {
+                    try {
+                        const validate = ajv.compile(schema)
+                        if (!validate(cleanData)) {
+                            resolved.valid = false
+                            resolved.errors = validate.errors?.map(e => ({
+                                path: e.instancePath || '/',
+                                message: e.message,
+                                keyword: e.keyword
+                            })) || []
+                        }
+                    } catch {
+                        // Schema compilation failed
+                    }
+                }
+
+                if (!entityMap.has(entityName)) entityMap.set(entityName, [])
+                entityMap.get(entityName)!.push(resolved)
+
+                const entityKey = `#${entityName}`
+                if (!allEntities.has(entityKey)) allEntities.set(entityKey, [])
+                allEntities.get(entityKey)!.push(resolved)
+            } catch {
+                // Skip unparseable files
+            }
+        }
+    } else {
+        // Nested structure: subdirectories contain entity files (e.g., facts)
+        for (const entityTypeDir of items) {
+            if (!entityTypeDir.startsWith('@')) continue
+            const entityTypePath = join(entityDir, entityTypeDir)
+            const entityName = entityTypeDir.replace(/~/g, '/')
+            const schema = schemas.get(entityName)
+
+            let entityFiles: string[]
+            try {
+                entityFiles = await readdir(entityTypePath)
+            } catch {
+                continue
+            }
+
+            for (const entityFile of entityFiles) {
+                if (!entityFile.endsWith('.json')) continue
+                const entityFilePath = join(entityTypePath, entityFile)
+                const entityFileName = entityFile.slice(0, -5) // strip .json
+
+                try {
+                    const content = await readFile(entityFilePath, 'utf-8')
+                    const data = JSON.parse(content)
+                    const cleanData = { ...data }
+                    delete cleanData.$schema
+                    delete cleanData.$defs
+                    delete cleanData.$id
+
+                    const resolved: ResolvedEntity = {
+                        schemaId: entityName,
+                        name: entityFileName,
+                        data: cleanData,
+                        filePath: entityFilePath,
+                        relPath: relative(workspaceRootDir, entityFilePath),
+                        valid: true,
+                        errors: []
+                    }
+
+                    if (schema) {
+                        try {
+                            const validate = ajv.compile(schema)
+                            if (!validate(cleanData)) {
+                                resolved.valid = false
+                                resolved.errors = validate.errors?.map(e => ({
+                                    path: e.instancePath || '/',
+                                    message: e.message,
+                                    keyword: e.keyword
+                                })) || []
+                            }
+                        } catch {
+                            // Schema compilation failed
+                        }
+                    }
+
+                    if (!entityMap.has(entityName)) entityMap.set(entityName, [])
+                    entityMap.get(entityName)!.push(resolved)
+
+                    const entityKey = `#${entityName}`
+                    if (!allEntities.has(entityKey)) allEntities.set(entityKey, [])
+                    allEntities.get(entityKey)!.push(resolved)
+                } catch {
+                    // Skip unparseable files
+                }
+            }
+        }
+    }
+}

package/lib/ucan.ts

@@ -0,0 +1,137 @@
+
+import { ed25519 } from '@ucanto/principal';
+import * as Server from '@ucanto/server';
+
+
+export async function generateKeypair(): Promise<{ did: string; privateKey: string }> {
+    const principal = await ed25519.generate();
+    // The principal itself is a Uint8Array containing the private key
+    const privateKeyBytes = new Uint8Array(principal as any);
+    return {
+        did: principal.did(),
+        privateKey: Buffer.from(privateKeyBytes).toString('base64'),
+    };
+}
+
+/**
+ * Extract DID from a base64-encoded private key
+ * @param privateKeyBase64 - Base64-encoded private key
+ * @returns The DID string
+ */
+export function didForPrivateKey(privateKeyBase64: string): string {
+    const keyBytes = Buffer.from(privateKeyBase64, 'base64');
+    const principal = ed25519.decode(new Uint8Array(keyBytes));
+    return principal.did();
+}
+
+/**
+ * Issue a UCAN capability delegation
+ * @param options.issuerPrivateKey - Base64-encoded private key of the issuer
+ * @param options.audienceDID - DID of the audience (recipient)
+ * @param options.capabilities - Array of capabilities to delegate
+ * @param options.expiresIn - Expiration time in seconds from now (default: 1 year)
+ * @returns Base64-encoded UCAN token
+ */
+export async function issueCapability(options: {
+    issuerPrivateKey: string;
+    audienceDID: string;
+    capabilities: Array<{ with: string; can: string }>;
+    expiresIn?: number;
+}): Promise<string> {
+    // Decode the issuer's private key
+    const keyBytes = Buffer.from(options.issuerPrivateKey, 'base64');
+    const issuer = ed25519.decode(new Uint8Array(keyBytes));
+
+    // Parse the audience DID
+    const audience = ed25519.Verifier.parse(options.audienceDID);
+
+    const expiresIn = options.expiresIn || 365 * 24 * 60 * 60; // 1 year
+    const expiration = Math.floor(Date.now() / 1000) + expiresIn;
+
+    const delegation = await Server.delegate({
+        issuer,
+        audience,
+        capabilities: options.capabilities,
+        expiration,
+    });
+
+    const archive = await delegation.archive();
+    if (!archive.ok) {
+        throw new Error('Failed to archive delegation');
+    }
+    return Buffer.from(archive.ok).toString('base64');
+};
+
+/**
+ * Validate a UCAN capability delegation
+ * @param options.ucanToken - Base64-encoded UCAN token
+ * @param options.issuerDID - Expected DID of the issuer
+ * @param options.expectedCapability - Expected capability (optional)
+ * @returns Validation result with delegation details
+ */
+export async function validateCapability(options: {
+    ucanToken: string;
+    issuerDID: string;
+    expectedCapability?: { can: string };
+}): Promise<{
+    valid: boolean;
+    error?: string;
+    issuer?: string;
+    audience?: string;
+    capabilities?: Array<{ with: string; can: string }>;
+    expiration?: number;
+}> {
+    try {
+        // Parse the UCAN from the token
+        const carBytes = Buffer.from(options.ucanToken, 'base64');
+        const result: any = await Server.Delegation.extract(carBytes);
+        if (!result.ok) {
+            return {
+                valid: false,
+                error: `Failed to parse UCAN: ${result.error.message}`,
+            };
+        }
+        const delegation: any = result.ok;
+
+        // Basic validation: check expiration
+        const now = Math.floor(Date.now() / 1000);
+        if (delegation.expiration && delegation.expiration < now) {
+            return {
+                valid: false,
+                error: 'UCAN has expired',
+            };
+        }
+
+        // Verify issuer matches expected
+        if (delegation.issuer.did() !== options.issuerDID) {
+            return {
+                valid: false,
+                error: `UCAN not issued by expected issuer. Expected: ${options.issuerDID}, Got: ${delegation.issuer.did()}`,
+            };
+        }
+
+        // Validate capability if specified
+        if (options.expectedCapability) {
+            const capability = delegation.capabilities[0];
+            if (capability.can !== options.expectedCapability.can) {
+                return {
+                    valid: false,
+                    error: `Invalid capability: expected '${options.expectedCapability.can}', got '${capability.can}'`,
+                };
+            }
+        }
+
+        return {
+            valid: true,
+            issuer: delegation.issuer.did(),
+            audience: delegation.audience.did(),
+            capabilities: delegation.capabilities,
+            expiration: delegation.expiration,
+        };
+    } catch (error: any) {
+        return {
+            valid: false,
+            error: `Failed to validate UCAN: ${error.message}`,
+        };
+    }
+}