@originals/sdk 1.4.3 → 1.4.5

package/dist/kinds/KindRegistry.js

@@ -0,0 +1,216 @@
+/**
+ * Kind Registry
+ *
+ * Central registry for Original kinds, providing validation and type management.
+ */
+import { OriginalKind, } from './types';
+import { ValidationUtils, AppValidator, AgentValidator, ModuleValidator, DatasetValidator, MediaValidator, DocumentValidator, } from './validators';
+/**
+ * Registry for Original kinds
+ *
+ * Provides centralized validation and type information for all kinds.
+ */
+export class KindRegistry {
+    constructor() {
+        this.validators = new Map();
+        this.registerDefaultValidators();
+    }
+    /**
+     * Get the singleton instance
+     */
+    static getInstance() {
+        if (!KindRegistry.instance) {
+            KindRegistry.instance = new KindRegistry();
+        }
+        return KindRegistry.instance;
+    }
+    /**
+     * Register default validators for all built-in kinds
+     */
+    registerDefaultValidators() {
+        this.validators.set(OriginalKind.App, new AppValidator());
+        this.validators.set(OriginalKind.Agent, new AgentValidator());
+        this.validators.set(OriginalKind.Module, new ModuleValidator());
+        this.validators.set(OriginalKind.Dataset, new DatasetValidator());
+        this.validators.set(OriginalKind.Media, new MediaValidator());
+        this.validators.set(OriginalKind.Document, new DocumentValidator());
+    }
+    /**
+     * Register a custom validator for a kind
+     * Can be used to override built-in validators or add new kinds
+     */
+    registerValidator(kind, validator) {
+        this.validators.set(kind, validator);
+    }
+    /**
+     * Get the validator for a kind
+     */
+    getValidator(kind) {
+        return this.validators.get(kind);
+    }
+    /**
+     * Check if a kind is registered
+     */
+    hasKind(kind) {
+        return this.validators.has(kind);
+    }
+    /**
+     * Get all registered kinds
+     */
+    getRegisteredKinds() {
+        return Array.from(this.validators.keys());
+    }
+    /**
+     * Validate a manifest
+     *
+     * @param manifest - The manifest to validate
+     * @param options - Validation options
+     * @returns Validation result
+     */
+    validate(manifest, options) {
+        // First check if kind is valid
+        if (!manifest.kind) {
+            return ValidationUtils.failure([
+                ValidationUtils.error('MISSING_KIND', 'Manifest must specify a kind', 'kind'),
+            ]);
+        }
+        // Check if kind is registered
+        if (!this.hasKind(manifest.kind)) {
+            return ValidationUtils.failure([
+                ValidationUtils.error('UNKNOWN_KIND', `Unknown kind: "${manifest.kind}". Registered kinds: ${this.getRegisteredKinds().join(', ')}`, 'kind', manifest.kind),
+            ]);
+        }
+        // Get validator and run validation
+        const validator = this.getValidator(manifest.kind);
+        if (!validator) {
+            return ValidationUtils.failure([
+                ValidationUtils.error('VALIDATOR_NOT_FOUND', `No validator found for kind: ${manifest.kind}`, 'kind'),
+            ]);
+        }
+        const result = validator.validate(manifest);
+        // In strict mode, treat warnings as errors
+        if (options?.strictMode && result.warnings.length > 0) {
+            const warningErrors = result.warnings.map(w => ValidationUtils.error(`STRICT_${w.code}`, `[Warning treated as error] ${w.message}`, w.path));
+            return ValidationUtils.failure([...result.errors, ...warningErrors], []);
+        }
+        return result;
+    }
+    /**
+     * Validate a manifest and throw if invalid
+     */
+    validateOrThrow(manifest, options) {
+        if (options?.skipValidation) {
+            return;
+        }
+        const result = this.validate(manifest, options);
+        if (!result.isValid) {
+            const errorMessages = result.errors.map(e => {
+                const path = e.path ? ` at ${e.path}` : '';
+                return `[${e.code}]${path}: ${e.message}`;
+            });
+            throw new Error(`Manifest validation failed:\n${errorMessages.join('\n')}`);
+        }
+    }
+    /**
+     * Check if a value is a valid OriginalKind
+     */
+    static isValidKind(value) {
+        return typeof value === 'string' && Object.values(OriginalKind).includes(value);
+    }
+    /**
+     * Parse a kind string to OriginalKind
+     * Accepts both full URIs (originals:kind:app) and short names (app)
+     */
+    static parseKind(value) {
+        // Check if it's already a full kind URI
+        if (KindRegistry.isValidKind(value)) {
+            return value;
+        }
+        // Try to match short name
+        const normalized = value.toLowerCase().trim();
+        for (const kind of Object.values(OriginalKind)) {
+            const shortName = kind.split(':').pop()?.toLowerCase();
+            if (shortName === normalized) {
+                return kind;
+            }
+        }
+        return null;
+    }
+    /**
+     * Get the short name of a kind (e.g., "app" from "originals:kind:app")
+     */
+    static getShortName(kind) {
+        return kind.split(':').pop() || kind;
+    }
+    /**
+     * Get human-readable display name for a kind
+     */
+    static getDisplayName(kind) {
+        const shortName = KindRegistry.getShortName(kind);
+        return shortName.charAt(0).toUpperCase() + shortName.slice(1);
+    }
+    /**
+     * Create an empty manifest template for a kind
+     * Useful for scaffolding new Originals
+     */
+    static createTemplate(kind, name, version = '1.0.0') {
+        const base = {
+            kind,
+            name,
+            version,
+            resources: [],
+        };
+        // Add kind-specific metadata templates
+        switch (kind) {
+            case OriginalKind.App:
+                return {
+                    ...base,
+                    metadata: {
+                        runtime: 'node',
+                        entrypoint: 'index.js',
+                    },
+                };
+            case OriginalKind.Agent:
+                return {
+                    ...base,
+                    metadata: {
+                        capabilities: [],
+                    },
+                };
+            case OriginalKind.Module:
+                return {
+                    ...base,
+                    metadata: {
+                        format: 'esm',
+                        main: 'index.js',
+                    },
+                };
+            case OriginalKind.Dataset:
+                return {
+                    ...base,
+                    metadata: {
+                        format: 'json',
+                        schema: {},
+                    },
+                };
+            case OriginalKind.Media:
+                return {
+                    ...base,
+                    metadata: {
+                        mediaType: 'image',
+                        mimeType: 'image/png',
+                    },
+                };
+            case OriginalKind.Document:
+                return {
+                    ...base,
+                    metadata: {
+                        format: 'markdown',
+                        content: 'content',
+                    },
+                };
+            default:
+                return base;
+        }
+    }
+}

