hosanna-tools

Documentation

• MCP debugger & UI tests — hst mcp:start, all MCP tools, commands by use case, examples, hst test:ui / hst test:record.
• docs/README.md — index of docs in this repo (MCP + source-map note).
• hosanna-ui (separate repo): docs/README.md for agentic debugging and links back to this README.

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

Hosanna source install modes

Client projects can switch between private Keygen source tarballs, an embedded copy, a shared local checkout, and the legacy git/local modes:

hst config source                                                        # show current mode and immutable install identity
hst config source keygen --sdk-version latest --install                  # newest valid private publication across all lanes
hst config source keygen --sdk-version v1.29.1 --install                 # pin an exact immutable production release
hst config source embedded --source-path ../hosanna-ui --install         # filtered, reproducible copy
hst config source shared --source-path ../hosanna-ui --install           # portable relative link for local development
hst config source git --install                                           # legacy git checkout
hst config source local                                                   # caller-provided LOCAL_SDK checkout

Keygen mode writes distribution: "keygen", flavour: "fullSource", and no platform list to hosanna.json. Bare latest means the newest valid published full-source release by Keygen publication time, whether it came from a nightly, manual, or tag run. @latest remains the stable-lane alias and @nightly remains the development-lane alias. Exact versions are immutable pins. The same HSC_LICENSE_KEY used by the compiler authorizes source installation; there is no separate Hosanna source-license environment variable.

Local shared, embedded, and local selections are private developer overrides. They do not rewrite hosanna.json: Git projects store the selection in worktree-specific Git metadata, so activating a local checkout cannot dirty the project or leak a machine path into a commit. hst config source and hst env check prominently report the active override, resolved checkout, and the committed distribution/version it temporarily supersedes. Running hst sdk:install or hst framework:update while an override is active preserves the local checkout. Select keygen or git with --install --replace-existing to clear the override and return to the committed source.

Use --replace-existing with --install when switching an existing project between modes. Replacement is refused for an unrecognized or modified source root; --force is required for a dirty git checkout. Embedded installs exclude repository/build/secret state, write a content-hash manifest, and never modify the source checkout. Shared installs validate the source and create a relative symlink. Granular flavours and platform subsets are deliberately rejected with NOT SUPPORTED YET — use flavour "fullSource".

Embedding as a library

Hosanna Tools can also be imported by app build chains. The CLI remains available as hst, but package imports are library-safe and do not parse CLI arguments or call process.exit during import. Public wrappers for process-oriented commands use no-exit mode where supported, so API callers receive structured results or thrown errors instead of forced process termination.

import { buildConfig, compiler, env, generate, roku, secrets } from '@tantawowa/hosanna-tools';

await generate.all({
  rootFolder: './src',
  generatedFolder: './src-generated',
  mode: 'runtime',
});

await buildConfig.resolve({
  env: 'dev',
  platform: 'roku',
  out: 'assets/meta/build-config.json',
});

await compiler.install({ version: '0.33.7' });
await roku.package({ env: 'prod', prebuild: 'npm run roku:build:prod' });

Common build-script replacements:

| CLI command | Programmatic API | | --- | --- | | npx hst generate:all --rootFolder ./src | await generate.all({ rootFolder: './src' }) | | npx hst generate:clean | await generate.clean() | | npx hst build-config:resolve --env dev --platform roku --out assets/meta/build-config.json | await buildConfig.resolve({ env: 'dev', platform: 'roku', out: 'assets/meta/build-config.json' }) | | npx hst compiler:install 0.33.7 | await compiler.install({ version: '0.33.7' }) | | npx hst roku:package --env prod --prebuild 'npm run roku:build:prod' | await roku.package({ env: 'prod', prebuild: 'npm run roku:build:prod' }) | | npx hst secrets:check | await secrets.check({ cwd: process.cwd() }) | | npx hst env check | await env.check({ cwd: process.cwd() }) |

