Enhance Bundle Upload with Pre-Upload Validation and Auto-Activation

[Mishael-2584]

Component

• formulus (React Native mobile app)

• formulus-formplayer (React web app)

• synkronus (Go backend server)

• synkronus-cli (Command-line utility)

• Documentation

• Other (please specify)

Feature Description

Enhance the synk app-bundle upload command with comprehensive pre-upload validation, auto-activation capability, and improved user experience. This feature will:

1. Validate bundle structure before upload - Check for required files, valid JSON, and correct structure to catch errors early
2. Auto-activate uploaded versions - Add --activate flag to automatically activate the uploaded bundle version
3. Provide verbose output - Add --verbose flag to show detailed bundle information (size, file count, forms, renderers, manifest)
4. Improve error messages - Use color-coded output (green/yellow/red) for better visibility and clearer error reporting

This enhancement will improve developer experience by catching validation errors before upload, reducing manual steps, and providing better feedback during the bundle upload process.

Problem Statement

The current synk app-bundle upload command provides a solid foundation for bundle management. This enhancement would improve the developer experience by adding client-side validation and workflow optimizations:

• Early validation feedback: Currently, validation occurs server-side after upload. Adding client-side validation would provide immediate feedback, helping developers catch issues before upload and reducing the need for re-uploads
• Enhanced error messaging: Providing clearer, more actionable error messages during the upload process would help developers quickly identify and fix bundle issues
• Streamlined workflow: After upload, users currently need to run a separate synk app-bundle switch <version> command to activate the new version. An optional auto-activation flag would streamline this common workflow
• Better visibility: Adding the ability to view bundle statistics (file count, forms, renderers) would help users understand bundle contents before and after upload
• Faster iteration: Detecting bundle structure issues (missing app/index.html, incomplete forms, missing renderers) before upload would enable faster development cycles

Use Cases:

• Developers uploading app bundles would benefit from immediate feedback on bundle structure validity
• Administrators could upload and activate bundles in a single command for improved efficiency
• Users would gain visibility into bundle statistics (file count, forms, renderers) before committing to upload
• CI/CD pipelines would benefit from clear validation errors that fail fast, improving pipeline efficiency

Use Cases:

• Developers uploading app bundles want immediate feedback if their bundle structure is invalid
• Administrators want to upload and activate bundles in a single command
• Users want to see bundle statistics (file count, forms, renderers) before committing to upload
• CI/CD pipelines need clear validation errors to fail fast

Proposed Solution

1. Pre-Upload Validation

Create a validation package (pkg/validation/bundle.go) that validates bundle structure before upload:

• Structure Validation: Ensure only app/, forms/, renderers/ top-level directories exist
• Required Files: Check for app/index.html and required form files (forms/{formName}/schema.json, forms/{formName}/ui.json)
• JSON Validation: Validate JSON syntax in all schema and UI files
• Renderer References: Ensure all referenced renderers exist (either as custom renderers or built-in renderers)
• Match Server Logic: Validation logic should mirror synkronus/pkg/appbundle/validation.go exactly

2. Auto-Activation Flag

Add --activate (or -a) flag to automatically activate the uploaded version:

synk app-bundle upload bundle.zip --activate

This eliminates the need for a separate switch command after upload.

3. Verbose Output Flag

Add --verbose (or -v) flag to show detailed bundle information:

• Bundle size
• Total file count
• Number of forms
• Number of renderers
• Full manifest after upload

4. Skip Validation Option

Add --skip-validation flag (not recommended) for edge cases, with a warning message when used.

Example Usage

Basic upload (with automatic validation):

$ synk app-bundle upload bundle.zip
Validating bundle structure...
✓ Bundle structure is valid
Uploading bundle...
✓ App bundle uploaded successfully!
Version: 20250102-123456

Upload with auto-activation:

$ synk app-bundle upload bundle.zip --activate
Validating bundle structure...
✓ Bundle structure is valid
Uploading bundle...
✓ App bundle uploaded successfully!
Version: 20250102-123456
Activating version 20250102-123456...
✓ Version 20250102-123456 activated successfully!

Upload with verbose output:

