@fgv/ts-res 5.0.0-16 → 5.0.0-18

package/lib/packlets/zip-archive/zipArchiveLoader.js

@@ -0,0 +1,285 @@
+"use strict";
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZipArchiveLoader = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_extras_1 = require("@fgv/ts-extras");
+const zipArchiveFormat_1 = require("./zipArchiveFormat");
+/**
+ * ZIP archive loader extending ts-extras foundation
+ * @public
+ */
+class ZipArchiveLoader {
+    /**
+     * Load ZIP archive from File object (Browser)
+     * @param file - File object from file input
+     * @param options - Loading options
+     * @param onProgress - Optional progress callback
+     * @returns Result containing loaded archive data
+     */
+    async loadFromFile(file, options = {}, onProgress) {
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('reading-file', 0, `Reading file: ${file.name}`);
+        if (!(0, zipArchiveFormat_1.isZipFile)(file.name)) {
+            return (0, ts_utils_1.fail)(`File ${file.name} is not a ZIP file`);
+        }
+        try {
+            const buffer = await file.arrayBuffer();
+            onProgress === null || onProgress === void 0 ? void 0 : onProgress('reading-file', 100, 'File read complete');
+            return await this.loadFromBuffer(buffer, options, onProgress);
+            /* c8 ignore next 3 - defense in depth against internal error */
+        }
+        catch (error) {
+            return (0, ts_utils_1.fail)(`Failed to read file: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Load ZIP archive from ArrayBuffer (Universal)
+     * @param buffer - ZIP data buffer
+     * @param options - Loading options
+     * @param onProgress - Optional progress callback
+     * @returns Result containing loaded archive data
+     */
+    async loadFromBuffer(buffer, options = {}, onProgress) {
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('parsing-zip', 0, 'Parsing ZIP archive');
+        const zipAccessorsResult = ts_extras_1.ZipFileTree.ZipFileTreeAccessors.fromBuffer(buffer);
+        if (zipAccessorsResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Failed to parse ZIP: ${zipAccessorsResult.message}`);
+        }
+        const zipAccessors = zipAccessorsResult.value;
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('parsing-zip', 100, 'ZIP archive parsed');
+        // Load manifest
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('loading-manifest', 0, 'Loading manifest');
+        const manifestResult = this._loadManifestFromAccessors(zipAccessors);
+        if (manifestResult.isFailure()) {
+            return (0, ts_utils_1.fail)(manifestResult.message);
+        }
+        const manifest = manifestResult.value;
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('loading-manifest', 100, 'Manifest loaded');
+        // Load configuration
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('loading-config', 0, 'Loading configuration');
+        const configResult = this._loadConfigurationFromAccessors(zipAccessors, manifest, options);
+        if (configResult.isFailure()) {
+            return (0, ts_utils_1.fail)(configResult.message);
+        }
+        const config = configResult.value;
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('loading-config', 100, 'Configuration loaded');
+        // Extract files and directory structure
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('extracting-files', 0, 'Extracting files');
+        const filesResult = await this._extractFilesFromAccessors(zipAccessors, onProgress);
+        /* c8 ignore next 3 - defense in depth against internal error */
+        if (filesResult.isFailure()) {
+            return (0, ts_utils_1.fail)(filesResult.message);
+        }
+        const { files, directory } = filesResult.value;
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('extracting-files', 100, `Extracted ${files.length} files`);
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('extracting-files', 100, 'ZIP loading complete');
+        return (0, ts_utils_1.succeed)({
+            manifest,
+            config,
+            files,
+            directory
+        });
+    }
+    /**
+     * Load manifest from ZIP using ZipFileTreeAccessors
+     * @param zipAccessors - ZIP file tree accessors
+     * @returns Result containing parsed manifest
+     */
+    _loadManifestFromAccessors(zipAccessors) {
+        const manifestResult = zipAccessors.getFileContents('manifest.json');
+        if (manifestResult.isFailure()) {
+            // Manifest is optional - return success with undefined
+            return (0, ts_utils_1.succeed)(undefined);
+        }
+        const parseResult = (0, zipArchiveFormat_1.parseZipArchiveManifest)(manifestResult.value);
+        if (parseResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Failed to parse manifest.json: ${parseResult.message}`);
+        }
+        return (0, ts_utils_1.succeed)(parseResult.value);
+    }
+    /**
+     * Load configuration from ZIP using ZipFileTreeAccessors
+     * @param zipAccessors - ZIP file tree accessors
+     * @param manifest - Parsed manifest (may be undefined)
+     * @param options - Loading options
+     * @returns Result containing parsed configuration
+     */
+    _loadConfigurationFromAccessors(zipAccessors, manifest, options) {
+        // Check if manifest specifies a config file
+        const manifestSpecifiesConfig = (manifest === null || manifest === void 0 ? void 0 : manifest.config) !== undefined;
+        if (!manifestSpecifiesConfig) {
+            // If no config specified in manifest, config is optional
+            return (0, ts_utils_1.succeed)(undefined);
+        }
+        // Get the config path from the manifest
+        const configPath = manifest.config.archivePath;
+        return zipAccessors
+            .getFileContents(configPath)
+            .withErrorFormat(() => `Manifest specifies config file at '${configPath}' but it was not found in archive`)
+            .onSuccess((configContent) => (0, zipArchiveFormat_1.parseZipArchiveConfiguration)(configContent))
+            .withErrorFormat((e) => `Failed to parse config file '${configPath}': ${e}`);
+    }
+    /**
+     * Extract files and directory structure from ZIP
+     * @param zipAccessors - ZIP file tree accessors
+     * @param onProgress - Optional progress callback
+     * @returns Result containing files and directory structure
+     */
+    async _extractFilesFromAccessors(zipAccessors, onProgress) {
+        try {
+            const files = [];
+            const directories = new Map();
+            // Get all children from root
+            const rootChildrenResult = zipAccessors.getChildren('/');
+            /* c8 ignore next 3 - defense in depth against internal error */
+            if (rootChildrenResult.isFailure()) {
+                return (0, ts_utils_1.fail)(`Failed to read ZIP contents: ${rootChildrenResult.message}`);
+            }
+            // Process all items recursively
+            await this._processFileTreeItems(zipAccessors, '/', rootChildrenResult.value, files, directories, onProgress);
+            // Build directory structure
+            const directory = this._buildDirectoryStructure(files, directories);
+            return (0, ts_utils_1.succeed)({ files, directory });
+            /* c8 ignore next 3 - defense in depth against internal error */
+        }
+        catch (error) {
+            return (0, ts_utils_1.fail)(`Failed to extract files: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Recursively process file tree items
+     * @param zipAccessors - ZIP file tree accessors
+     * @param currentPath - Current directory path
+     * @param items - Items to process
+     * @param files - Files collection
+     * @param directories - Directories collection
+     * @param onProgress - Optional progress callback
+     * @param processed - Processing counter
+     */
+    async _processFileTreeItems(zipAccessors, currentPath, items, files, directories, onProgress, processed = { count: 0 }) {
+        for (const item of items) {
+            /* c8 ignore next 1 - defense in depth */
+            const itemPath = item.absolutePath.startsWith('/') ? item.absolutePath.substring(1) : item.absolutePath;
+            if (item.type === 'directory') {
+                // Track directory
+                if (!directories.has(itemPath)) {
+                    directories.set(itemPath, {
+                        name: item.name,
+                        files: [],
+                        subdirectories: []
+                    });
+                }
+                // Recursively process children
+                const childrenResult = zipAccessors.getChildren(item.absolutePath);
+                if (childrenResult.isSuccess()) {
+                    await this._processFileTreeItems(zipAccessors, item.absolutePath, childrenResult.value, files, directories, onProgress, processed);
+                }
+            }
+            else if (item.type === 'file') {
+                // Get file content
+                const contentResult = item.getRawContents();
+                const content = contentResult.orDefault('');
+                files.push({
+                    name: item.name,
+                    path: itemPath,
+                    content,
+                    type: this._getFileType(item.name)
+                });
+            }
+            processed.count++;
+            onProgress === null || onProgress === void 0 ? void 0 : onProgress('extracting-files', 0, `Processing ${itemPath}`);
+        }
+    }
+    /**
+     * Build directory structure from files
+     * @param files - Extracted files
+     * @param directories - Directories map
+     * @returns Root directory structure or null
+     */
+    _buildDirectoryStructure(files, directories) {
+        /* c8 ignore next 3 - should never happen with fflate */
+        if (files.length === 0) {
+            return undefined;
+        }
+        const rootDir = {
+            name: 'root',
+            files: [],
+            subdirectories: []
+        };
+        // Process files to build directory structure
+        for (const file of files) {
+            const pathParts = file.path.split('/').filter((part) => part.length > 0);
+            /* c8 ignore next 1 - defense in depth should never happen */
+            if (pathParts.length === 0)
+                continue;
+            // Ensure all parent directories exist
+            let currentDir = rootDir;
+            for (let i = 0; i < pathParts.length - 1; i++) {
+                const dirName = pathParts[i];
+                let foundDir = currentDir.subdirectories.find((d) => d.name === dirName);
+                if (!foundDir) {
+                    foundDir = {
+                        name: dirName,
+                        files: [],
+                        subdirectories: []
+                    };
+                    currentDir.subdirectories.push(foundDir);
+                }
+                currentDir = foundDir;
+            }
+            // Add file to its parent directory
+            currentDir.files.push(file);
+        }
+        return rootDir;
+    }
+    /**
+     * Get file MIME type based on extension
+     * @param filename - Filename
+     * @returns MIME type
+     */
+    _getFileType(filename) {
+        const ext = filename.toLowerCase().split('.').pop();
+        /* c8 ignore next 20 - no need to test every one */
+        switch (ext) {
+            case 'json':
+                return 'application/json';
+            case 'yaml':
+            case 'yml':
+                return 'application/yaml';
+            case 'xml':
+                return 'application/xml';
+            case 'txt':
+                return 'text/plain';
+            case 'md':
+                return 'text/markdown';
+            case 'js':
+                return 'application/javascript';
+            case 'ts':
+                return 'application/typescript';
+            default:
+                return 'application/octet-stream';
+        }
+    }
+}
+exports.ZipArchiveLoader = ZipArchiveLoader;
+//# sourceMappingURL=zipArchiveLoader.js.map

package/lib/test/unit/zip-archive/convert.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=convert.test.d.ts.map

package/lib/test/unit/zip-archive/json.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=json.test.d.ts.map

package/lib/test/unit/zip-archive/zipArchiveCreator.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=zipArchiveCreator.test.d.ts.map

package/lib/test/unit/zip-archive/zipArchiveFormat.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=zipArchiveFormat.test.d.ts.map

package/lib/test/unit/zip-archive/zipArchiveIdempotency.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=zipArchiveIdempotency.test.d.ts.map

package/lib/test/unit/zip-archive/zipArchiveLoader.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=zipArchiveLoader.test.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-res",
-  "version": "5.0.0-16",
+  "version": "5.0.0-18",
   "description": "Multi-dimensional Resource Runtime",
   "main": "lib/index.js",
   "types": "dist/ts-res.d.ts",
@@ -44,15 +44,16 @@
     "@rushstack/heft-node-rig": "~2.9.3",
     "@types/heft-jest": "1.0.6",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils-jest": "5.0.0-16",
-    "@fgv/ts-extras": "5.0.0-16"
+    "@fgv/ts-utils-jest": "5.0.0-18",
+    "@fgv/ts-extras": "5.0.0-18"
   },
   "dependencies": {
     "luxon": "^3.7.1",
-    "@fgv/ts-utils": "5.0.0-16",
-    "@fgv/ts-json-base": "5.0.0-16",
-    "@fgv/ts-bcp47": "5.0.0-16",
-    "@fgv/ts-json": "5.0.0-16"
+    "fflate": "~0.8.2",
+    "@fgv/ts-utils": "5.0.0-18",
+    "@fgv/ts-json-base": "5.0.0-18",
+    "@fgv/ts-json": "5.0.0-18",
+    "@fgv/ts-bcp47": "5.0.0-18"
   },
   "scripts": {
     "build": "heft build --clean",

package/src/index.ts

@@ -32,6 +32,7 @@ import * as Resources from './packlets/resources';
 import * as ResourceTypes from './packlets/resource-types';
 import * as Import from './packlets/import';
 import * as Runtime from './packlets/runtime';
+import * as ZipArchive from './packlets/zip-archive';
 
 export * from './packlets/common';
 
@@ -69,5 +70,6 @@ export {
   ResourceType,
   ResourceTypes,
   Resources,
-  Runtime
+  Runtime,
+  ZipArchive
 };

package/src/packlets/zip-archive/convert.ts

@@ -0,0 +1,121 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/* eslint-disable @rushstack/typedef-var */
+
+import { Validator, Validators, Converter, Converters } from '@fgv/ts-utils';
+import * as Json from './json';
+import { Model as ConfigModel, Convert as ConfigConvert } from '../config';
+
+/**
+ * Validator for ZIP archive input type
+ * @public
+ */
+export const zipArchiveInputType: Validator<'file' | 'directory'> = Validators.enumeratedValue([
+  'file',
+  'directory'
+] as const);
+
+/**
+ * Validator for ZIP archive config type
+ * @public
+ */
+export const zipArchiveConfigType: Validator<'file'> = Validators.enumeratedValue(['file'] as const);
+
+/**
+ * Validator for ZIP archive input information
+ * @public
+ */
+export const zipArchiveInputInfo: Validator<Json.IZipArchiveInputInfo> =
+  Validators.object<Json.IZipArchiveInputInfo>({
+    type: zipArchiveInputType,
+    originalPath: Validators.string,
+    archivePath: Validators.string
+  });
+
+/**
+ * Validator for ZIP archive config information
+ * @public
+ */
+export const zipArchiveConfigInfo: Validator<Json.IZipArchiveConfigInfo> =
+  Validators.object<Json.IZipArchiveConfigInfo>({
+    type: zipArchiveConfigType,
+    originalPath: Validators.string,
+    archivePath: Validators.string
+  });
+
+/**
+ * Validator for ZIP archive manifest
+ * Compatible with existing tools from ts-res-browser-cli
+ * @public
+ */
+export const zipArchiveManifest: Validator<Json.IZipArchiveManifest> =
+  Validators.object<Json.IZipArchiveManifest>({
+    timestamp: Validators.string,
+    input: zipArchiveInputInfo.optional(),
+    config: zipArchiveConfigInfo.optional()
+  });
+
+/**
+ * Validator for MIME type strings
+ * @public
+ */
+export const mimeType: Validator<string> = Validators.string;
+
+/**
+ * Converter for imported file
+ * @public
+ */
+export const importedFile: Converter<Json.IImportedFile> = Converters.strictObject<Json.IImportedFile>({
+  name: Converters.string,
+  path: Converters.string,
+  content: Converters.string,
+  type: Converters.string // MIME type as string
+});
+
+/**
+ * Converter for imported directory structure (recursive)
+ * Note: Uses Converter pattern because Validators don't support recursion with self parameter
+ * @public
+ */
+export const importedDirectory: Converter<Json.IImportedDirectory> = Converters.generic<
+  Json.IImportedDirectory,
+  unknown
+>((from: unknown, self: Converter<Json.IImportedDirectory, unknown>, context?: unknown) => {
+  return Converters.strictObject<Json.IImportedDirectory>({
+    name: Converters.string,
+    files: Converters.arrayOf(importedFile),
+    subdirectories: Converters.arrayOf(self)
+  }).convert(from, context);
+});
+
+/**
+ * Validator for system configuration (delegates to config packlet)
+ * This validates that the parsed JSON conforms to the system configuration schema
+ * @public
+ */
+export const systemConfiguration: Validator<ConfigModel.ISystemConfiguration> = Validators.isA(
+  'system configuration',
+  (value: unknown): value is ConfigModel.ISystemConfiguration => {
+    return ConfigConvert.systemConfiguration.convert(value).isSuccess();
+  }
+);

package/src/packlets/zip-archive/index.ts

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * ZIP archive functionality for ts-res source file archives
+ *
+ * This packlet provides consolidated ZIP archive creation and loading functionality
+ * for source files, compatible with existing tools while using fflate for
+ * universal browser compatibility.
+ *
+ * @remarks
+ * ZIP archives contain source files for resource ingestion with directory
+ * structure preserved and optional validation but no processing or transformation.
+ * This is distinct from ZIP bundles which contain processed resource output.
+ *
+ * @packageDocumentation
+ */
+
+import * as Json from './json';
+import * as Convert from './convert';
+
+// Namespaces
+export { Json, Convert };
+
+// Core classes
+export { ZipArchiveCreator } from './zipArchiveCreator';
+export { ZipArchiveLoader } from './zipArchiveLoader';
+
+// Types and interfaces
+export type {
+  IZipArchivePathOptions,
+  IZipArchiveFileTreeOptions,
+  ZipArchiveOptions,
+  IZipArchiveResult,
+  IZipArchiveManifest,
+  IZipArchiveLoadOptions,
+  IZipArchiveLoadResult,
+  IImportedFile,
+  IImportedDirectory,
+  ZipArchiveProgressCallback
+} from './types';
+
+// Format utilities
+export {
+  createZipArchiveManifest,
+  parseZipArchiveManifest,
+  validateZipArchiveManifest,
+  parseZipArchiveConfiguration,
+  generateZipArchiveFilename,
+  normalizePath,
+  getDirectoryName,
+  sanitizeFilename,
+  isZipFile
+} from './zipArchiveFormat';
+
+// Constants
+export { ZipArchiveConstants } from './types';

package/src/packlets/zip-archive/json.ts

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * JSON representation of ZIP archive input information
+ * @public
+ */
+export interface IZipArchiveInputInfo {
+  /** Type of input (file or directory) */
+  type: 'file' | 'directory';
+  /** Original file/directory path */
+  originalPath: string;
+  /** Path within the archive (e.g., "input/mydir") */
+  archivePath: string;
+}
+
+/**
+ * JSON representation of ZIP archive config information
+ * @public
+ */
+export interface IZipArchiveConfigInfo {
+  /** Type of config (always 'file') */
+  type: 'file';
+  /** Original config file path */
+  originalPath: string;
+  /** Path within the archive (e.g., "config.json") */
+  archivePath: string;
+}
+
+/**
+ * JSON representation of a ZIP archive manifest
+ * Compatible with existing tools from ts-res-browser-cli
+ * @public
+ */
+export interface IZipArchiveManifest {
+  /** Archive creation timestamp */
+  timestamp: string;
+
+  /** Optional input source information */
+  input?: IZipArchiveInputInfo;
+
+  /** Optional configuration file information */
+  config?: IZipArchiveConfigInfo;
+}
+
+/**
+ * JSON representation of an imported file
+ * @public
+ */
+export interface IImportedFile {
+  /** File name */
+  name: string;
+  /** Full path within archive */
+  path: string;
+  /** File content as string */
+  content: string;
+  /** MIME type */
+  type: string;
+}
+
+/**
+ * JSON representation of an imported directory structure
+ * @public
+ */
+export interface IImportedDirectory {
+  /** Directory name */
+  name: string;
+  /** Files in this directory */
+  files: IImportedFile[];
+  /** Subdirectories */
+  subdirectories: IImportedDirectory[];
+}