@tantawowa/hosanna-tools 3.6.1 → 3.7.0

package/README.md

@@ -20,19 +20,32 @@ npm install . -g # path to the hosanna-tools directory
 
 ## Hosanna source install modes
 
-Client projects can switch between Keygen source tarballs, git checkouts, and a
-local SDK checkout:
+Client projects can switch between private Keygen source tarballs, an embedded
+copy, a shared local checkout, and the legacy git/local modes:
 
 ```bash
-hst config source                 # show current mode
-hst config source keygen --fix    # default: full + roku,web from @nightly
-hst config source git --fix       # use the configured git checkout again
-hst config source local --fix     # use LOCAL_SDK for framework development
+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"` to `hosanna.json` and installs
-license-gated artifacts with `hst env fix` / `hst sdk:install`. Git mode keeps
-the legacy clone/update path for developers who need it.
+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.
+
+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
 
@@ -197,9 +210,23 @@ hst target:list --form-factor tv --json
 
 ### 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):
+
+```bash
+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:
+
+```bash
+hst roku:command clearRegistry --app-id 8518 --dry-run
+```
+
 Resolve pasted Roku output:
 
 ```bash

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "buildDate": "2026-07-11T20:48:11+00:00",
-  "buildDateISO": "2026-07-11T20:48:11.158Z",
+  "buildDate": "2026-07-14T09:12:47+00:00",
+  "buildDateISO": "2026-07-14T09:12:47.324Z",
   "timeZone": "UTC",
-  "gitHash": "aee354a"
+  "gitHash": "915e992"
 }

package/dist/cli.js

