@kubuild/core 0.0.1

package/dist/importer.d.ts

@@ -0,0 +1,243 @@
+import { PageDocument, DocumentMetadata, Manifest, ManifestAssetItem } from '@kubuild/schema';
+import { ComponentRegistryLike } from './validator';
+import { MigrationRegistry } from './migration';
+import type { AssetProvider, AssetInfo } from './interfaces';
+export interface SecurityLimits {
+    /**
+     * Maximum allowed size for the compressed archive in bytes (default: 50MB).
+     */
+    maxArchiveSize?: number;
+    /**
+     * Maximum total uncompressed size across all files in bytes (default: 100MB).
+     */
+    maxUncompressedSize?: number;
+    /**
+     * Maximum number of files in the archive (default: 1000).
+     */
+    maxFileCount?: number;
+    /**
+     * Maximum size for any individual asset in bytes (default: 25MB).
+     */
+    maxAssetSize?: number;
+}
+export declare const DEFAULT_SECURITY_LIMITS: Required<SecurityLimits>;
+export type MissingDependencyPolicy = 'cancel' | 'import-with-placeholder' | 'install-or-register-before-import';
+export type AssetCollisionStrategy = 'reject' | 'rename' | 'overwrite' | 'reuse-existing';
+export interface AssetConflict {
+    assetId: string;
+    path: string;
+    mimeType: string;
+    size: number;
+    existingAsset?: AssetInfo | Record<string, unknown>;
+}
+export interface AssetConflictResolution {
+    action: AssetCollisionStrategy;
+    newAssetId?: string;
+}
+export type PreflightDiagnosticCode = 'ARCHIVE_EMPTY' | 'ARCHIVE_CORRUPT' | 'SIZE_LIMIT_EXCEEDED' | 'FILE_COUNT_EXCEEDED' | 'ZIP_SLIP_DETECTED' | 'EXECUTABLE_ASSET_DETECTED' | 'PROTOTYPE_POLLUTION_DETECTED' | 'MISSING_MANIFEST' | 'INVALID_MANIFEST' | 'MISSING_PAGE_DOCUMENT' | 'INVALID_PAGE_DOCUMENT' | 'UNSUPPORTED_SCHEMA_VERSION' | 'NO_MIGRATION_PATH' | 'MIGRATION_FAILED' | 'ASSET_FILE_MISSING' | 'ASSET_SIZE_MISMATCH' | 'ASSET_CHECKSUM_MISMATCH' | 'ASSET_LIMIT_EXCEEDED' | 'ASSET_CONFLICT' | 'MISSING_COMPONENTS' | 'MISSING_CAPABILITIES' | 'HOST_ADAPTER_ERROR';
+export interface PreflightDiagnostic {
+    code: PreflightDiagnosticCode;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    path?: string;
+    details?: Record<string, unknown>;
+}
+export interface PreflightOptions {
+    /**
+     * Component registry to check required custom components.
+     */
+    componentRegistry?: ComponentRegistryLike;
+    /**
+     * Allowlist of known component type names (used if componentRegistry is not provided or in combination).
+     */
+    knownComponentTypes?: string[] | Set<string>;
+    /**
+     * Allowlist of capabilities supported by host.
+     */
+    supportedCapabilities?: string[] | Set<string>;
+    /**
+     * Security limits for archive and files.
+     */
+    securityLimits?: SecurityLimits;
+    /**
+     * Custom migration registry.
+     */
+    migrationRegistry?: MigrationRegistry;
+    /**
+     * Target schema version (defaults to CURRENT_SCHEMA_VERSION = "1.0.0").
+     */
+    targetSchemaVersion?: string;
+    /**
+     * Policy for handling missing custom components and capabilities.
+     * - 'cancel' (default): Abort import with blocking errors when components/capabilities are missing.
+     * - 'import-with-placeholder': Allow import, keeping missing component nodes and props intact for placeholder rendering.
+     * - 'install-or-register-before-import': Call onMissingDependency to register/install before finalizing import.
+     */
+    dependencyPolicy?: MissingDependencyPolicy;
+    /**
+     * Hook called when dependencyPolicy is 'install-or-register-before-import'.
+     */
+    onMissingDependency?: (missing: {
+        components: string[];
+        capabilities: string[];
+    }, preflight: PreflightReport) => Promise<boolean | void> | boolean | void;
+    /**
+     * If true, missing components are treated as warnings rather than blocking errors.
+     * (Equivalent to setting dependencyPolicy: 'import-with-placeholder')
+     */
+    allowMissingComponents?: boolean;
+    /**
+     * If true, missing capabilities are treated as warnings rather than blocking errors.
+     * (Equivalent to setting dependencyPolicy: 'import-with-placeholder')
+     */
+    allowMissingCapabilities?: boolean;
+    /**
+     * Strategy for resolving asset collisions with existing host assets.
+     * - 'reject' (default): Refuse import if asset collision is detected without an explicit resolution strategy.
+     * - 'rename': Rename the incoming asset to avoid overwriting host assets, and automatically remap document asset references.
+     * - 'overwrite': Explicitly overwrite host assets with incoming archive assets.
+     * - 'reuse-existing': Reuse existing host assets and skip writing archive asset binaries.
+     */
+    assetCollisionStrategy?: AssetCollisionStrategy;
+    /**
+     * Existing host asset IDs or checker function to detect collisions.
+     */
+    existingAssetIds?: string[] | Set<string> | ((assetId: string) => boolean | Promise<boolean>);
+    /**
+     * Custom naming function when renaming colliding assets.
+     */
+    renameAssetStrategy?: (incoming: ManifestAssetItem, existingIds: Set<string>) => string;
+    /**
+     * Host AssetProvider to resolve existing assets or upload extracted local assets.
+     */
+    assetProvider?: AssetProvider;
+    /**
+     * Fine-grained callback for resolving individual asset conflicts.
+     */
+    onAssetConflict?: (conflict: AssetConflict) => Promise<AssetConflictResolution | AssetCollisionStrategy> | AssetConflictResolution | AssetCollisionStrategy;
+}
+export interface PreflightReport {
+    /**
+     * True if archive is completely safe and syntactically valid.
+     */
+    valid: boolean;
+    /**
+     * True if archive can be safely imported given the host's supported components/capabilities and asset policies.
+     */
+    canImport: boolean;
+    /**
+     * Parsed manifest if available.
+     */
+    manifest?: Manifest;
+    /**
+     * Parsed metadata if available.
+     */
+    rawMetadata?: DocumentMetadata;
+    /**
+     * Schema version reported in the document/manifest.
+     */
+    sourceVersion?: string;
+    /**
+     * Target schema version.
+     */
+    targetVersion: string;
+    /**
+     * True if the document version differs from target version and requires migration.
+     */
+    requiresMigration: boolean;
+    /**
+     * Migration path version sequence if migration is needed.
+     */
+    migrationPath?: string[];
+    /**
+     * List of custom component types required by package that are missing in host.
+     */
+    missingComponents: string[];
+    /**
+     * List of capabilities required by package that are missing in host.
+     */
+    missingCapabilities: string[];
+    /**
+     * Active policy for missing dependencies.
+     */
+    dependencyPolicy: MissingDependencyPolicy;
+    /**
+     * Number of valid local assets declared in manifest.
+     */
+    assetCount: number;
+    /**
+     * List of detected asset collisions with existing host assets.
+     */
+    assetConflicts: AssetConflict[];
+    /**
+     * Active strategy for handling asset collisions.
+     */
+    assetCollisionStrategy: AssetCollisionStrategy;
+    /**
+     * Total uncompressed size of all files in archive.
+     */
+    totalUncompressedBytes: number;
+    /**
+     * Diagnostics collected during inspection.
+     */
+    diagnostics: PreflightDiagnostic[];
+}
+export interface ImportPackageOptions extends PreflightOptions {
+    /**
+     * Custom asset importer hook called for each extracted asset.
+     */
+    onAssetImport?: (assetId: string, assetBytes: Uint8Array, assetMeta: ManifestAssetItem) => Promise<AssetInfo | string | void> | AssetInfo | string | void;
+}
+export interface ExtractedAsset {
+    bytes: Uint8Array;
+    meta: ManifestAssetItem;
+    hostInfo?: AssetInfo | string;
+}
+export interface ImportPackageSuccess {
+    success: true;
+    document: PageDocument;
+    manifest: Manifest;
+    metadata: DocumentMetadata;
+    extractedAssets: Map<string, ExtractedAsset>;
+    renamedAssets?: Record<string, string>;
+    preflight: PreflightReport;
+}
+export interface ImportPackageFailure {
+    success: false;
+    errors: PreflightDiagnostic[];
+    diagnosticMessage: string;
+    preflight?: PreflightReport;
+}
+export type ImportPackageResult = ImportPackageSuccess | ImportPackageFailure;
+/**
+ * Checks if a zip entry path contains zip-slip or directory traversal attempts.
+ */
+export declare function isDangerousPath(filepath: string): boolean;
+/**
+ * Inspects a .stora archive and runs non-destructive preflight validation.
+ * Verifies security limits, path safety, manifest, checksums, component/capability requirements, and migration status.
+ */
+export declare function preflightPackage(archiveData: Uint8Array | ArrayBuffer, options?: PreflightOptions): Promise<PreflightReport>;
+/**
+ * Preview a .stora package without mutating host state.
+ * Returns missing dependencies, asset conflicts, schema migration status, and diagnostics.
+ */
+export declare const previewImportPackage: typeof preflightPackage;
+/**
+ * Alias for preflightPackage.
+ */
+export declare const inspectPackage: typeof preflightPackage;
+/**
+ * Default generator for renaming colliding asset IDs.
+ */
+export declare function defaultRenameAssetStrategy(incoming: ManifestAssetItem, existingIds: Set<string>): string;
+/**
+ * Imports a .stora package with preflight safety checks, schema migration, missing dependency policy,
+ * and host-controlled asset collision handling.
+ */
+export declare function importPackage(archiveData: Uint8Array | ArrayBuffer, options?: ImportPackageOptions): Promise<ImportPackageResult>;
+/**
+ * Alias for importPackage.
+ */
+export declare const importStoraPackage: typeof importPackage;
+//# sourceMappingURL=importer.d.ts.map

package/dist/importer.d.ts.map

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