package/dist/kinds/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Originals Kind System
+ *
+ * Provides typed "Kinds" for Originals - a classification system that
+ * enables kind-specific validation, metadata schemas, and behaviors.
+ *
+ * @example
+ * ```typescript
+ * import { OriginalKind, KindRegistry } from '@originals/sdk';
+ *
+ * // Create an App Original manifest
+ * const appManifest = {
+ *   kind: OriginalKind.App,
+ *   name: 'MyApp',
+ *   version: '1.0.0',
+ *   resources: [entrypointResource],
+ *   metadata: {
+ *     runtime: 'node',
+ *     entrypoint: 'index.js',
+ *   },
+ * };
+ *
+ * // Validate the manifest
+ * const registry = KindRegistry.getInstance();
+ * const result = registry.validate(appManifest);
+ * if (!result.isValid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+export { OriginalKind, type DependencyRef, type BaseManifest, type AppMetadata, type AgentMetadata, type ModuleMetadata, type DatasetMetadata, type MediaMetadata, type DocumentMetadata, type KindMetadataMap, type KindMetadata, type OriginalManifest, type AppManifest, type AgentManifest, type ModuleManifest, type DatasetManifest, type MediaManifest, type DocumentManifest, type AnyManifest, type ValidationResult, type ValidationError, type ValidationWarning, type CreateTypedOriginalOptions, } from './types';
+export { KindRegistry } from './KindRegistry';
+export { type KindValidator, BaseKindValidator, ValidationUtils, AppValidator, AgentValidator, ModuleValidator, DatasetValidator, MediaValidator, DocumentValidator, } from './validators';

package/dist/kinds/index.js

@@ -0,0 +1,36 @@
+/**
+ * Originals Kind System
+ *
+ * Provides typed "Kinds" for Originals - a classification system that
+ * enables kind-specific validation, metadata schemas, and behaviors.
+ *
+ * @example
+ * ```typescript
+ * import { OriginalKind, KindRegistry } from '@originals/sdk';
+ *
+ * // Create an App Original manifest
+ * const appManifest = {
+ *   kind: OriginalKind.App,
+ *   name: 'MyApp',
+ *   version: '1.0.0',
+ *   resources: [entrypointResource],
+ *   metadata: {
+ *     runtime: 'node',
+ *     entrypoint: 'index.js',
+ *   },
+ * };
+ *
+ * // Validate the manifest
+ * const registry = KindRegistry.getInstance();
+ * const result = registry.validate(appManifest);
+ * if (!result.isValid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+// Type exports
+export { OriginalKind, } from './types';
+// Registry export
+export { KindRegistry } from './KindRegistry';
+// Validator exports (for extension/customization)
+export { BaseKindValidator, ValidationUtils, AppValidator, AgentValidator, ModuleValidator, DatasetValidator, MediaValidator, DocumentValidator, } from './validators';

package/dist/kinds/types.d.ts

@@ -0,0 +1,363 @@
+/**
+ * Originals Kind System Types
+ *
+ * Defines the typed "Kinds" for Originals - a classification system that
+ * enables kind-specific validation, metadata schemas, and behaviors.
+ */
+import type { AssetResource } from '../types/common';
+/**
+ * The supported Original kinds
+ * Each kind represents a category of digital asset with specific requirements
+ */
+export declare enum OriginalKind {
+    /** Executable application with runtime and entrypoint */
+    App = "originals:kind:app",
+    /** AI agent or autonomous system with capabilities and model info */
+    Agent = "originals:kind:agent",
+    /** Reusable code module with exports and dependencies */
+    Module = "originals:kind:module",
+    /** Structured data collection with schema definition */
+    Dataset = "originals:kind:dataset",
+    /** Media content (image, audio, video) with format metadata */
+    Media = "originals:kind:media",
+    /** Text document with formatting and sections */
+    Document = "originals:kind:document"
+}
+/**
+ * Reference to a dependency Original
+ */
+export interface DependencyRef {
+    /** DID of the dependency Original */
+    did: string;
+    /** Semantic version constraint (e.g., "^1.0.0", ">=2.0.0") */
+    version?: string;
+    /** Human-readable name of the dependency */
+    name?: string;
+    /** Whether this dependency is required (default: true) */
+    optional?: boolean;
+}
+/**
+ * Base manifest fields shared by all kinds
+ */
+export interface BaseManifest {
+    /** Human-readable name */
+    name: string;
+    /** Semantic version string (e.g., "1.0.0") */
+    version: string;
+    /** Optional description */
+    description?: string;
+    /** Resources associated with this Original */
+    resources: AssetResource[];
+    /** Dependencies on other Originals */
+    dependencies?: DependencyRef[];
+    /** Free-form tags for categorization */
+    tags?: string[];
+    /** Author information */
+    author?: {
+        name?: string;
+        did?: string;
+        email?: string;
+        url?: string;
+    };
+    /** License identifier (SPDX) */
+    license?: string;
+    /** URL for more information */
+    homepage?: string;
+    /** Repository URL */
+    repository?: string;
+}
+/**
+ * App-specific metadata
+ */
+export interface AppMetadata {
+    /** Runtime environment (e.g., "node", "browser", "deno", "bun") */
+    runtime: string;
+    /** Entrypoint resource ID or path */
+    entrypoint: string;
+    /** Required runtime version */
+    runtimeVersion?: string;
+    /** Minimum required runtime version */
+    minRuntimeVersion?: string;
+    /** App permissions required */
+    permissions?: string[];
+    /** Environment variables expected */
+    env?: Record<string, {
+        description?: string;
+        required?: boolean;
+        default?: string;
+    }>;
+    /** Supported platforms */
+    platforms?: ('linux' | 'darwin' | 'windows' | 'web')[];
+    /** App icons by size */
+    icons?: Record<string, string>;
+    /** CLI commands exposed */
+    commands?: Record<string, {
+        description: string;
+        args?: string[];
+    }>;
+}
+/**
+ * Agent-specific metadata
+ */
+export interface AgentMetadata {
+    /** Agent capabilities/skills */
+    capabilities: string[];
+    /** Model information if AI-based */
+    model?: {
+        provider?: string;
+        name: string;
+        version?: string;
+        parameters?: Record<string, unknown>;
+    };
+    /** Input types the agent accepts */
+    inputTypes?: string[];
+    /** Output types the agent produces */
+    outputTypes?: string[];
+    /** Memory/state configuration */
+    memory?: {
+        type: 'stateless' | 'session' | 'persistent';
+        maxSize?: number;
+    };
+    /** System prompt or instructions */
+    systemPrompt?: string;
+    /** Tools/functions the agent can use */
+    tools?: Array<{
+        name: string;
+        description: string;
+        parameters?: Record<string, unknown>;
+    }>;
+    /** Rate limiting configuration */
+    rateLimit?: {
+        requestsPerMinute?: number;
+        tokensPerMinute?: number;
+    };
+}
+/**
+ * Module-specific metadata
+ */
+export interface ModuleMetadata {
+    /** Module format (esm, commonjs, umd, etc.) */
+    format: 'esm' | 'commonjs' | 'umd' | 'amd' | 'iife';
+    /** Main entrypoint file (resource ID) */
+    main: string;
+    /** Types definition file (resource ID) */
+    types?: string;
+    /** Exported symbols/functions */
+    exports?: Record<string, string | {
+        import?: string;
+        require?: string;
+        types?: string;
+    }>;
+    /** Peer dependencies (expected to be provided by consumer) */
+    peerDependencies?: Record<string, string>;
+    /** Browser-specific entrypoint */
+    browser?: string;
+    /** Files included in the module */
+    files?: string[];
+    /** Side effects declaration */
+    sideEffects?: boolean | string[];
+    /** TypeScript configuration */
+    typescript?: {
+        strict?: boolean;
+        target?: string;
+        moduleResolution?: string;
+    };
+}
+/**
+ * Dataset-specific metadata
+ */
+export interface DatasetMetadata {
+    /** Schema definition (JSON Schema, or URL to schema) */
+    schema: Record<string, unknown> | string;
+    /** Data format (csv, json, parquet, etc.) */
+    format: string;
+    /** Number of records/rows */
+    recordCount?: number;
+    /** Data columns/fields */
+    columns?: Array<{
+        name: string;
+        type: string;
+        description?: string;
+        nullable?: boolean;
+    }>;
+    /** Data source information */
+    source?: {
+        origin?: string;
+        collectedAt?: string;
+        methodology?: string;
+    };
+    /** Dataset statistics */
+    statistics?: {
+        sizeBytes?: number;
+        compression?: string;
+        checksums?: Record<string, string>;
+    };
+    /** License specific to the data */
+    dataLicense?: string;
+    /** Privacy classification */
+    privacy?: 'public' | 'internal' | 'confidential' | 'restricted';
+    /** Update frequency */
+    updateFrequency?: 'realtime' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'static';
+}
+/**
+ * Media-specific metadata
+ */
+export interface MediaMetadata {
+    /** Media type (image, audio, video, 3d) */
+    mediaType: 'image' | 'audio' | 'video' | '3d' | 'animation';
+    /** MIME type of the primary media resource */
+    mimeType: string;
+    /** Dimensions (for images and video) */
+    dimensions?: {
+        width: number;
+        height: number;
+        aspectRatio?: string;
+    };
+    /** Duration in seconds (for audio/video) */
+    duration?: number;
+    /** Frame rate (for video/animation) */
+    frameRate?: number;
+    /** Audio channels (for audio/video) */
+    audioChannels?: number;
+    /** Sample rate (for audio) */
+    sampleRate?: number;
+    /** Codec information */
+    codec?: string;
+    /** Bitrate in kbps */
+    bitrate?: number;
+    /** Color space */
+    colorSpace?: string;
+    /** Thumbnail resource ID */
+    thumbnail?: string;
+    /** Preview/low-res version resource ID */
+    preview?: string;
+    /** Alt text for accessibility */
+    altText?: string;
+    /** Caption or transcript */
+    caption?: string;
+    /** EXIF or similar metadata */
+    exif?: Record<string, unknown>;
+}
+/**
+ * Document-specific metadata
+ */
+export interface DocumentMetadata {
+    /** Document format (markdown, html, pdf, docx, etc.) */
+    format: 'markdown' | 'html' | 'pdf' | 'docx' | 'txt' | 'asciidoc' | 'rst' | 'latex';
+    /** Document language (ISO 639-1) */
+    language?: string;
+    /** Main content resource ID */
+    content: string;
+    /** Table of contents */
+    toc?: Array<{
+        title: string;
+        level: number;
+        anchor?: string;
+    }>;
+    /** Page count */
+    pageCount?: number;
+    /** Word count */
+    wordCount?: number;
+    /** Reading time in minutes */
+    readingTime?: number;
+    /** Keywords */
+    keywords?: string[];
+    /** Abstract or summary */
+    abstract?: string;
+    /** Bibliography/references */
+    references?: Array<{
+        id: string;
+        title: string;
+        authors?: string[];
+        year?: number;
+        url?: string;
+        doi?: string;
+    }>;
+    /** Document status */
+    status?: 'draft' | 'review' | 'published' | 'archived';
+    /** Revision number */
+    revision?: number;
+}
+/**
+ * Maps each kind to its specific metadata type
+ */
+export interface KindMetadataMap {
+    [OriginalKind.App]: AppMetadata;
+    [OriginalKind.Agent]: AgentMetadata;
+    [OriginalKind.Module]: ModuleMetadata;
+    [OriginalKind.Dataset]: DatasetMetadata;
+    [OriginalKind.Media]: MediaMetadata;
+    [OriginalKind.Document]: DocumentMetadata;
+}
+/**
+ * Type-safe metadata accessor
+ */
+export type KindMetadata<K extends OriginalKind> = K extends keyof KindMetadataMap ? KindMetadataMap[K] : never;
+/**
+ * Generic Original manifest with kind-specific metadata
+ */
+export interface OriginalManifest<K extends OriginalKind = OriginalKind> extends BaseManifest {
+    /** The kind of Original */
+    kind: K;
+    /** Kind-specific metadata */
+    metadata: KindMetadata<K>;
+}
+/**
+ * Type-specific manifest aliases for convenience
+ */
+export type AppManifest = OriginalManifest<OriginalKind.App>;
+export type AgentManifest = OriginalManifest<OriginalKind.Agent>;
+export type ModuleManifest = OriginalManifest<OriginalKind.Module>;
+export type DatasetManifest = OriginalManifest<OriginalKind.Dataset>;
+export type MediaManifest = OriginalManifest<OriginalKind.Media>;
+export type DocumentManifest = OriginalManifest<OriginalKind.Document>;
+/**
+ * Union type of all possible manifests
+ */
+export type AnyManifest = AppManifest | AgentManifest | ModuleManifest | DatasetManifest | MediaManifest | DocumentManifest;
+/**
+ * Result of validating a manifest
+ */
+export interface ValidationResult {
+    /** Whether the manifest is valid */
+    isValid: boolean;
+    /** Validation errors if any */
+    errors: ValidationError[];
+    /** Validation warnings (non-fatal) */
+    warnings: ValidationWarning[];
+}
+/**
+ * A validation error
+ */
+export interface ValidationError {
+    /** Error code */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Path to the invalid field (e.g., "metadata.entrypoint") */
+    path?: string;
+    /** The invalid value */
+    value?: unknown;
+}
+/**
+ * A validation warning (non-fatal issue)
+ */
+export interface ValidationWarning {
+    /** Warning code */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Path to the field with warning */
+    path?: string;
+    /** Suggested fix */
+    suggestion?: string;
+}
+/**
+ * Options for creating a typed Original
+ */
+export interface CreateTypedOriginalOptions {
+    /** Skip validation (not recommended) */
+    skipValidation?: boolean;
+    /** Treat warnings as errors */
+    strictMode?: boolean;
+}

package/dist/kinds/types.js

@@ -0,0 +1,25 @@
+/**
+ * Originals Kind System Types
+ *
+ * Defines the typed "Kinds" for Originals - a classification system that
+ * enables kind-specific validation, metadata schemas, and behaviors.
+ */
+/**
+ * The supported Original kinds
+ * Each kind represents a category of digital asset with specific requirements
+ */
+export var OriginalKind;
+(function (OriginalKind) {
+    /** Executable application with runtime and entrypoint */
+    OriginalKind["App"] = "originals:kind:app";
+    /** AI agent or autonomous system with capabilities and model info */
+    OriginalKind["Agent"] = "originals:kind:agent";
+    /** Reusable code module with exports and dependencies */
+    OriginalKind["Module"] = "originals:kind:module";
+    /** Structured data collection with schema definition */
+    OriginalKind["Dataset"] = "originals:kind:dataset";
+    /** Media content (image, audio, video) with format metadata */
+    OriginalKind["Media"] = "originals:kind:media";
+    /** Text document with formatting and sections */
+    OriginalKind["Document"] = "originals:kind:document";
+})(OriginalKind || (OriginalKind = {}));

package/dist/kinds/validators/AgentValidator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Agent Kind Validator
+ *
+ * Validates manifests for AI agents or autonomous systems with capabilities and model info.
+ */
+import { OriginalKind, type OriginalManifest, type ValidationResult } from '../types';
+import { BaseKindValidator } from './base';
+/**
+ * Validator for Agent Originals
+ */
+export declare class AgentValidator extends BaseKindValidator<OriginalKind.Agent> {
+    readonly kind = OriginalKind.Agent;
+    protected validateKind(manifest: OriginalManifest<OriginalKind.Agent>): ValidationResult;
+}