@interopio/desktop-cli/README.md

io.Connect Desktop Seed Repository CLI Tools

# io.Connect Desktop CLI Tools

A comprehensive command-line tool for managing io.Connect Desktop Seed Repositories. This CLI provides tools for component management, license validation, customization application, and application packaging.

## Features

- **Component Management**: Install, update, and manage io.Connect Desktop components with full version control
- **License Validation**: Validate licenses and check component access permissions with JWT support
- **Modifications System**: Apply customizations and overrides to components without modifying source files, with extensible component abstraction for multiple component types
- **Package Builder**: Create distribution packages for multiple platforms (Windows, macOS, Linux)
- **Setup Automation**: Automated repository initialization and configuration with interactive prompts
- **Validation Tools**: Comprehensive validation of setup, licenses, and configurations
- **Cross-Platform Support**: Full compatibility across Windows, macOS, and Linux environments
- **TypeScript Support**: Complete TypeScript definitions and development experience

## Prerequisites

- Node.js version `>=18.0.0` (LTS recommended)
- Valid io.Connect Desktop license
- Git for version control
- **electron-builder** `^24.0.0 || ^25.0.0` (required for packaging)

## Installation

When using the CLI in your io.Connect Desktop project:

```bash
# Install the CLI
npm install @interopio/desktop-cli

# Install electron-builder (required for packaging)
npm install --save-dev electron-builder@^24.0.0

# Initialize your project
npx iocd setup
```

## Quick Start

```bash
# 0. Configure storage (optional - HTTP is default)
export IOCD_STORAGE_TYPE=http

# 1. Initialize a new seed repository
iocd setup

# 2. Show current configuration
iocd config show

# 3. View available components
iocd component all

# 4. Add required components
iocd component add iocd

# 5. Start io.Connect Desktop
iocd start

# 6. Package for distribution (automatically applies modifications)
iocd package           # Current platform
iocd package --platform win32  # Windows
iocd package --platform darwin # macOS
iocd package --platform linux  # Linux
```
```
```

## Usage

### Basic Commands

```bash
# Show help
iocd --help

# Initialize seed repository
iocd setup

# Show current configuration
iocd config show

# Initialize configuration file
iocd config init

# Start io.Connect Desktop
iocd start

# Start in development mode
iocd start --dev

# Validate system and licenses
iocd validate
```

### Component Management

```bash
# List installed components
iocd component list

# Show all available components  
iocd component all

# Add components (uses latest version from registry)
iocd component add iocd
iocd component add bbg-v2 teams-adapter excel-adapter

# Remove a component
iocd component remove teams-adapter

# Install all components from configuration
iocd component install

# Component cache management
iocd component cache clear   # Clear component cache
iocd component cache info    # Show cache information
```

### License Management

```bash
# Validate current license
iocd license validate

# Show license information
iocd license info

# Check component access permissions
iocd license check-components
```

### Package & Distribution

**Note**: Modifications are automatically applied during packaging.

```bash
# Package for current platform
iocd package

# Package for specific platform
iocd package --platform win32
iocd package --platform darwin  
iocd package --platform linux

# Package to custom output directory
iocd package --output ./my-dist

# Package directory only (no archive)
iocd package --dir
```

**How it works**: The `iocd package` command:

1. Applies any modifications from the `modifications/` directory
2. Validates licenses and components
3. Uses your `package.json` build configuration
4. Calls electron-builder with the appropriate settings
5. Creates distributable packages in the output directory

**Requirements**:

- electron-builder must be installed as a peer dependency
- Build configuration must be present in `package.json`
- All required components must be installed

### Modifications System

```bash
# Apply modifications to components
iocd modifications apply

# Apply modifications for specific component
iocd modifications apply --component iocd

# Validate modification sources
iocd modifications validate
```

### Validation & Maintenance

