A configurable CLI tool that scans folders, categorizes and organizes files by type and context, enforces naming conventions (e.g., lowercase kebab case), moves and renames files, generates a manifest, and logs all actions for full auditability—ensuring a clean, consistent, and traceable directory structure.

• 🔍 Smart File Scanning: Automatically scans directories and categorizes files by type
• 📁 File Organization: Moves files into organized folders based on their type
• ✏️ Naming Convention Enforcement: Automatically renames files to follow consistent naming patterns (kebab-case, snake_case, camelCase, or PascalCase)
• 📋 Manifest Generation: Creates detailed JSON and Markdown manifests of all operations
• 📝 Comprehensive Logging: Full audit trail of all actions with configurable log levels
• 🎯 Configurable Rules: Customize file categories, patterns, and organization rules
• 🔒 Dry Run Mode: Preview changes before applying them
• 🎨 Colorized Output: Easy-to-read console output with colors
• 🛡️ Type Safety: Built with TypeScript using strict mode and type-safe enums
• ✅ Production Ready: 99.66% test coverage, zero lint errors, comprehensive quality gates

npm install -g orderly

Or use directly with npx:

npx orderly organize

1. Initialize a configuration file:

   orderly init

2. Scan a directory to see what would be organized:

   orderly scan ./my-folder

3. Organize files (dry run first):

   orderly organize ./my-folder --dry-run

4. Apply the organization:

   orderly organize ./my-folder

Organize files in the specified directory (defaults to current directory).

Options:

• -c, --config <path> - Path to config file
• -d, --dry-run - Preview changes without applying them
• --no-manifest - Skip manifest generation
• -l, --log-level <level> - Set log level (debug, info, warn, error)
• -o, --output <path> - Output directory for organized files

Examples:

# Organize current directory with dry run
orderly organize --dry-run

# Organize specific directory with custom config
orderly organize ./downloads -c ./my-config.yml

# Organize and output to a different location
orderly organize ./messy-folder -o ./organized-folder

Scan a directory and display what would be organized without making changes.

Options:

• -c, --config <path> - Path to config file
• -l, --log-level <level> - Set log level

Example:

orderly scan ./downloads

Initialize a new configuration file.

Options:

• -f, --format <format> - Config file format (json or yaml, default: yaml)

Example:

orderly init --format json

Create a .orderly.yml (or .orderly.yaml or orderly.config.json) file in your project root:

categories:
  - name: images
    extensions:
      - .jpg
      - .jpeg
      - .png
      - .gif
      - .svg
      - .webp
    targetFolder: images
  - name: documents
    extensions:
      - .pdf
      - .doc
      - .docx
      - .txt
      - .md
    targetFolder: documents
  - name: code
    extensions:
      - .js
      - .ts
      - .py
      - .java
    targetFolder: code

namingConvention:
  type: kebab-case  # Options: kebab-case, snake_case, camelCase, PascalCase
  lowercase: true

excludePatterns:
  - node_modules/**
  - .git/**
  - dist/**
  - build/**

includeHidden: false
dryRun: false
generateManifest: true
logLevel: info

Define file categories based on extensions and optional patterns.

• name: Category name
• extensions: List of file extensions (including the dot)
• patterns: Optional glob patterns for additional matching
• targetFolder: Folder name where files should be moved

Define how files should be renamed.

• type: Naming convention type
  • kebab-case: my-file-name.txt
  • snake_case: my_file_name.txt
  • camelCase: myFileName.txt
  • PascalCase: MyFileName.txt
• lowercase: Force lowercase (only applies to kebab-case and snake_case)

Glob patterns for files/folders to exclude from scanning.

Whether to include hidden files (starting with .).

Preview changes without applying them.

Generate JSON and Markdown manifests of all operations.

Logging verbosity: debug, info, warn, or error.

When organization completes, Orderly generates two manifest files in the .orderly directory:

1. manifest.json: Machine-readable JSON format
2. manifest.md: Human-readable Markdown format

These files contain:

• Timestamp of operation
• Total number of operations
• Success/failure counts
• Detailed list of all file operations
• Any errors encountered

All operations are logged to .orderly/orderly.log for full auditability.

# Preview what would happen
orderly scan ~/Downloads

# Apply organization
orderly organize ~/Downloads

Create .orderly.yml:

categories:
  - name: photos
    extensions: [.jpg, .jpeg, .png]
    targetFolder: Photos
  - name: videos
    extensions: [.mp4, .mov]
    targetFolder: Videos

namingConvention:
  type: kebab-case
  lowercase: true

Then run:

orderly organize ./media-files

orderly organize ./source-folder -o ./organized-output

• Node.js ≥ 18.0.0
• npm ≥ 9.0.0

# Clone the repository
git clone https://github.com/Coderrob/orderly.git
cd orderly

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm run dev -- organize ./test-folder

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode (development)
npm run test:watch

# CI/CD mode
npm run test:ci

Test Results: All 157 tests passing across 13 test suites with 99.66% code coverage.

This project maintains exceptional code quality through automated checks and standards:

# Run linting
npm run lint

# Auto-fix lint issues
npm run lint:fix

# Check code formatting
npm run format:check

# Format code
npm run format

# Type checking
npm run typecheck

# Check code duplication (< 1%)
npm run duplication

# Run static analysis
npm run sonar

# Full quality check
npm run verify

# Quick quality fixes
npm run quality:fix

• Type-Safe Enums: All string literals replaced with type-safe enums
  • ConfigFormat: JSON, YAML configuration formats
  • NamingConventionType: kebab-case, snake_case, camelCase, PascalCase
  • FileOperationType: move, rename, move-rename operations
  • OperationStatus: success, failed status tracking
• Defensive Testing: Comprehensive test assertions using toHaveBeenCalledTimes() and toHaveBeenNthCalledWith()
• Module Consistency: Proper Node.js module imports with node: prefix for built-in modules
• Mock Integrity: All tests use proper mocking patterns with jest.mock() and jest.mocked()

Comprehensive documentation is available:

• TESTING_STANDARDS.md - Testing guidelines and best practices
• CODE_QUALITY_STANDARDS.md - SOLID principles and clean code
• QUALITY_GATE.md - Automated quality checks and gates
• ARCHITECTURE.md - System architecture
• CONTRIBUTING.md - How to contribute

• ✅ Type-Safe Enums: Replaced all string literals with TypeScript enums for compile-time safety
  • Configuration format validation (JSON/YAML)
  • Naming convention types (kebab-case, snake_case, camelCase, PascalCase)
  • File operation types (move, rename, move-rename)
  • Operation status tracking (success, failed)
• ✅ Enhanced Test Quality: Upgraded all unit tests with defensive assertions
  • Precise call count verification with toHaveBeenCalledTimes()
  • Argument validation with toHaveBeenNthCalledWith()
  • Proper module mocking with node: prefix consistency
• ✅ Bug Fixes: Resolved critical module import mismatches and test mocking issues
• ✅ Quality Gates: Achieved 99.66% test coverage with 157 passing tests
• ✅ Zero Defects: No TypeScript errors, no lint errors, no code duplication

Apache-2.0