$ synk app-bundle upload bundle.zip --verbose
Validating bundle structure...
✓ Bundle structure is valid

Bundle Information:
  Size: 245678 bytes
  Files: 15
  Forms: 3
  Renderers: 2

Uploading bundle...
✓ App bundle uploaded successfully!
Version: 20250102-123456

Manifest:
  Version: 20250102-123456
  Hash: abc123def456...
  Files: 15

Validation error handling:

$ synk app-bundle upload invalid-bundle.zip
Validating bundle structure...
✗ Bundle validation failed: missing app/index.html

Features to Implement

1. Pre-Upload Validation

• Validate bundle structure (required directories: app/, forms/, renderers/)
• Check for required files (app/index.html, forms/{formName}/schema.json, forms/{formName}/ui.json)
• Validate JSON syntax in schema and UI files
• Validate renderer references (ensure referenced renderers exist)
• Match server-side validation logic exactly

2. Auto-Activation Flag

• --activate or -a flag to automatically activate uploaded version
• Eliminates need for separate switch command after upload

3. Verbose Output

• --verbose or -v flag to show:
  • Bundle size
  • File count
  • Form count
  • Renderer count
  • Full manifest after upload

4. Skip Validation Option

• --skip-validation flag (not recommended, for edge cases)
• Warning message when used

Expected Behavior

Basic Upload (with validation)

$ synk app-bundle upload bundle.zip
Validating bundle structure...
✓ Bundle structure is valid
Uploading bundle...
✓ App bundle uploaded successfully!
Version: 20250102-123456

Upload with Auto-Activation

$ synk app-bundle upload bundle.zip --activate
Validating bundle structure...
✓ Bundle structure is valid
Uploading bundle...
✓ App bundle uploaded successfully!
Version: 20250102-123456
Activating version 20250102-123456...
✓ Version 20250102-123456 activated successfully!

Upload with Verbose Output

$ synk app-bundle upload bundle.zip --verbose
Validating bundle structure...
✓ Bundle structure is valid

Bundle Information:
  Size: 245678 bytes
  Files: 15
  Forms: 3
  Renderers: 2

Uploading bundle...
✓ App bundle uploaded successfully!
Version: 20250102-123456

Manifest:
  Version: 20250102-123456
  Hash: abc123def456...
  Files: 15

Validation Errors

$ synk app-bundle upload invalid-bundle.zip
Validating bundle structure...
✗ Bundle validation failed: missing app/index.html

Acceptance Criteria

• Validation package created (pkg/validation/bundle.go)
• Validation matches server-side logic in synkronus/pkg/appbundle/validation.go
• All validation tests passing (13+ test cases)
• --activate flag implemented and working
• --verbose flag implemented and working
• --skip-validation flag implemented with warning
• Color-coded output (green for success, yellow for warnings, red for errors)
• README updated with new flags and examples
• No breaking changes (backward compatible)
• Works with fresh install (no hardcoded paths)

Technical Details

Validation Checks

1. Structure Validation

   • Only app/, forms/, renderers/ top-level directories allowed
   • app/index.html must exist

2. Form Validation

   • Each form directory must have both schema.json and ui.json
   • JSON files must be valid JSON
   • Form file paths must be forms/{formName}/schema.json or forms/{formName}/ui.json

3. Renderer Validation

   • Renderer files must be renderers/{rendererName}/renderer.jsx
   • Referenced renderers in schemas must exist (or be built-in)

4. Built-in Renderers

   • Standard JSONForms renderers (text, number, boolean, etc.)
   • Formulus custom controls (image, signature, audio, video, file, qrcode)

Testing

• Unit tests for validation package
• Integration test with real bundle
• Test with invalid bundles (missing files, invalid JSON, missing renderers)
• Test auto-activation flow
• Test verbose output
• Test skip-validation flag

Related Files

• synkronus-cli/internal/cmd/appbundle.go - Upload command
• synkronus/pkg/appbundle/validation.go - Server-side validation (reference)
• synkronus-cli/pkg/validation/bundle.go - New validation package (to be created)

Labels

• enhancement
• synkronus-cli

[Bahati308]

Thanks for the catch @Mishael-2584 ,