```bash
# Run comprehensive validation
iocd validate

# Clean build artifacts
iocd clean

# Clean everything including components
iocd clean --all

# Clean only components
iocd clean --components

# Get platform information
iocd platform info
```cmd
iocd clean --components
```


### Auto-Created Directories

The following directories are created automatically by the CLI during setup and operation:

- `components/` - Downloaded io.Connect Desktop components
- `modifications/` - Component customizations (created when modifications are applied)
- `.iocd-cache/` - Component download cache

> **Note**: The `components/`, `modifications/`, and `.iocd-cache/` directories should not be committed to source control in client projects.

## Source Control Best Practices

### For CLI Development

The CLI project itself does not include `components/` or `modifications/` directories in source control, as these are auto-generated during setup and operation.

### For Client Projects

When using the CLI in your projects:

1. **Copy `.gitignore` template**: Use `examples/.gitignore.template` as a starting point for your project's `.gitignore`
2. **Exclude auto-generated directories**: Never commit `components/` or `modifications/` directories
3. **License files**: Consider whether to commit `license.json` (exclude if it contains sensitive information)
4. **Build outputs**: Always exclude compiled/built assets

### Directory Structure Best Practices

```text
your-project/
├── src/                     # Your source code
│   ├── icon.ico            # Windows app icon
│   ├── icon.icns           # macOS app icon
│   └── icon.png            # Linux app icon
├── package.json            # With build configuration
├── license.json            # Your io.Connect license
├── .gitignore             # Using provided template
├── components/            # AUTO-GENERATED (excluded from git)
├── modifications/         # AUTO-GENERATED (excluded from git)
└── dist/                  # Build output (excluded from git)
```

## Configuration

### Build Configuration (package.json)

Configure electron-builder in your project's `package.json` for packaging:

```json
{
  "name": "your-iocd-app",
  "version": "1.0.0",
  "main": "components/iocd/main.js",
  "build": {
    "appId": "io.interop.desktop.yourapp",
    "productName": "Your io.Connect Desktop App",
    "directories": {
      "output": "dist",
      "buildResources": "build"
    },
    "files": [
      "components/**/*",
      "modifications/**/*",
      "license.json",
      "!components/**/*.map",
      "!**/node_modules/**/*"
    ],
    "extraFiles": [
      {
        "from": "components/iocd/resources",
        "to": "resources",
        "filter": ["**/*"]
      }
    ],
    "win": {
      "target": "nsis",
      "icon": "build/icon.ico"
    },
    "mac": {
      "target": "dmg",
      "icon": "build/icon.icns"
    },
    "linux": {
      "target": "AppImage",
      "icon": "build/icon.png"
    },
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true
    }
  }
}
```

### License Configuration

Place your `license.json` file in the project root:

```json
{
  "id": "your-license-id",
  "type": "production",
  "expiresAt": "2025-12-31T23:59:59Z",
  "features": ["*"],
  "allowedComponents": ["*"],
  "organization": "Your Organization"
}
```

### Storage Configuration

The CLI supports multiple storage backends for downloading components with built-in component definitions:

#### Configuration File (Recommended)

Create a `.iocdrc` configuration file for flexible, JSON-based configuration:

```bash
iocd config init  # Generate sample configuration
```

Example `.iocdrc`:

```json
{
  "http": {
    "baseUrl": "http://localhost:8080",
    "timeout": 300000,
    "headers": {
      "Authorization": "Bearer YOUR_TOKEN"
    }
  },
  "settings": {
    "defaultStorage": "http",
    "debug": false,
    "useCache": true,
    "cacheDirectory": ".iocd-cache"
  }
}
```

**✨ Components are now built-in!** No manual component configuration required.
Available components: `iocd`, `bbg-v2`, `teams-adapter`, `excel-adapter`

#### Environment Variables

```bash
# Storage type (defaults to http)
export IOCD_STORAGE_TYPE=http

# HTTP storage settings
export IOCD_HTTP_BASE_URL=http://localhost:8080
export IOCD_HTTP_TIMEOUT=300000

# GitHub storage settings (alternative)
export IOCD_STORAGE_TYPE=github
export GITHUB_TOKEN=your_token_here

# Cache settings
export IOCD_USE_CACHE=true
export IOCD_CACHE_DIR=.iocd-cache