@@ -250,7 +250,7 @@ catch (err) {
 // Let yargs handle all commands including env
 (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
     .version(`${buildVersion}\n  git: ${buildGitHash}\n  built: ${buildDate}`)
-    .usage('$0 [command] [options]', `Hosanna Tools CLI\nVersion: ${buildVersion}\nBuild Date: ${buildDate}\n\nCommand Groups:\n  compiler:*    Compiler lifecycle (install, status, list)\n  config        hosanna.json management (wizard, show, set)\n  env           Environment checks and repair (check, fix, prepare-gitignore)\n  dev:*         Local development execution\n  debugger:*    Command debugger control\n  mcp:*         Hosanna MCP server control\n  build         Cross-platform build orchestration\n  run           Cross-platform launch orchestration\n  native:*      Native platform bootstrap and validation\n  target:*      Run target discovery and inventory\n  roku:*        Roku deployment & packaging (run, package, map-stack)\n  device:*      Device discovery and run workflows\n  generate:*    Code and asset generation\n  sdk:*         Hosanna SDK/framework installation\n  build-config:* Build/runtime configuration resolution\n  ci:*          Continuous integration helpers\n  framework:*   Framework distribution helpers\n  license:*     Hosanna framework licensing\n  secrets:*     Portable .secrets files\n  test:*        UI testing\n  rasp:*        RASP cert scripts`)
+    .usage('$0 [command] [options]', `Hosanna Tools CLI\nVersion: ${buildVersion}\nBuild Date: ${buildDate}\n\nCommand Groups:\n  compiler:*    Compiler lifecycle (install, status, list)\n  config        hosanna.json management (wizard, show, set)\n  env           Environment checks and repair (check, fix, prepare-gitignore)\n  dev:*         Local development execution\n  debugger:*    Command debugger control\n  mcp:*         Hosanna MCP server control\n  build         Cross-platform build orchestration\n  run           Cross-platform launch orchestration\n  native:*      Native platform bootstrap and validation\n  target:*      Run target discovery and inventory\n  roku:*        Roku deployment, commands & packaging (run, command, package, map-stack)\n  device:*      Device discovery and run workflows\n  generate:*    Code and asset generation\n  sdk:*         Hosanna SDK/framework installation\n  build-config:* Build/runtime configuration resolution\n  ci:*          Continuous integration helpers\n  framework:*   Framework distribution helpers\n  license:*     Hosanna framework licensing\n  secrets:*     Portable .secrets files\n  test:*        UI testing\n  rasp:*        RASP cert scripts`)
     .option('verbose', {
     type: 'boolean',
     default: false,
@@ -551,6 +551,44 @@ catch (err) {
         console.error('❌ Failed to publish Roku package:', err);
         process.exit(1);
     }
+})
+    .command('roku:command <command>', 'Send a Hosanna command to an installed Roku channel through ECP', yargs => yargs
+    .positional('command', { type: 'string', demandOption: true, describe: 'Hosanna command name, e.g. clearRegistry' })
+    .option('device', { alias: 'ip', type: 'string', describe: 'Roku IP or configured device name (env: ROKU_IP)' })
+    .option('app-id', { type: 'string', default: 'dev', describe: 'Installed Roku channel ID (default: dev)' })
+    .option('timeout-ms', { type: 'number', default: 10000, describe: 'ECP request timeout in milliseconds' })
+    .option('yes', { alias: 'y', type: 'boolean', default: false, describe: 'Confirm destructive commands without prompting' })
+    .option('dry-run', { type: 'boolean', default: false, describe: 'Resolve the device and print the ECP request without sending it' })
+    .option('non-interactive', { type: 'boolean', default: false, describe: 'Fail instead of prompting for destructive command confirmation' })
+    .example('$0 roku:command clearRegistry --device 192.168.1.50', 'Clear the sideloaded dev channel registry after confirmation')
+    .example('$0 roku:command clearRegistry --device "living room" --yes', 'Clear the configured Roku registry non-interactively')
+    .example('$0 roku:command clearRegistry --app-id 8518 --dry-run', 'Preview a command for an installed production channel'), async (args) => {
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require('./support-tools/roku-command.js')));
+        const result = await mod.runRokuCommand({
+            command: args.command,
+            cwd: process.cwd(),
+            device: args.device,
+            appId: args['app-id'],
+            timeoutMs: args['timeout-ms'],
+            yes: Boolean(args.yes),
+            dryRun: Boolean(args['dry-run']),
+            nonInteractive: Boolean(args['non-interactive']),
+            env: process.env,
+        });
+        if (result.dryRun) {
+            console.info(`Dry run: POST ${result.url}`);
+        }
+        else {
+            console.info(`✅ Sent Hosanna command "${result.command}" to Roku ${result.deviceIp} (app ${result.appId}).`);
+        }
+        process.exit(0);
+    }
+    catch (err) {
+        console.error('❌ roku:command failed');
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
 })
     .command('roku:map-stack', 'Resolve Roku BrightScript stack traces or compile errors to original TypeScript locations using .brs.map files', yargs => yargs
     .option('source-map-root', {
@@ -747,7 +785,7 @@ catch (err) {
 })
     .positional('mode', {
     type: 'string',
-    choices: ['show', 'keygen', 'git', 'local'],
+    choices: ['show', 'keygen', 'git', 'local', 'embedded', 'shared'],
     describe: 'Source install mode when action is source',
 })
     .option('git-url', { type: 'string', describe: 'Set hosanna.json git-url' })
@@ -756,8 +794,9 @@ catch (err) {
     .option('transpiler-version', { type: 'string', describe: 'Set hosanna.json transpiler-version' })
     .option('config-catalog-url', { type: 'string', describe: 'Persist a remote catalog URL into hosanna.json' })
     .option('catalog-url', { type: 'string', describe: 'Use a remote catalog URL for this run without writing it' })
-    .option('flavour', { type: 'string', choices: ['core', 'game', 'full'], describe: 'Keygen source flavour when action is source (default: full)' })
-    .option('platforms', { type: 'string', array: true, describe: 'Keygen platforms when action is source, comma-separated or repeatable (default: roku,web)' })
+    .option('flavour', { type: 'string', choices: ['fullSource', 'core', 'game', 'full'], describe: 'Keygen source flavour when action is source (supported: fullSource)' })
+    .option('platforms', { type: 'string', array: true, describe: 'Future split-platform selection; omit for fullSource' })
+    .option('source-path', { type: 'string', describe: 'Hosanna UI checkout to copy for embedded mode or link for shared mode' })
     .option('install', { type: 'boolean', default: false, describe: 'Install the selected source mode atomically after updating config' })
     .option('replace-existing', { type: 'boolean', default: false, describe: 'Allow --install to replace an existing hosanna-ui source root when switching modes' })
     .option('force', { type: 'boolean', default: false, describe: 'Allow --install to replace a dirty git checkout when used with --replace-existing' })
@@ -774,6 +813,7 @@ catch (err) {
                 mode: (typeof args.mode === 'string' ? args.mode : 'show'),
                 flavour: args.flavour,
                 platforms: (0, hosanna_config_js_1.parsePlatformList)(stringArrayArg(args.platforms)),
+                sourcePath: typeof args.sourcePath === 'string' ? args.sourcePath : undefined,
                 sdkVersion: typeof args.sdkVersion === 'string' ? args.sdkVersion : undefined,
                 gitUrl: typeof args.gitUrl === 'string' ? args.gitUrl : undefined,
                 branch: typeof args.branch === 'string' ? args.branch : undefined,