Long-running APIs such as dev.run, debugger.start, mcp.start, test.record, and RASP capture-style workflows keep the same operational behavior as the corresponding CLI commands: they start services, attach to debuggers, or wait for user/session activity. mcp.start, dev.run, and test.ui are wired for programmatic no-exit behavior through the top-level API.

Getting started

Ensure you have Node.js 24.17.0.

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 24.17.0
• 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.

Releasing

See RELEASE.md for the full release process.

Quick reference:

npm run release -- patch   # 2.14.0 → 2.14.1
npm run release -- minor   # 2.14.0 → 2.15.0
npm run release -- major   # 2.14.0 → 3.0.0

For tokenless agent releases, dispatch Release Patch or Release Minor in GitHub Actions. Both wrappers invoke the OIDC-trusted release.yml workflow on main; agents do not need npm credentials.

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:

Development Commands

• run - Canonical cross-platform app launcher. Bare interactive runs show one destination picker; explicit platform options support web, Roku, iOS, Apple TV, Android, and Android TV launch targets.
• target:list - List launch targets for humans or agents, including web emulators, sims, and physical devices.
• dev:start - Run dev processes: vite, generator watch, and optional debugger
• debugger:start - Start the command debugger WebSocket proxy (only one debugger is needed for multiple apps; if the port is already in use, a friendly message is shown instead of crashing)

Examples:

hst run
hst run --last
hst run --platform web
hst run --platform roku --target emulator
hst run --platform ios --target emulator
hst run --platform android --target emulator
hst run --platform apple-tv --target emulator
hst run --platform android-tv --target emulator
hst run --platform ios --target sim --device "iPhone 17 Pro"
hst run --platform ios --target device --device "George iPhone" --no-logs
hst run --platform android --target sim --device "Pixel_8" --no-logs
hst run --platform android --target device --device "RF8M62694QT" --no-logs
hst run --platform android-tv --target sim --device "Television_1080p" --no-logs
hst run --platform apple-tv --target sim --device "Apple TV 4K"
hst run --platform roku --target device --device "Living Room"
hst run --platform roku --target device --device "Living Room" --replace
hst target:list --platform ios --target device --json
hst target:list --platform android --target sim --json
hst target:list --platform android-tv --target sim --json
hst target:list --platform apple-tv --target sim --json
hst target:list --form-factor tv --json

Bare hst run in an interactive terminal discovers runnable web previews, vendor simulators, and online physical devices, then presents one flat destination picker. The last selection is placed first, so pressing Enter repeats it; hst run --last skips discovery and immediately uses that remembered destination. The selection is stored in the user-level ~/.hosanna-tools/run.json, preserving existing defaults. Explicit commands remain deterministic, and non-interactive runs never open the picker.

--target emulator starts or reuses the shared Vite/debugger dev services for any platform and opens a profiled DOM runtime URL for interactive runs; use --device <preset-id> to override defaults such as iphone-15, pixel-8, apple-tv-4k, android-tv-1080p, or rokufhd, and use --no-open for server-only launches. --target sim launches the vendor virtual device for platforms that have one: Apple Simulator for iOS and Apple TV, Android Emulator for Android and Android TV. --target device launches or deploys to physical local hardware. web and browser remain accepted aliases for the web emulator; simulator and simulated remain accepted aliases for sim; emulated remains an accepted alias for the web emulator. Device/sim runs record the target and refuse to overwrite a recorded session or safe-to-kill occupied resource in non-interactive mode unless --replace is passed. Preferred run defaults live in .hosanna-tools/run.json, and preferred devices live in .hosanna-tools/devices.json or ~/.hosanna-tools/devices.json. Legacy .hs-devices.json files are still read for compatibility.

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

• roku:run - Deploy a Roku app to a device (supports .zip file or folder)
• roku:command - Send a Hosanna command to an installed channel through Roku ECP
• roku:package - Package and sign a Roku channel using roku-deploy
• roku:map-stack - Resolve Roku .brs stack traces, compile errors, and crash snippets to original TypeScript locations using .brs.map files

Send a command to the sideloaded dev channel (the default app ID):

