@tantawowa/hosanna-tools 3.1.0 → 3.3.0

package/README.md

@@ -145,7 +145,7 @@ The CLI commands are organized into logical groups using colon-separated namespa
 
 ### 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.
+- `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)
 
@@ -153,29 +153,27 @@ Examples:
 
 ```bash
 hst run --platform web
-hst run --platform roku --target web
-hst run --platform ios --target web
-hst run --platform android --target web
-hst run --platform apple-tv --target web
-hst run --platform android-tv --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 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 emulator --device "Pixel_8" --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 emulator --device "Television_1080p" --no-logs
-hst run --platform apple-tv --target simulator --device "Apple TV 4K"
+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 emulator --json
-hst target:list --platform android-tv --target emulator --json
-hst target:list --platform apple-tv --target simulator --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 run` is platform-explicit by design, so non-interactive agents do not guess between iOS, Apple TV, Android, Android TV, Roku, or web. `--target web` 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. For Roku, `simulated` and `emulated` are accepted aliases for 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.
+`hst run` is platform-explicit by design, so non-interactive agents do not guess between iOS, Apple TV, Android, Android TV, Roku, or web. `--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)
@@ -328,25 +326,23 @@ silently break an install.
 ```bash
 # Development workflow
 hst run --platform web            # Start/reuse web dev services
-hst run --platform roku --target web
-hst run --platform ios --target web
-hst run --platform android --target web
-hst run --platform apple-tv --target web
-hst run --platform android-tv --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 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 emulator --device "Pixel_8" --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 emulator --device "Television_1080p" --no-logs
-hst run --platform apple-tv --target simulator --device "Apple TV 4K"
+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 emulator --json
-hst target:list --platform android-tv --target emulator --json
-hst target:list --platform apple-tv --target simulator --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

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "buildDate": "2026-06-22T22:01:33+01:00",
-  "buildDateISO": "2026-06-22T21:01:33.521Z",
+  "buildDate": "2026-07-01T07:59:40+01:00",
+  "buildDateISO": "2026-07-01T06:59:40.421Z",
   "timeZone": "Europe/London",
-  "gitHash": "03dcf25"
+  "gitHash": "fd78d71"
 }

package/dist/cli.js

@@ -69,11 +69,20 @@ function formatRunPlanText(plan, explain, command = 'run') {
     if (explain) {
         lines.push('', 'Resolution sources:');
         for (const [key, value] of Object.entries(plan.sources)) {
-            lines.push(`  ${key}: ${value}`);
+            lines.push(`  ${key}: ${value}${explainResolvedValue(plan, key)}`);
         }
     }
     return lines.join('\n');
 }
+function explainResolvedValue(plan, key) {
+    if (key === 'hsconfig' && plan.resolved.hsconfig) {
+        return ` (${plan.resolved.hsconfig})`;
+    }
+    if (key === 'hscProject' && plan.resolved.hscProject) {
+        return ` (${plan.resolved.hscProject})`;
+    }
+    return '';
+}
 function rawCommandPositionals(command) {
     const raw = (0, helpers_1.hideBin)(process.argv);
     const index = raw.indexOf(command);
@@ -110,6 +119,7 @@ function runPlanFlagsFromCliArgs(args, format) {
         appPackage: rawHasFlag('app-package') ? args['app-package'] : undefined,
         files: rawHasFlag('files') ? args.files : undefined,
         deployTimeoutMs: rawHasFlag('deploy-timeout-ms') ? args['deploy-timeout-ms'] : undefined,
+        hsconfig: rawHasFlag('hsconfig') ? args.hsconfig : undefined,
         config: rawHasFlag('config') ? args.config : undefined,
         hscProject: rawHasFlag('hsc-project') ? args.hscProject : undefined,
         vitePort: rawHasFlag('vitePort') ? args.vitePort : undefined,
@@ -1400,7 +1410,7 @@ catch (err) {
         process.exit(1);
     }
 })
-    .command('target:list [platform]', 'List run targets discovered by hst, including web previews, simulators, and physical devices', yargs => yargs
+    .command('target:list [platform]', 'List run targets discovered by hst, including web emulators, sims, and physical devices', yargs => yargs
     .positional('platform', {
     type: 'string',
     choices: ['web', 'roku', 'ios', 'apple-tv', 'android', 'android-tv'],
@@ -1413,7 +1423,7 @@ catch (err) {
 })
     .option('target', {
     type: 'string',
-    choices: ['browser', 'web', 'device', 'simulator', 'emulator', 'simulated', 'emulated'],
+    choices: ['emulator', 'web', 'browser', 'sim', 'simulator', 'device', 'simulated', 'emulated'],
     describe: 'Filter by target kind',
 })
     .option('form-factor', {
@@ -1432,14 +1442,14 @@ catch (err) {
     default: 'text',
     describe: 'Output format',
 })
-    .example('$0 target:list --platform roku', 'List Roku web/device targets')
-    .example('$0 target:list --platform ios --target browser --json', 'List the iOS browser target as JSON')
-    .example('$0 target:list --platform ios --target simulator --json', 'List iOS simulator targets as JSON')
+    .example('$0 target:list --platform roku', 'List Roku web emulator and device targets')
+    .example('$0 target:list --platform ios --target emulator --json', 'List the iOS web emulator target as JSON')
+    .example('$0 target:list --platform ios --target sim --json', 'List iOS simulator targets as JSON')
     .example('$0 target:list --platform ios --target device --json', 'List physical iOS device targets as JSON')
-    .example('$0 target:list --platform android --target emulator --json', 'List Android phone emulator targets as JSON')
+    .example('$0 target:list --platform android --target sim --json', 'List Android phone emulator targets as JSON')
     .example('$0 target:list --platform android --target device --json', 'List physical Android device targets as JSON')
-    .example('$0 target:list --platform android-tv --target emulator --json', 'List Android TV emulator targets as JSON')
-    .example('$0 target:list --platform apple-tv --target simulator --json', 'List Apple TV simulator targets as JSON')
+    .example('$0 target:list --platform android-tv --target sim --json', 'List Android TV emulator targets as JSON')
+    .example('$0 target:list --platform apple-tv --target sim --json', 'List Apple TV simulator targets as JSON')
     .example('$0 target:list --form-factor tv --json', 'List TV-class targets as JSON'), async (args) => {
     try {
         const mod = await Promise.resolve().then(() => __importStar(require('./run/targets.js')));
@@ -1475,11 +1485,11 @@ catch (err) {
 })
     .positional('target', {
     type: 'string',
-    describe: 'Target kind: browser, device, simulator, or emulator.',
+    describe: 'Target kind: emulator, sim, or device.',
 })
     .positional('deviceSelector', {
     type: 'string',
-    describe: 'Device IP, serial/UDID, AVD name, simulator name, or case-insensitive name substring.',
+    describe: 'Device IP, serial/UDID, AVD name, simulator name, web preset id, or case-insensitive name substring.',
 })
     .option('platform', {
     type: 'string',
@@ -1492,12 +1502,12 @@ catch (err) {
 })
     .option('target', {
     type: 'string',
-    choices: ['browser', 'web', 'device', 'simulator', 'emulator', 'simulated', 'emulated'],
+    choices: ['emulator', 'web', 'browser', 'sim', 'simulator', 'device', 'simulated', 'emulated'],
     describe: 'Target kind. Defaults by platform.',
 })
     .option('device', {
     type: 'string',
-    describe: 'Device IP, serial/UDID, case-insensitive name substring, or web preset id for --target browser',
+    describe: 'Device IP, serial/UDID, case-insensitive name substring, or web preset id for --target emulator',
 })
     .option('appName', {
     type: 'string',
@@ -1519,13 +1529,14 @@ catch (err) {
     .option('dry-run', { type: 'boolean', default: false, describe: 'Print the resolved build RunPlan without executing it' })
     .option('format', { type: 'string', choices: ['text', 'json'], default: 'text', describe: 'Output format for --dry-run and build result' })
     .option('explain', { type: 'boolean', default: false, describe: 'Include resolution source details in text dry-run output' })
+    .option('hsconfig', { type: 'string', describe: 'Explicit hsconfig file for Roku/native build planning' })
     .option('hsc-project', { type: 'string', describe: 'Explicit Roku HSC project file for hst build planning' })
-    .option('config', { type: 'string', describe: 'Alias for --hsc-project' })
+    .option('config', { type: 'string', describe: 'Back-compatible alias for --hsconfig / --hsc-project' })
     .option('source-root', { type: 'string', describe: 'Roku source root to preserve in build planning output' })
     .example('$0 build roku dev device', 'Build the dev Roku output without deploying or streaming logs')
     .example('$0 build roku prod device --hsc-project platforms/hsconfig-roku.prod.json', 'Build Roku with an explicit HSC project file')
-    .example('$0 build ios dev simulator --device "iPhone 17 Pro"', 'Build an iOS simulator target without install, launch, or logs')
-    .example('$0 build web dev browser', 'Resolve web runtime build config without opening a browser'), async (args) => {
+    .example('$0 build ios dev sim --device "iPhone 17 Pro"', 'Build an iOS simulator target without install, launch, or logs')
+    .example('$0 build web dev emulator', 'Resolve web runtime build config without opening a browser'), async (args) => {
     await runRunPlanCommand('build', args);
 })
     .command('run [platform] [env] [target] [deviceSelector]', 'Launch a Hosanna app on a platform target (web, Roku, iOS, Apple TV, Android, and Android TV targets are supported)', yargs => yargs
@@ -1540,11 +1551,11 @@ catch (err) {
 })
     .positional('target', {
     type: 'string',
-    describe: 'Target kind: browser, device, simulator, or emulator.',
+    describe: 'Target kind: emulator, sim, or device.',
 })
     .positional('deviceSelector', {
     type: 'string',
-    describe: 'Device IP, serial/UDID, AVD name, simulator name, or case-insensitive name substring.',
+    describe: 'Device IP, serial/UDID, AVD name, simulator name, web preset id, or case-insensitive name substring.',
 })
     .option('platform', {
     type: 'string',
@@ -1557,12 +1568,12 @@ catch (err) {
 })
     .option('target', {
     type: 'string',
-    choices: ['browser', 'web', 'device', 'simulator', 'emulator', 'simulated', 'emulated'],
+    choices: ['emulator', 'web', 'browser', 'sim', 'simulator', 'device', 'simulated', 'emulated'],
     describe: 'Target kind. Defaults by platform.',
 })
     .option('device', {
     type: 'string',
-    describe: 'Device IP, serial/UDID, case-insensitive name substring, or web preset id for --target browser',
+    describe: 'Device IP, serial/UDID, case-insensitive name substring, or web preset id for --target emulator',
 })
     .option('appName', {
     type: 'string',
@@ -1592,8 +1603,9 @@ catch (err) {
     .option('build-only', { type: 'boolean', default: false, describe: 'Plan or run build steps without opening browser/log streams where supported' })
     .option('no-logs', { type: 'boolean', default: false, describe: 'Do not stream device logs after launch where supported' })
     .option('build-cmd', { type: 'string', describe: 'Override the platform build command for device runs' })
+    .option('hsconfig', { type: 'string', describe: 'Explicit hsconfig file for Roku/native run planning' })
     .option('hsc-project', { type: 'string', describe: 'Explicit Roku HSC project file for hst run planning' })
-    .option('config', { type: 'string', describe: 'Alias for --hsc-project' })
+    .option('config', { type: 'string', describe: 'Back-compatible alias for --hsconfig / --hsc-project' })
     .option('app-package', { type: 'string', describe: 'Roku app .zip or folder to deploy for device runs' })
     .option('source-root', { type: 'string', describe: 'Roku source root to deploy for device runs' })
     .option('source-map-root', { type: 'string', describe: 'Roku source map root for log resolution' })
@@ -1603,17 +1615,17 @@ catch (err) {
     .option('logs', { type: 'boolean', default: false, describe: 'Enable verbose deploy logging where supported' })
     .option('applySourceMapToPaths', { type: 'boolean', default: true, describe: 'Resolve Roku stack trace paths with source maps during log streaming' })
     .example('$0 run --platform web', 'Start/reuse web dev services for this app')
-    .example('$0 run --platform roku --target browser', 'Start/reuse the Roku TV browser preview')
-    .example('$0 run --platform ios --target browser', 'Start/reuse the iPhone-shaped browser runtime profile')
-    .example('$0 run --platform android --target browser --device pixel-8', 'Start/reuse the Android-shaped browser runtime profile')
-    .example('$0 run --platform apple-tv --target browser --no-open', 'Start/reuse the Apple TV browser runtime profile without opening a browser')
-    .example('$0 run --platform android-tv --target browser', 'Start/reuse the Android TV browser runtime profile')
-    .example('$0 run --platform ios --target simulator --device "iPhone 17 Pro"', 'Build, install, and launch on an iOS simulator')
+    .example('$0 run --platform roku --target emulator', 'Start/reuse the Roku TV web emulator')
+    .example('$0 run --platform ios --target emulator', 'Start/reuse the iPhone-shaped web emulator profile')
+    .example('$0 run --platform android --target emulator --device pixel-8', 'Start/reuse the Android-shaped web emulator profile')
+    .example('$0 run --platform apple-tv --target emulator --no-open', 'Start/reuse the Apple TV web emulator profile without opening a browser')
+    .example('$0 run --platform android-tv --target emulator', 'Start/reuse the Android TV web emulator profile')
+    .example('$0 run --platform ios --target sim --device "iPhone 17 Pro"', 'Build, install, and launch on an iOS simulator')
     .example('$0 run --platform ios --target device --device "George iPhone" --no-logs', 'Build, install, and launch on a physical iPhone')
-    .example('$0 run --platform android --target emulator --device "Pixel_8" --no-logs', 'Build, install, and launch on an Android phone emulator')
+    .example('$0 run --platform android --target sim --device "Pixel_8" --no-logs', 'Build, install, and launch on an Android phone emulator')
     .example('$0 run --platform android --target device --device "RF8M62694QT" --no-logs', 'Build, install, and launch on a physical Android device')
-    .example('$0 run --platform android-tv --target emulator --device "Television_1080p" --no-logs', 'Build, install, and launch on an Android TV emulator')
-    .example('$0 run --platform apple-tv --target simulator --device "Apple TV 4K"', 'Build, install, and launch on an Apple TV simulator')
+    .example('$0 run --platform android-tv --target sim --device "Television_1080p" --no-logs', 'Build, install, and launch on an Android TV emulator')
+    .example('$0 run --platform apple-tv --target sim --device "Apple TV 4K"', 'Build, install, and launch on an Apple TV simulator')
     .example('$0 run --platform roku --target device --device "living room"', 'Build, deploy, launch, and stream logs on a Roku device')
     .example('$0 run roku dev device --app criterion', 'Run a configured monorepo app/flavor')
     .example('$0 run roku prod device --hsc-project platforms/hsconfig.criterion.prod.json', 'Override the Roku HSC project file'), async (args) => {