@tantawowa/hosanna-tools 2.21.0 → 2.23.0

package/README.md

@@ -2,7 +2,7 @@
 
 ## Documentation
 
-- **[MCP debugger & UI tests](src/support-tools/mcp-server/README.md)** — `hst run:mcp`, all MCP tools, commands by use case, examples, `hst test:ui` / `hst test:record`.
+- **[MCP debugger & UI tests](src/support-tools/mcp-server/README.md)** — `hst mcp:start`, all MCP tools, commands by use case, examples, `hst test:ui` / `hst test:record`.
 - **[docs/README.md](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.
 
@@ -23,7 +23,7 @@ npm install . -g # path to the hosanna-tools directory
 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.
 
 ```ts
-import { buildConfig, env, generate, install, roku, secrets } from '@tantawowa/hosanna-tools';
+import { buildConfig, compiler, env, generate, roku, secrets } from '@tantawowa/hosanna-tools';
 
 await generate.all({
   rootFolder: './src',
@@ -37,7 +37,7 @@ await buildConfig.resolve({
   out: 'assets/meta/build-config.json',
 });
 
-await install.compiler({ version: '0.33.7' });
+await compiler.install({ version: '0.33.7' });
 await roku.package({ env: 'prod', prebuild: 'npm run roku:build:prod' });
 ```
 
@@ -45,13 +45,13 @@ Common build-script replacements:
 
 | CLI command | Programmatic API |
 | --- | --- |
-| `npx hst generate --rootFolder ./src` | `await generate.all({ rootFolder: './src' })` |
+| `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 install:compiler 0.33.7` | `await install.compiler({ version: '0.33.7' })` |
+| `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` | `await env.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.
 
@@ -143,9 +143,35 @@ Hosanna Tools is a comprehensive CLI toolset for the Hosanna framework that prov
 
 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 (only one debugger is needed for multiple apps; if the port is already in use, a friendly message is shown instead of crashing)
+### Development Commands
+- `run` - Canonical cross-platform app launcher. Requires `--platform` and supports web, Roku, iOS, Apple TV, Android, and Android TV launch targets.
+- `target:list` - List launch targets for humans or agents, including web previews, simulators, 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:
+
+```bash
+hst run --platform web
+hst run --platform roku --target web
+hst run --platform roku --target simulated
+hst run --platform roku --target emulated
+hst run --platform ios --target simulator --device "iPhone 17 Pro"
+hst run --platform ios --target device --device "George iPhone" --no-logs
+hst run --platform android --target emulator --device "Pixel_8" --no-logs
+hst run --platform android --target device --device "RF8M62694QT" --no-logs
+hst run --platform android-tv --target emulator --device "Television_1080p" --no-logs
+hst run --platform apple-tv --target simulator --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 emulator --json
+hst target:list --platform android-tv --target emulator --json
+hst target:list --platform apple-tv --target simulator --json
+hst target:list --form-factor tv --json
+```
+
+`hst run` is platform-explicit by design, so non-interactive agents do not guess between iOS, Apple TV, Android, Android TV, Roku, or web. For Roku, `web`, `simulated`, and `emulated` all launch the web preview; `device` deploys to a physical Roku. For iOS and Apple TV, `simulator` launches an Apple simulator and `device` launches paired physical hardware. For Android and Android TV, `emulator` launches an Android emulator and `device` launches ADB-connected physical hardware. Device/emulator 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)
@@ -168,37 +194,39 @@ 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](docs/roku-map-stack.md).
 
 ### Generate Commands (`generate:*`) - Code Generation
-- `generate` - Generate structs and command handler maps
+- `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
 
-### 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
+### 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`
+- `build-config:resolve` - Resolve `build-config/base.json`, env/platform overlays, secrets, and optional developer profiles into the canonical runtime `build-config.json`
 
 Native builds can resolve config immediately before the platform build:
 
 ```bash
-npx hst build-config resolve --env dev --platform roku --out assets/meta/build-config.json
+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
+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
+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
-- `ci:configure-hosanna-url` - Configure hosanna.json git-url from argument or environment
+- `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: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
@@ -209,16 +237,83 @@ npm run apple:build-code
 
 Shared options: `--file` (secrets path), `--template` (template path for `check` / `init` / `list --template`), `--format text|json`.
 
-### Environment Commands (`env:*`) - Environment Management
-- `env` - Print environment information and run checks with auto-fix option
-- `env:prepare-gitignore` - Ensure .gitignore contains required entries
-- `env:cloud-agent-setup` - Write `build-config/profiles/cloud-agent.json`, patch `remoteDebug` for cloud agents, optionally start debugger and `npm run dev` with `HS_BUILD_PROFILE=cloud-agent`
+### 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-http`, `hosanna-bridge-lib`, `hosanna-bridge-targets`, `hosanna-list`, `hosanna-ui` |
+| >= 1.31.0 | the above + `hosanna-bridge-core` |
+
+`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):
+
+```json
+{
+  "git-url": "git@github.com: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:
+
+```json
+{
+  "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 (`run:mcp`, `stop:mcp`) - AI Agent Debugging
-- `run:mcp` - Start the Hosanna MCP server for AI agent debugging
-- `stop:mcp` - Stop the Hosanna MCP server
+### 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 agents and MCP:** Cursor does not magically attach to a terminal `hst run:mcp`. You add Hosanna as an MCP server (project **`.cursor/mcp.json`** or **Cursor Settings → MCP → Add Custom MCP**) so Cursor spawns **`hosanna-mcp`** (stdio transport). That process talks to the **command debugger** on HTTP **59150** and extension WebSocket **59153** by default. In **Cursor Cloud Agents**, run **`npx hst env:cloud-agent-setup --start-debugger --start-app`** so those services are up before the agent uses MCP tools. See [Cursor MCP settings](#cursor-settings--mcp-hosanna-debugger) below.
+**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`, `hst run --platform roku --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
@@ -228,23 +323,39 @@ Shared options: `--file` (secrets path), `--template` (template path for `check`
 
 ```bash
 # 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
+hst run --platform web            # Start/reuse web dev services
+hst run --platform roku --target web
+hst run --platform roku --target simulated
+hst run --platform roku --target emulated
+hst run --platform ios --target simulator --device "iPhone 17 Pro"
+hst run --platform ios --target device --device "George iPhone" --no-logs
+hst run --platform android --target emulator --device "Pixel_8" --no-logs
+hst run --platform android --target device --device "RF8M62694QT" --no-logs
+hst run --platform android-tv --target emulator --device "Television_1080p" --no-logs
+hst run --platform apple-tv --target simulator --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 emulator --json
+hst target:list --platform android-tv --target emulator --json
+hst target:list --platform apple-tv --target simulator --json
+hst target:list --form-factor tv --json
+hst generate:all --watch          # Generate code with file watching
+hst dev:start                    # Lower-level dev server command
 
 # 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
+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
+hst build-config:resolve --env prod --platform roku --out assets/meta/build-config.json
 
 # Secrets (.secrets / .secrets.example)
 hst secrets:list
@@ -254,13 +365,12 @@ 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
-hst env:cloud-agent-setup --start-debugger --start-app
+hst env fix                  # Check and fix environment issues
+hst env prepare-gitignore      # Update .gitignore
 
 # MCP debugging (AI agent integration)
-hst run:debugger               # Start debug proxy (required)
-hst run:mcp                    # Start MCP server for Cursor/Claude
+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
@@ -283,7 +393,7 @@ Use **Type: Command** (not URL). Cursor spawns one long-lived process and speaks
 | **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 run:debugger`. Use only if you use non-default ports. |
+| **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:
 
@@ -317,20 +427,20 @@ Equivalent **`~/.cursor/mcp.json`** or **`.cursor/mcp.json`** (project) entry:
 |-----|----------------|
 | `HOSANNA_MANAGEMENT_PORT` | `59150` |
 | `HOSANNA_MANAGEMENT_HOST` | `localhost` |
-| `HOSANNA_EXTENSION_PORT` | `59153` (must match `hst run:debugger`) |
+| `HOSANNA_EXTENSION_PORT` | `59153` (must match `hst debugger:start`) |
 
-After saving, enable the server in the MCP list. **`hst run:mcp`** is still useful in a terminal for manual runs; Cursor agents use the configured MCP spawn instead.
+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
 
 ```bash
 # 1. Start the debug proxy (required for both MCP and test automation)
-hst run:debugger
+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 run:mcp in a terminal
+#    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"

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "buildDate": "2026-06-10T19:58:46+01:00",
-  "buildDateISO": "2026-06-10T18:58:46.578Z",
+  "buildDate": "2026-06-14T08:41:07+01:00",
+  "buildDateISO": "2026-06-14T07:41:07.025Z",
   "timeZone": "Europe/London",
-  "gitHash": "411594a"
+  "gitHash": "21b0bc5"
 }