hosanna-tools

To use the tool

npm install -g @tantawowa/hosanna-tools

Note, if you are developing hosanna-tools, you will install the package locally.

npm install . -g # path to the hosanna-tools directory

Getting started

Ensure you have a version of node that is the same or higher than yml.ci, which is node 20 or higher at time of writing.

run npm install to install all dependencies

Install ts-node globally:

  npm install -g ts-node

Ensure you have hosanna compiler (hsc) installed globally. Tantawowa Ltd will provide you with the compiler.

Requirements

• Node.js 20.5.0 or higher
• Python installed
• *nix operating system (BSD, macOS, Unix, WSL)
• Visual Studio Code or any MS Language Server Protocol (LSP) supported editor (only VS Code is officially supported by Tantawowa Ltd.)

Note: Windows is not supported directly. Developers can use WSL on Windows to meet the requirements. For more information, refer to the WSL installation guide and the VS Code WSL guide.

Development Workflow

Editing code

1. Use vscode
2. Ensure you have installed the package locally

   npm install . -g # path to the hosanna-tools directory

3. Open this folder in vscode
4. Run Npm Watch
5. Open a javascript debugging terminal
6. Run the hosanna server in a terminal, with Javscript debugging (i.e. Javascript Debug Terminal)

Developer Process

Before checking in your changes, ensure the following steps are completed:

1. Run the linter: Ensure your code adheres to the project's coding standards by running the linter:

   npm run lint

2. Run tests: Verify that all tests pass to ensure your changes do not introduce regressions:

   npm test

3. Commit your changes: Once the linter and tests pass, commit your changes with a meaningful commit message.

Following these steps helps maintain code quality and stability across the project.

CLI: configure-hosanna-url

• purpose: Updates hosanna.json with a new Hosanna UI Git URL under the git-url key.
• usage:
  • hst configure-hosanna-url https://github.com/YourOrg/hosanna-ui.git
  • HOSANNA_UI_GIT_URL=https://github.com/YourOrg/hosanna-ui.git hst configure-hosanna-url
• behavior:
  • If no positional gitUrl is provided, the command falls back to the HOSANNA_UI_GIT_URL environment variable.
  • If neither is provided, it prints a message and leaves hosanna.json unchanged.
  • On success, it prints a sanitized URL (protocol + host + path) for logs.

Hosanna Tools CLI

Hosanna Tools is a comprehensive CLI toolset for the Hosanna framework that provides commands for development, building, deployment, and CI/CD operations.

CLI Command Groups

The CLI commands are organized into logical groups using colon-separated namespacing:

Run Commands (run:*) - Development Execution

• run:dev - Run dev processes: vite, generator watch, and optional debugger
• run:debugger - Start the command debugger WebSocket proxy

Roku Commands (roku:*) - Roku Deployment & Packaging

• roku:run - Deploy a Roku app to a device (supports .zip file or folder)
• roku:package - Package and sign a Roku channel using roku-deploy

Generate Commands (generate:*) - Code Generation

• generate - Generate structs and command handler maps
• generate:structs - Generate structs only for the specified files
• generate:clean - Clean generated files in the generated folder

Install Commands (install:*) - Setup & Installation

• install - Install the SDK by creating hosanna.json
• install:compiler - Install or update the Hosanna compiler (hsc)
• install:template - Create a new template app with the Hosanna SDK

CI Commands (ci:*) - Continuous Integration

• ci:extract-pkg-key - Extract signing key from an existing signed Roku package as base64
• ci:extract-config - Extract debug-flags JSON files as base64 environment variables
• ci:restore-flags - Restore debug-flags JSON files from base64 environment variables
• ci:configure-hosanna-url - Configure hosanna.json git-url from argument or environment

Environment Commands (env:*) - Environment Management

• env - Print environment information and run checks with auto-fix option
• env:prepare-gitignore - Ensure .gitignore contains required entries

Usage Examples

# Development workflow
hst run:dev                    # Start development server
hst generate --watch          # Generate code with file watching
hst roku:run --app-package myapp.zip  # Deploy to Roku device

# Building and packaging
hst roku:package --ip 192.168.1.10  # Package and deploy Roku app
hst generate:clean              # Clean generated files

# Setup and installation
hst install                     # Initialize Hosanna SDK
hst install:compiler           # Install Hosanna compiler
hst install:template           # Create new template app

# CI/CD operations
hst ci:extract-pkg-key myapp.pkg  # Extract signing key for CI
hst ci:extract-config           # Extract debug config for CI
hst ci:restore-flags           # Restore config from CI variables

# Environment management
hst env --fix                  # Check and fix environment issues
hst env:prepare-gitignore      # Update .gitignore

To debug

• Run the hosanna server in a terminal, with Javscript debugging (i.e. Javascript Debug Terminal)
• Run the hosanna tool in a terminal: breakpoint debugging will be available