hst roku:command clearRegistry --device 192.168.1.50
hst roku:command clearRegistry --device "Living Room" --yes

The device can also come from ROKU_IP or the preferred/default Roku in .hosanna-tools/devices.json. Destructive commands such as clearRegistry prompt for confirmation unless --yes is passed. Use --app-id for another installed channel and --dry-run to print the encoded ECP request without sending it:

hst roku:command clearRegistry --app-id 8518 --dry-run

Resolve pasted Roku output:

pbpaste | hst roku:map-stack --source-map-root platforms/roku/src

Resolve a saved crash report or a single line:

hst roku:map-stack --file crash.txt --source-map-root platforms/roku/src
hst roku:map-stack --text "file/line: pkg:/components/source_0.brs(7475)"

Supported inputs include file/line: pkg:/components/source_0.brs(7475), at ... (pkg:/components/source_1.brs:6636), in pkg:/components/source_3.brs(4710), and bare generated references such as source_10.brs:8211. See docs/roku-map-stack.md.

Generate Commands (generate:*) - Code Generation

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

Setup Commands

• sdk:install - Install the SDK by creating hosanna.json
• compiler:install - Install or update the Hosanna compiler (hsc)
• compiler:status - Print local compiler status for this project
• compiler:list - List compiler versions known from local config, install, and cache
• template:create - Create a new template app with the Hosanna SDK

Build Config Commands (build-config) - Runtime Configuration

• build-config:resolve - Resolve build-config/base.json, env/platform overlays, secrets, and optional developer profiles into the canonical runtime build-config.json

Production JavaScript bundles strip console.* calls by default. Configure this through the normal overlay chain with build.stripLogs: set it to false in build-config/prod.json to retain production logs, or in build-config/prod.apple.json / build-config/prod.web.json for a platform-only exception. Non-production environments keep logs unless their overlay explicitly enables stripping. Apple prod builds use Xcode Release; other environments continue to use Debug.

Native builds can resolve config immediately before the platform build:

npx hst build-config:resolve --env dev --platform roku --out assets/meta/build-config.json
npm run roku:build

HS_ENV=dev HS_PLATFORM=android npx hst build-config:resolve --out assets/meta/build-config.json
npm run android:build-code

HS_ENV=dev HS_PLATFORM=apple HS_BUILD_PROFILE=george npx hst build-config:resolve --out assets/meta/build-config.json
npm run apple:build-code

CI Commands (ci:*) - Continuous Integration

• ci:extract-pkg-key - Extract signing key from an existing signed Roku package as base64
• config set --git-url - Configure hosanna.json git-url from argument or environment

Build Config Commands (build-config:*) - Build/runtime config

