@aldrs/packager

@aldrs/packager is a cross-platform CLI tool that analyzes a directory, generates a structured JSON representation of its contents, and creates ZIP archives accordingly. It supports advanced file filtering, intelligent ordering, and content segmentation based on user-defined size thresholds.

Version 2.0.0

Key Features

• Structured JSON Generation
  Recursively scans the target directory and creates a directory_structure.json file that describes each node with the following properties:

  • name: The display name (with numeric prefixes removed if present).
  • order: A numeric order extracted from any numeric prefix; for items without a prefix, a sequential number is assigned using Arabic-aware sorting at each directory level.
  • oldName: The original name of the file or folder.
  • path: The relative path from the package root.
  • type: One of file, folder, or attachments.
  • subFolderAndfiles: An array representing nested subdirectories and their contents.

• File Filtering & Validation

  • Only allowed audio and video files (determined by MIME types) are included.
  • Recognizes and includes attachments (e.g. PDF, DOC, DOCX, EPUB) as extra metadata.
  • Optionally enforces a “leaf-only” rule where only leaf directories may contain files.
  • Analyzes directories to distinguish between valid “subjects” (directories with audio/video files) and “categories” (nested structures containing subjects).

• Content Segmentation
  Automatically splits the package into multiple ZIP archives if the total size of files exceeds a user-specified maximum:

  • User-Defined Size Threshold: Must be between 50 MB and 1000 MB.
  • Segmentation Logic: Files are distributed across segments (while preserving directory structure) so that no single ZIP file exceeds the specified limit.
  • Validation: If any single file exceeds the maximum allowed size, the command fails.

• CLI & Interactive Modes

  • Interactive Mode:
    Running the command without arguments launches an interactive menu where the user can choose options such as processing mode, maximum ZIP size, target category, and root category order.
  • CLI Mode:
    Providing command-line arguments runs the tool non-interactively.
    Options:
    • -m, --mode <subjects|categories>: Processing mode (default: subjects).
    • -z, --maxZipSize <number>: Maximum overall ZIP file size in MB (must be between 50 and 1000). If the total file size exceeds this limit, segmentation is applied. If any single file exceeds this limit, the command fails.
    • -t, --targetCategory <string>: (Optional) Target category for upload.
    • -r, --rootCategoryOrder <string>: (Optional) Root category order value.
    • -h, --help: Display help information.

• Cross-Platform Compatibility
  Built on Node.js (>=18.0.0), @aldrs/packager works seamlessly on Windows, macOS, and Linux.

Installation

Install globally via npm:

npm install -g @aldrs/packager

This makes the aldrs-pack command available globally.

Usage

Interactive Mode (Default)

Run the command without arguments to launch the interactive menu:

aldrs-pack

In interactive mode, you will be prompted to choose the processing mode, specify the maximum ZIP size (between 50 MB and 1000 MB), and optionally set a target category and root order.

CLI Mode

You can also run the tool in CLI mode by providing command-line options:

aldrs-pack [options] [directory]

If [directory] is omitted, the current working directory is used.

Options

• -m, --mode <subjects|categories>
  Processing mode. Default is subjects.

• -z, --maxZipSize <number>
  Maximum overall ZIP file size in MB (must be between 50 and 1000).
  If the total file size exceeds this limit, the tool segments the content into multiple ZIP archives. If any single file exceeds this limit, the command fails.

• -t, --targetCategory <string>
  (Optional) Target category for upload.

• -r, --rootCategoryOrder <string>
  (Optional) Root category order value.

• -h, --help
  Display help information.

Examples

• Run in CLI Mode on a Specific Directory in Subjects Mode:

  aldrs-pack --mode subjects --maxZipSize 800 /path/to/directory

• Run in CLI Mode in Categories Mode with Default Size:

  aldrs-pack --mode categories /path/to/directory

Build and Test

• Build:
  Compile TypeScript to JavaScript:

  npm run build

• Test:
  Run the integration test suite using:

  npm run test

  The tests cover ordering, segmentation, attachment inclusion, CLI/interactive mode consistency, and validation of maxZipSize.

License

This project is licensed under the MIT License.