# Debug mode
export IOCD_DEBUG=true
```

## Modifications System Details

The modifications system allows you to customize components without directly editing source files. You can now explicitly apply or validate modifications at any time with:

```bash
iocd modifications apply                 # Apply all component modifications
iocd modifications apply --component iocd # Apply only IOCD component mods
iocd modifications validate              # Validate modification sources
```

Modifications are also automatically processed during `iocd setup` (unless `--skip-modifications`) and before packaging (`iocd package`).

### JSON Configuration Merging

The CLI supports intelligent JSON configuration merging during packaging. This allows you to override or extend configuration files without completely replacing them:

```text
modifications/
└── iocd/
    └── config/
        ├── system.merge.json        # Merges with system.json
        ├── logger.merge.json        # Merges with logger.json
        └── apps.merge.json          # Merges with apps.json
```

**How it works:**

1. During packaging, `.merge.json` files are automatically detected
2. They are merged with their corresponding base `.json` files using sophisticated object merging
3. The base file is updated with the merged result
4. The `.merge.json` file is removed after successful merge

**Example:**

Base `system.json`:

```json
{
  "region": "DEMO",
  "gw": {
    "configuration": {
      "port": 8385
    }
  }
}
```

Override `system.merge.json`:

```json
{
  "region": "PRODUCTION", 
  "gw": {
    "configuration": {
      "authentication": {
        "available": ["windows", "basic"]
      }
    }
  }
}
```

**Result** (merged `system.json`):

```json
{
  "region": "PRODUCTION",
  "gw": {
    "configuration": {
      "port": 8385,
      "authentication": {
        "available": ["windows", "basic"]
      }
    }
  }
}
```

### File Replacement

```text
modifications/
└── iocd/
    ├── config/
    │   └── system.json              # Replaces components/iocd/config/system.json
    ├── assets/
    │   ├── logo.png              # Replaces components/iocd/assets/logo.png
    │   └── themes/
    │       └── custom.css        # Replaces components/iocd/assets/themes/custom.css
    └── splash/
        └── index.html           # Replaces components/iocd/splash/index.html
```

#### Real-World Examples from Workspace

You can find working examples in your workspace folders:

**Assets Examples** (`./assets/`):

- `assets/launchpad/index.html` - Launchpad application UI
- `assets/components/index.html` - Components app interface  
- `assets/splash/` - Splash screen assets
- `assets/notifications/` - Notification system assets
- `assets/workspaces/` - Workspace management UI
- `assets/global-search/` - Global search functionality
- `assets/images/` - Application icons and branding

#### Customizing Assets

You can customize any of these assets by copying them to your modifications folder:

```bash
# Example: Customize the launchpad
mkdir -p modifications/iocd/launchpad
cp assets/launchpad/index.html modifications/iocd/launchpad/
# Edit modifications/iocd/launchpad/index.html with your changes

# Example: Replace application icons  
mkdir -p modifications/iocd/images
cp assets/images/your-custom-icon.png modifications/iocd/images/