• build-config:resolve - Merge build config overlays into assets/meta/build-config.json
• build-config:restore-secrets - Restore ignored secrets/*.json overlays from BUILD_CONFIG_SECRETS_*_BASE64

Secrets Commands (secrets:*) - Portable .secrets files

• secrets:list - Print key names from .secrets (or --template for .secrets.example); --format json
• secrets:check - Compare .secrets to the template; report missing, empty, and extra keys; --strict fails on extras
• secrets:exec - Load .secrets into the environment and run a command after --
• secrets:init - Copy .secrets.example to .secrets when missing

Shared options: --file (secrets path), --template (template path for check / init / list --template), --format text|json.

Environment Commands (env ...) - Environment Management

• env check - Print environment information and run checks
• env fix - Check and repair environment issues
• env prepare-gitignore - Ensure .gitignore contains required entries

Framework Source Symlinks (semver-keyed registry)

hst symlinks framework source folders from the hosanna-ui/ checkout into the project (src/hosanna-ui -> ../hosanna-ui/src/hosanna-ui, etc.). Which folders get linked is decided by a semver-keyed registry: an entry applies when the installed framework version is >= its key, and the highest applicable key wins. The installed version is read from hosanna-ui/package.json (prerelease suffixes are ignored, so 1.31.0-next counts as 1.31.0) — this works for tags, branches, @latest, and LOCAL_SDK alike.

Built-in defaults (src/updater/symlink-registry.ts):

| Installed hosanna-ui version | Symlinks under src/ | |---|---| | >= 1.0.0 | hosanna-bridge-core, hosanna-bridge-http, hosanna-bridge-lib, hosanna-bridge-targets, hosanna-list, hosanna-ui |

Prefer folder existence over version gates when adding registry entries: a checkout's package.json version can lag the tag it was cut from (hosanna-ui v1.28.3 reads 1.28.1-next), and folders absent from a checkout are already skipped safely at sync time.

hst env check always prints the active set, the matched registry version, and the source (built-in, hosanna.json override, + N extra). hst env fix creates missing links, repairs wrong targets, and removes obsolete ones — with no git/network access when only symlinks are wrong. Symlinks are also re-synced as part of every SDK update.

Adding folders (symlink-extra-folders) — the common customization. Appends to the resolved defaults; cannot break them. Folder names are forgiving ("hosanna-game/", "hosanna-game", and "src/hosanna-game" are equivalent):

{
  "git-url": "[email protected]:TantaWowa/hosanna-ui.git",
  "sdk-version": "v1.31.0",
  "symlink-extra-folders": ["hosanna-game/", "hosanna-game-examples/"]
}

Use this for game projects (hosanna-game, hosanna-game-examples) or when a project wants the example rigs (hosanna-ui-examples). Removing an entry makes its symlink obsolete; the next env fix cleans it up.

Replacing the registry (symlink-registry) — rare; total control. A valid key fully replaces the built-in registry (extras still append on top). Folders absent from the set become obsolete and are removed by --fix, so list everything the project needs:

{
  "symlink-registry": {
    "1.0.0":  ["hosanna-bridge-http/", "hosanna-bridge-lib/", "hosanna-bridge-targets/", "hosanna-list/", "hosanna-ui/"],
    "1.31.0": ["hosanna-bridge-http/", "hosanna-bridge-lib/", "hosanna-bridge-core/", "hosanna-bridge-targets/", "hosanna-list/", "hosanna-ui/"]
  }
}

An invalid symlink-registry/symlink-extra-folders value falls back to the built-in registry and is reported as an issue by hst env check — a typo cannot silently break an install.

Safety rules:

• A registry folder that does not exist in the checkout is skipped with a warning, never an error (older framework versions predate some folders).
• Obsolete cleanup only ever deletes symlinks at known framework paths (registry union, extras, retired folders such as src/hosanna-game). Real directories and files are never deleted; env fix reports them for manual handling instead.
• .gitignore (via env prepare-gitignore or any SDK update) covers the union of the built-in registry, any override, and any extras for the project.

MCP Debugging Commands (mcp:start, mcp:stop) - AI Agent Debugging

• mcp:start - Start the Hosanna MCP server for AI agent debugging
• mcp:stop - Stop the Hosanna MCP server

Cursor and MCP: Cursor does not magically attach to a terminal hst mcp:start. Add Hosanna as a Command MCP server (project .cursor/mcp.json or Cursor Settings → MCP → Add Custom MCP) so Cursor spawns hosanna-mcp over stdio. Start the command debugger/app explicitly with hst run --platform web --target web, hst run --platform ios --target web, hst run --platform android-tv --target web, or hst run --platform roku --target device.

UI Test Commands (test:*) - UI Test Automation

• test:ui - Replay UI test recordings against a running Hosanna app
• test:record - Interactively record a UI test by navigating the app

Usage Examples

# Development workflow
hst run --platform web            # Start/reuse web dev services
hst run --platform roku --target emulator
hst run --platform ios --target emulator
hst run --platform android --target emulator
hst run --platform apple-tv --target emulator
hst run --platform android-tv --target emulator
hst run --platform ios --target sim --device "iPhone 17 Pro"
hst run --platform ios --target device --device "George iPhone" --no-logs
hst run --platform android --target sim --device "Pixel_8" --no-logs
hst run --platform android --target device --device "RF8M62694QT" --no-logs
hst run --platform android-tv --target sim --device "Television_1080p" --no-logs
hst run --platform apple-tv --target sim --device "Apple TV 4K"
hst run --platform roku --target device --device "Living Room"
hst run --platform roku --target device --device "Living Room" --replace
hst target:list --platform ios --target device --json
hst target:list --platform android --target sim --json
hst target:list --platform android-tv --target sim --json
hst target:list --platform apple-tv --target sim --json
hst target:list --form-factor tv --json
hst generate:all --watch          # Generate code with file watching
hst dev:start                    # Lower-level dev server task used by hst run

# 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 sdk:install                 # Initialize Hosanna SDK
hst compiler:install           # Install Hosanna compiler
hst template:create           # Create new template app

# CI/CD operations
hst ci:extract-pkg-key myapp.pkg  # Extract signing key for CI
hst build-config:restore-secrets
hst build-config:resolve --env prod --platform roku --out assets/meta/build-config.json

# Secrets (.secrets / .secrets.example)
hst secrets:list
hst secrets:list --template --format json
hst secrets:check --strict
hst secrets:exec -- npm run build
hst secrets:init

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

# MCP debugging (AI agent integration)
hst debugger:start               # Start debug proxy (required)
hst mcp:start                    # Start MCP server for Cursor/Claude

# UI test automation
hst test:record --name "My test"  # Record UI test interactively
hst test:ui                       # Replay all recordings
hst test:ui --suite regression.json  # Run test suite
hst test:ui --json --report-dir ./reports  # CI mode with reports

MCP Debugging & UI Test Automation

Hosanna Tools includes a powerful MCP (Model Context Protocol) server for AI-assisted debugging and a UI test automation framework.

Cursor Settings → MCP (Hosanna debugger)

Use Type: Command (not URL). Cursor spawns one long-lived process and speaks MCP over stdin/stdout.

| Field | Suggested value | |--------|------------------| | Name | hosanna-debugger (or any stable label) | | Type | Command | | Command | hosanna-mcp if @tantawowa/hosanna-tools is on your PATH (e.g. npm install -g or project node_modules/.bin). Otherwise use npx and put the package + binary in Arguments (see JSON below). | | Arguments | Usually empty when Command is hosanna-mcp. With npx: -y --package=@tantawowa/hosanna-tools hosanna-mcp (one token per argv if the UI supports a list; otherwise a single line matching the JSON args array). | | Environment | Optional; defaults match hst debugger:start. Use only if you use non-default ports. |

Equivalent ~/.cursor/mcp.json or .cursor/mcp.json (project) entry:

{
  "mcpServers": {
    "hosanna-debugger": {
      "command": "hosanna-mcp",
      "args": []
    }
  }
}

npx without a global install (same as one row in the UI: command npx, args as listed):

{
  "mcpServers": {
    "hosanna-debugger": {
      "command": "npx",
      "args": ["-y", "--package=@tantawowa/hosanna-tools", "hosanna-mcp"]
    }
  }
}

Environment variables (add under "env" in JSON, or Key / Value in the UI) when ports differ from the debugger:

| Key | Typical value | |-----|----------------| | HOSANNA_MANAGEMENT_PORT | 59150 | | HOSANNA_MANAGEMENT_HOST | localhost | | HOSANNA_EXTENSION_PORT | 59153 (must match hst debugger:start) |

After saving, enable the server in the MCP list. hst mcp:start is still useful in a terminal for manual runs; Cursor agents use the configured MCP spawn instead.

Quick Start

# 1. Start the debug proxy (required for both MCP and test automation)
hst debugger:start

# 2. Start your Hosanna app with remote debugging enabled

# 3. For AI debugging (Cursor, Claude Code):
#    Add MCP server (see "Cursor Settings → MCP" above) or hst mcp:start in a terminal

# 4. For UI test recording:
hst test:record --name "My test flow"

# 5. For UI test replay:
hst test:ui

See also

Documentation at the top of this README (MCP README, docs/README.md, hosanna-ui docs/README.md).

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