# Example: Customize splash screen
mkdir -p modifications/iocd/splash
cp -r assets/splash/* modifications/iocd/splash/
# Modify splash screen assets in modifications/iocd/splash/
```

**Configuration Examples** (`./config/`):

- `config/system.json` - Main system configuration with Gateway settings
- `config/logger.json` - Logging configuration with appenders and levels
- `config/themes.json` - Theme definitions and styling
- `config/channels.json` - Inter-app communication channels
- `config/apps/` - Application definitions and metadata

#### Sample Configuration Files

**System Configuration Example** (based on `./config/system.json`):

```json
{
  "region": "INTEROP.IO",
  "env": "DEMO",
  "appStores": [
    {
      "type": "path",
      "details": {
        "path": "./config/apps"
      }
    },
    {
      "type": "path", 
      "details": {
        "path": "%IO_CD_USER_DATA_DIR%/apps"
      }
    }
  ],
  "gw": {
    "useBeta": true,
    "embedded": false,
    "configuration": {
      "port": 8385,
      "ip": "127.0.0.1",
      "authentication": {
        "available": ["basic"],
        "default": "basic"
      }
    }
  }
}
```

**Logger Configuration Example** (based on `./config/logger.json`):

```json
{
  "appenders": {
    "out": {
      "type": "stdout"
    },
    "app": {
      "type": "file",
      "filename": "%GLUE-USER-DATA%/logs/application.log",
      "maxLogSize": 10485760,
      "backups": 5,
      "keepFileExt": true,
      "compress": true
    },
    "applications": {
      "type": "multiFile",
      "base": "%GLUE-USER-DATA%/logs/applications/",
      "property": "applicationName",
      "extension": ".log",
      "maxLogSize": 10485760,
      "backups": 10
    }
  }
}
```

### File Deletion

```text
modifications/
└── iocd/
    └── unwanted-file.js.delete   # Deletes components/iocd/unwanted-file.js
```

### Directory Replacement

You can replace an entire directory by mirroring it. The CLI will first delete the target directory then copy your version:

```text
modifications/
└── iocd/
  └── themes/                   # Replaces entire components/iocd/themes/ directory
    ├── custom.css
    └── assets/
      └── bg.jpg
```

To delete (remove) a directory without replacing it, create a marker:

```text
modifications/
└── iocd/
  └── temp-folder.delete        # Deletes components/iocd/temp-folder/ (directory marker)
```

To delete an individual file:

```text
modifications/iocd/config/old-config.json.delete
```

All files and directories in the modifications folder directly mirror the component structure. There are no reserved directories - everything is treated as a direct path override or delete marker.

## NPM Scripts

All CLI commands are also available as npm scripts:

```bash
# Setup and start
npm run setup
npm start
npm run start:dev
npm run start:debug

# Development
npm run dev
npm run watch
npm run build
npm run clean

# Component management
npm run component:install
npm run component:add
npm run component:remove
npm run component:list
npm run component:all

# Modifications
npm run modifications:apply
npm run modifications:validate

# License management
npm run license:validate
npm run license:info
npm run license:check-components

# Package and distribution
npm run package
npm run package:win
npm run package:mac
npm run package:linux
npm run package:dir

# Testing and validation
npm test
npm run test:watch
npm run test:coverage
npm run validate

# Debug modes
npm run debug:all
npm run debug:setup
npm run debug:components
npm run debug:package
npm run debug:validate
```

## Development

### Building

```bash
# Clean build
npm run clean && npm run build

# Development build with watch
npm run watch

# Run in development mode
npm run dev
```

### Testing

```bash
# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Type checking
npx tsc --noEmit
```

## Troubleshooting

### Common Issues

#### License validation fails

- Ensure `license.json` is present in the project root
- Verify license format and expiration date
- Check component permissions in license

#### Component installation fails

- Verify network connectivity
- Check license permissions for the component
- Ensure sufficient disk space

#### Modifications not applied

- Modifications are automatically applied during `iocd package`
- Ensure modification files are in correct directory structure
- Check file permissions
- Enable debug mode: `DEBUG=iocd:* iocd package`

#### Package creation fails

- Ensure all components are installed (`iocd component list`)
- Verify license is valid for packaging
- Check available disk space in output directory

### Getting Help

- **Command-line help**: Run commands with `--help` flag for detailed usage information

  ```bash
  iocd --help              # General help
  iocd setup --help        # Setup command help
  iocd component --help    # Component management help
  iocd config --help       # Configuration help
  ```

- **Configuration overview**: Use `iocd config show` to see current configuration
- **System validation**: Use `iocd validate` to check overall system health and configuration
- **Debug mode**: Enable verbose output with `DEBUG=* iocd <command>` for troubleshooting
- **Workspace examples**: Reference the `./assets/` and `./config/` folders for real-world examples
- **Version history**: Review the [CHANGELOG.md](./CHANGELOG.md) for version updates and features

## License

This project is licensed under the ISC License. See the LICENSE file for details.

---

For more information about io.Connect Desktop 10 and the Seed Repository approach, visit the [official documentation](https://docs.interop.io).