@tantawowa/hosanna-tools 2.26.0 → 3.1.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "buildDate": "2026-06-21T00:24:40+01:00",
-  "buildDateISO": "2026-06-20T23:24:40.984Z",
+  "buildDate": "2026-06-22T22:01:33+01:00",
+  "buildDateISO": "2026-06-22T21:01:33.521Z",
   "timeZone": "Europe/London",
-  "gitHash": "11f0011"
+  "gitHash": "03dcf25"
 }

package/dist/cli.js

@@ -60,6 +60,152 @@ const env_info_js_1 = require("./lib/env-info.js");
 const hosanna_tools_utils_js_1 = require("./lib/hosanna-tools-utils.js");
 const cli_app_config_resolve_js_1 = require("./lib/cli.app-config-resolve.js");
 const hosanna_config_js_1 = require("./lib/hosanna-config.js");
+function formatRunPlanText(plan, explain, command = 'run') {
+    const lines = [
+        `hst ${command} plan: ${plan.resolved.platform} ${plan.resolved.env} ${plan.resolved.target}`,
+        '',
+        ...plan.shellPreview.map(line => `  ${line}`),
+    ];
+    if (explain) {
+        lines.push('', 'Resolution sources:');
+        for (const [key, value] of Object.entries(plan.sources)) {
+            lines.push(`  ${key}: ${value}`);
+        }
+    }
+    return lines.join('\n');
+}
+function rawCommandPositionals(command) {
+    const raw = (0, helpers_1.hideBin)(process.argv);
+    const index = raw.indexOf(command);
+    if (index === -1)
+        return [];
+    const result = [];
+    for (const token of raw.slice(index + 1)) {
+        if (token === '--' || token.startsWith('-'))
+            break;
+        result.push(token);
+    }
+    return result;
+}
+function rawHasFlag(name) {
+    const dashName = `--${name}`;
+    return (0, helpers_1.hideBin)(process.argv).some(token => token === dashName || token.startsWith(`${dashName}=`));
+}
+function runPlanFlagsFromCliArgs(args, format) {
+    return {
+        platform: rawHasFlag('platform') ? args.platform : undefined,
+        env: rawHasFlag('env') ? args.env : undefined,
+        app: rawHasFlag('app') ? args.app : undefined,
+        target: rawHasFlag('target') ? args.target : undefined,
+        device: rawHasFlag('device') ? args.device : undefined,
+        profile: rawHasFlag('profile') ? args.profile : undefined,
+        appConfig: rawHasFlag('app-config') ? args['app-config'] : undefined,
+        hotReload: rawHasFlag('hot-reload') ? Boolean(args['hot-reload']) : undefined,
+        bundled: rawHasFlag('bundled') ? Boolean(args.bundled) : undefined,
+        noBuild: rawHasFlag('no-build') ? Boolean(args['no-build']) : undefined,
+        buildOnly: rawHasFlag('build-only') ? Boolean(args['build-only']) : undefined,
+        noLogs: rawHasFlag('no-logs') ? Boolean(args['no-logs']) : undefined,
+        logs: rawHasFlag('logs') ? Boolean(args.logs) : undefined,
+        sourceRoot: rawHasFlag('source-root') ? args['source-root'] : undefined,
+        appPackage: rawHasFlag('app-package') ? args['app-package'] : undefined,
+        files: rawHasFlag('files') ? args.files : undefined,
+        deployTimeoutMs: rawHasFlag('deploy-timeout-ms') ? args['deploy-timeout-ms'] : undefined,
+        config: rawHasFlag('config') ? args.config : undefined,
+        hscProject: rawHasFlag('hsc-project') ? args.hscProject : undefined,
+        vitePort: rawHasFlag('vitePort') ? args.vitePort : undefined,
+        webAppPort: rawHasFlag('webAppPort') ? args.webAppPort : undefined,
+        deviceAppPort: rawHasFlag('deviceAppPort') ? args.deviceAppPort : undefined,
+        extensionPort: rawHasFlag('extensionPort') ? args.extensionPort : undefined,
+        managementPort: rawHasFlag('managementPort') ? args.managementPort : undefined,
+        appName: rawHasFlag('appName') ? args.appName : undefined,
+        replace: rawHasFlag('replace') ? Boolean(args.replace) : undefined,
+        nonInteractive: rawHasFlag('non-interactive') ? Boolean(args['non-interactive']) : undefined,
+        dryRun: Boolean(args['dry-run']),
+        format,
+        explain: rawHasFlag('explain') ? Boolean(args.explain) : undefined,
+        allowProfileInProd: rawHasFlag('allow-profile-in-prod') ? Boolean(args['allow-profile-in-prod']) : undefined,
+        passthroughArgs: args['--'],
+    };
+}
+async function runRunPlanCommand(command, args) {
+    var _a, _b, _c;
+    try {
+        const planner = await Promise.resolve().then(() => __importStar(require('./run/planner.js')));
+        const executor = await Promise.resolve().then(() => __importStar(require('./run/executor.js')));
+        const positionalArgv = rawCommandPositionals(command);
+        const format = (args.json || args.format === 'json') ? 'json' : 'text';
+        const planInput = {
+            cwd: process.cwd(),
+            argv: positionalArgv,
+            flags: runPlanFlagsFromCliArgs(args, format),
+            env: process.env,
+        };
+        const plan = command === 'build'
+            ? planner.createBuildPlan(planInput)
+            : planner.createRunPlan(planInput);
+        if (args['dry-run']) {
+            if (format === 'json') {
+                console.info(JSON.stringify(plan, null, 2));
+            }
+            else {
+                console.info(formatRunPlanText(plan, Boolean(args.explain), command));
+            }
+            process.exit(0);
+        }
+        const result = await executor.executeRunPlan(plan);
+        if (format === 'json') {
+            console.info(JSON.stringify(result, null, 2));
+        }
+        else if (result.status === 'reused') {
+            console.info(`hst ${command}: reusing ${(_a = result.appName) !== null && _a !== void 0 ? _a : 'app'} at ${(_b = result.url) !== null && _b !== void 0 ? _b : '(unknown URL)'}`);
+        }
+        else if (result.url) {
+            console.info(`hst ${command}: ${(_c = result.appName) !== null && _c !== void 0 ? _c : 'app'} available at ${result.url}`);
+        }
+    }
+    catch (err) {
+        console.error(`❌ ${command} failed`);
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+const NATIVE_PLATFORM_CHOICES = ['apple', 'ios', 'apple-tv', 'android', 'android-tv', 'all'];
+function nativeInputFromArgs(args) {
+    return {
+        cwd: process.cwd(),
+        platform: nativePlatformArg(args.platform),
+        app: stringArg(args.app),
+        displayName: stringArg(args['display-name']),
+        bundleId: stringArg(args['bundle-id']),
+        iosBundleId: stringArg(args['ios-bundle-id']),
+        appleTvBundleId: stringArg(args['apple-tv-bundle-id']),
+        androidPackage: stringArg(args['android-package']),
+        androidTvPackage: stringArg(args['android-tv-package']),
+        teamId: stringArg(args['team-id']),
+        versionName: stringArg(args['version-name']),
+        versionCode: numberOrStringArg(args['version-code']),
+        referenceRoot: stringArg(args['reference-root']),
+        replace: Boolean(args.replace),
+        dryRun: Boolean(args['dry-run']),
+        nonInteractive: Boolean(args['non-interactive']),
+    };
+}
+function nativePlatformArg(value) {
+    return typeof value === 'string' && value.trim()
+        ? value.trim()
+        : undefined;
+}
+function nativeFormatArg(args) {
+    return args.format === 'json' ? 'json' : 'text';
+}
+function stringArg(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function numberOrStringArg(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    return stringArg(value);
+}
 // Read build date, version, and git hash embedded at build time
 let buildDate = 'unknown';
 let buildVersion = 'unknown';
@@ -86,7 +232,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  run           Cross-platform launch orchestration\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 & 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`)
     .option('verbose', {
     type: 'boolean',
     default: false,
@@ -237,6 +383,112 @@ catch (err) {
         console.error(`Failed to resolve app config: ${message}`);
         process.exit(1);
     }
+})
+    .command('native:init [platform]', 'Initialize app-owned Hosanna native thin projects and config', yargs => yargs
+    .positional('platform', { type: 'string', choices: NATIVE_PLATFORM_CHOICES, default: 'all', describe: 'Native platform family to initialize' })
+    .option('app', { type: 'string', describe: 'App key/name used when inferring defaults' })
+    .option('display-name', { type: 'string', describe: 'Native display name' })
+    .option('bundle-id', { type: 'string', describe: 'Base bundle/package identifier' })
+    .option('ios-bundle-id', { type: 'string', describe: 'iOS bundle identifier' })
+    .option('apple-tv-bundle-id', { type: 'string', describe: 'tvOS bundle identifier' })
+    .option('android-package', { type: 'string', describe: 'Android namespace and phone package base' })
+    .option('android-tv-package', { type: 'string', describe: 'Android TV application id' })
+    .option('team-id', { type: 'string', describe: 'Apple development team id for generated xcconfig files' })
+    .option('version-name', { type: 'string', describe: 'Native marketing/versionName value' })
+    .option('version-code', { type: 'number', describe: 'Native build/versionCode value' })
+    .option('reference-root', { type: 'string', default: 'hosanna-ui', describe: 'Installed framework/runtime root inside the app repo' })
+    .option('replace', { type: 'boolean', default: false, describe: 'Replace unchanged hst-managed native template files' })
+    .option('dry-run', { type: 'boolean', default: false, describe: 'Print the native init plan without writing files' })
+    .option('format', { type: 'string', choices: ['text', 'json'], default: 'text', describe: 'Output format' })
+    .option('non-interactive', { type: 'boolean', default: false, describe: 'Fail instead of prompting when a decision is needed' })
+    .example('$0 native:init all --display-name "Hope Stream"', 'Initialize Apple and Android app-owned native projects')
+    .example('$0 native:init android-tv --dry-run --format json', 'Preview Android TV native setup as JSON'), async (args) => {
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require('./native/native-project.js')));
+        const input = nativeInputFromArgs(args);
+        const format = nativeFormatArg(args);
+        const plan = mod.createNativeInitPlan(input);
+        if (input.dryRun) {
+            console.info(format === 'json' ? JSON.stringify(plan, null, 2) : mod.formatNativeInitPlanText(plan));
+            process.exit(plan.errors.length > 0 ? 1 : 0);
+        }
+        const result = await mod.executeNativeInitPlan(plan);
+        if (format === 'json') {
+            console.info(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.info(`hst native:init applied for ${plan.requestedPlatforms.join(', ')}`);
+            console.info(mod.formatNativeInitPlanText(plan));
+        }
+        process.exit(0);
+    }
+    catch (err) {
+        console.error('❌ native:init failed');
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+})
+    .command('native:doctor [platform]', 'Validate Hosanna native platform setup and print actionable fixes', yargs => yargs
+    .positional('platform', { type: 'string', choices: NATIVE_PLATFORM_CHOICES, default: 'all', describe: 'Native platform family to validate' })
+    .option('app', { type: 'string', describe: 'App key/name used when inferring defaults' })
+    .option('display-name', { type: 'string', describe: 'Native display name' })
+    .option('bundle-id', { type: 'string', describe: 'Base bundle/package identifier' })
+    .option('ios-bundle-id', { type: 'string', describe: 'iOS bundle identifier' })
+    .option('apple-tv-bundle-id', { type: 'string', describe: 'tvOS bundle identifier' })
+    .option('android-package', { type: 'string', describe: 'Android namespace and phone package base' })
+    .option('android-tv-package', { type: 'string', describe: 'Android TV application id' })
+    .option('team-id', { type: 'string', describe: 'Apple development team id for generated xcconfig files' })
+    .option('version-name', { type: 'string', describe: 'Native marketing/versionName value' })
+    .option('version-code', { type: 'number', describe: 'Native build/versionCode value' })
+    .option('reference-root', { type: 'string', default: 'hosanna-ui', describe: 'Installed framework/runtime root inside the app repo' })
+    .option('replace', { type: 'boolean', default: false, describe: 'Plan replacement checks for unchanged hst-managed native files' })
+    .option('dry-run', { type: 'boolean', default: false, describe: 'Accepted for script parity; doctor never writes files' })
+    .option('format', { type: 'string', choices: ['text', 'json'], default: 'text', describe: 'Output format' })
+    .option('non-interactive', { type: 'boolean', default: false, describe: 'Fail instead of prompting when a decision is needed' })
+    .example('$0 native:doctor all --format json', 'Validate native setup as JSON'), async (args) => {
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require('./native/native-project.js')));
+        const report = mod.createNativeDoctorReport(nativeInputFromArgs(args));
+        const format = nativeFormatArg(args);
+        console.info(format === 'json' ? JSON.stringify(report, null, 2) : mod.formatNativeDoctorReportText(report));
+        process.exit(0);
+    }
+    catch (err) {
+        console.error('❌ native:doctor failed');
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+})
+    .command('native:prepare [platform]', 'Run lightweight Hosanna native prebuild validation', yargs => yargs
+    .positional('platform', { type: 'string', choices: NATIVE_PLATFORM_CHOICES, default: 'all', describe: 'Native platform family to prepare' })
+    .option('app', { type: 'string', describe: 'App key/name used when inferring defaults' })
+    .option('display-name', { type: 'string', describe: 'Native display name' })
+    .option('bundle-id', { type: 'string', describe: 'Base bundle/package identifier' })
+    .option('ios-bundle-id', { type: 'string', describe: 'iOS bundle identifier' })
+    .option('apple-tv-bundle-id', { type: 'string', describe: 'tvOS bundle identifier' })
+    .option('android-package', { type: 'string', describe: 'Android namespace and phone package base' })
+    .option('android-tv-package', { type: 'string', describe: 'Android TV application id' })
+    .option('team-id', { type: 'string', describe: 'Apple development team id for generated xcconfig files' })
+    .option('version-name', { type: 'string', describe: 'Native marketing/versionName value' })
+    .option('version-code', { type: 'number', describe: 'Native build/versionCode value' })
+    .option('reference-root', { type: 'string', default: 'hosanna-ui', describe: 'Installed framework/runtime root inside the app repo' })
+    .option('replace', { type: 'boolean', default: false, describe: 'Accepted for script parity; prepare never writes files' })
+    .option('dry-run', { type: 'boolean', default: false, describe: 'Accepted for script parity; prepare never writes files' })
+    .option('format', { type: 'string', choices: ['text', 'json'], default: 'text', describe: 'Output format' })
+    .option('non-interactive', { type: 'boolean', default: false, describe: 'Fail instead of prompting when a decision is needed' })
+    .example('$0 native:prepare ios', 'Validate native iOS setup before building'), async (args) => {
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require('./native/native-project.js')));
+        const result = await mod.prepareNativeProject(nativeInputFromArgs(args));
+        const format = nativeFormatArg(args);
+        console.info(format === 'json' ? JSON.stringify(result, null, 2) : mod.formatNativeDoctorReportText(result.report));
+        process.exit(0);
+    }
+    catch (err) {
+        console.error('❌ native:prepare failed');
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
 })
     .command('roku:package', 'Package and sign a Roku channel using roku-deploy. Flags fall back to env vars.', yargs => yargs
     .option('ip', { type: 'string', describe: 'Roku device IP (env: ROKU_IP)' })
@@ -1148,7 +1400,12 @@ catch (err) {
         process.exit(1);
     }
 })
-    .command('target:list', '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 previews, simulators, and physical devices', yargs => yargs
+    .positional('platform', {
+    type: 'string',
+    choices: ['web', 'roku', 'ios', 'apple-tv', 'android', 'android-tv'],
+    describe: 'Filter by launch platform',
+})
     .option('platform', {
     type: 'string',
     choices: ['web', 'roku', 'ios', 'apple-tv', 'android', 'android-tv'],
@@ -1156,7 +1413,7 @@ catch (err) {
 })
     .option('target', {
     type: 'string',
-    choices: ['web', 'device', 'simulator', 'emulator', 'simulated', 'emulated'],
+    choices: ['browser', 'web', 'device', 'simulator', 'emulator', 'simulated', 'emulated'],
     describe: 'Filter by target kind',
 })
     .option('form-factor', {
@@ -1168,9 +1425,15 @@ catch (err) {
     type: 'boolean',
     default: false,
     describe: 'Print machine-readable JSON',
+})
+    .option('format', {
+    type: 'string',
+    choices: ['text', 'json'],
+    default: 'text',
+    describe: 'Output format',
 })
     .example('$0 target:list --platform roku', 'List Roku web/device targets')
-    .example('$0 target:list --platform ios --target web --json', 'List the iOS web-runtime target as JSON')
+    .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 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')
@@ -1186,7 +1449,7 @@ catch (err) {
             formFactor: args['form-factor'],
         });
         const targets = await mod.collectRunTargets(Object.assign(Object.assign({ cwd: process.cwd() }, filters), { env: process.env }));
-        if (args.json) {
+        if (args.json || args.format === 'json') {
             console.info(JSON.stringify(mod.formatRunTargetsJson(targets), null, 2));
         }
         else {
@@ -1200,27 +1463,117 @@ catch (err) {
         process.exit(1);
     }
 })
-    .command('run', 'Launch a Hosanna app on a platform target (web, Roku, iOS, Apple TV, Android, and Android TV targets are supported)', yargs => yargs
-    .parserConfiguration({ 'boolean-negation': false })
+    .command('build [platform] [env] [target] [deviceSelector]', 'Build a Hosanna app for a platform target without launching, deploying, opening browsers, or streaming logs', yargs => yargs
+    .parserConfiguration({ 'boolean-negation': false, 'populate--': true })
+    .positional('platform', {
+    type: 'string',
+    describe: 'Build platform. Defaults from flags, env, .hosanna-tools/run.json, then web.',
+})
+    .positional('env', {
+    type: 'string',
+    describe: 'Build environment, e.g. dev, qa, or prod.',
+})
+    .positional('target', {
+    type: 'string',
+    describe: 'Target kind: browser, device, simulator, or emulator.',
+})
+    .positional('deviceSelector', {
+    type: 'string',
+    describe: 'Device IP, serial/UDID, AVD name, simulator name, or case-insensitive name substring.',
+})
     .option('platform', {
     type: 'string',
     choices: ['web', 'roku', 'ios', 'apple-tv', 'android', 'android-tv'],
-    demandOption: true,
-    describe: 'Launch platform. Required to keep agent runs deterministic.',
+    describe: 'Build platform.',
+})
+    .option('env', {
+    type: 'string',
+    describe: 'Build environment, e.g. dev, qa, or prod.',
 })
     .option('target', {
     type: 'string',
-    choices: ['web', 'device', 'simulator', 'emulator', 'simulated', 'emulated'],
-    describe: 'Target kind. Defaults to web for web/roku and native simulator/emulator targets for mobile/TV platforms.',
+    choices: ['browser', 'web', 'device', 'simulator', 'emulator', '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 web',
+    describe: 'Device IP, serial/UDID, case-insensitive name substring, or web preset id for --target browser',
 })
     .option('appName', {
     type: 'string',
     describe: 'App name used for debugger/session identity',
 })
+    .option('app', { type: 'string', describe: 'Run config app/flavor selector (env: HOSANNA_RUN_APP)' })
+    .option('profile', { type: 'string', describe: 'Build config profile (env: HS_BUILD_PROFILE)' })
+    .option('allow-profile-in-prod', { type: 'boolean', default: false, describe: 'Allow applying --profile with --env prod' })
+    .option('app-config', { type: 'string', describe: 'Runtime app config selector passed to web/native launch inputs' })
+    .option('hot-reload', { type: 'boolean', default: false, describe: 'Use native JS dev server where supported' })
+    .option('bundled', { type: 'boolean', default: false, describe: 'Use bundled native JS/assets where supported' })
+    .option('vitePort', { type: 'number', description: 'Port for Vite dev server', default: 5173 })
+    .option('webAppPort', { type: 'number', description: 'Port for web app debugger client', default: 59151 })
+    .option('deviceAppPort', { type: 'number', description: 'Port for device app debugger client', default: 59152 })
+    .option('extensionPort', { type: 'number', description: 'Debugger extension WebSocket port', default: 59153 })
+    .option('managementPort', { type: 'number', description: 'Debugger management HTTP port', default: 59150 })
+    .option('non-interactive', { type: 'boolean', default: false, describe: 'Fail instead of prompting when a decision is needed' })
+    .option('json', { type: 'boolean', default: false, describe: 'Print build result as JSON when the command returns' })
+    .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('hsc-project', { type: 'string', describe: 'Explicit Roku HSC project file for hst build planning' })
+    .option('config', { type: 'string', describe: 'Alias for --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) => {
+    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
+    .parserConfiguration({ 'boolean-negation': false, 'populate--': true })
+    .positional('platform', {
+    type: 'string',
+    describe: 'Launch platform. Defaults from flags, env, .hosanna-tools/run.json, then web.',
+})
+    .positional('env', {
+    type: 'string',
+    describe: 'Build environment, e.g. dev, qa, or prod.',
+})
+    .positional('target', {
+    type: 'string',
+    describe: 'Target kind: browser, device, simulator, or emulator.',
+})
+    .positional('deviceSelector', {
+    type: 'string',
+    describe: 'Device IP, serial/UDID, AVD name, simulator name, or case-insensitive name substring.',
+})
+    .option('platform', {
+    type: 'string',
+    choices: ['web', 'roku', 'ios', 'apple-tv', 'android', 'android-tv'],
+    describe: 'Launch platform.',
+})
+    .option('env', {
+    type: 'string',
+    describe: 'Build environment, e.g. dev, qa, or prod.',
+})
+    .option('target', {
+    type: 'string',
+    choices: ['browser', 'web', 'device', 'simulator', 'emulator', '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',
+})
+    .option('appName', {
+    type: 'string',
+    describe: 'App name used for debugger/session identity',
+})
+    .option('app', { type: 'string', describe: 'Run config app/flavor selector (env: HOSANNA_RUN_APP)' })
+    .option('profile', { type: 'string', describe: 'Build config profile (env: HS_BUILD_PROFILE)' })
+    .option('allow-profile-in-prod', { type: 'boolean', default: false, describe: 'Allow applying --profile with --env prod' })
+    .option('app-config', { type: 'string', describe: 'Runtime app config selector passed to web/native launch inputs' })
+    .option('hot-reload', { type: 'boolean', default: false, describe: 'Use native JS dev server where supported' })
+    .option('bundled', { type: 'boolean', default: false, describe: 'Use bundled native JS/assets where supported' })
     .option('vitePort', { type: 'number', description: 'Port for Vite dev server', default: 5173 })
     .option('webAppPort', { type: 'number', description: 'Port for web app debugger client', default: 59151 })
     .option('deviceAppPort', { type: 'number', description: 'Port for device app debugger client', default: 59152 })
@@ -1232,74 +1585,39 @@ catch (err) {
     .option('no-open', { type: 'boolean', default: false, describe: 'Do not open the default browser for web runtime launches' })
     .option('non-interactive', { type: 'boolean', default: false, describe: 'Fail instead of prompting when a decision is needed' })
     .option('json', { type: 'boolean', default: false, describe: 'Print run result as JSON when the command returns' })
+    .option('dry-run', { type: 'boolean', default: false, describe: 'Print the resolved RunPlan without executing it' })
+    .option('format', { type: 'string', choices: ['text', 'json'], default: 'text', describe: 'Output format for --dry-run and run result' })
+    .option('explain', { type: 'boolean', default: false, describe: 'Include resolution source details in text dry-run output' })
     .option('no-build', { type: 'boolean', default: false, describe: 'Skip the platform build step for device runs' })
+    .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('hsc-project', { type: 'string', describe: 'Explicit Roku HSC project file for hst run planning' })
+    .option('config', { type: 'string', describe: 'Alias for --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' })
     .option('files', { type: 'array', describe: 'Roku file globs when deploying a folder' })
+    .option('deploy-timeout-ms', { type: 'number', describe: 'Roku deploy request timeout in milliseconds' })
     .option('installer-password', { type: 'string', describe: 'Roku installer password (env: ROKU_DEVPASSWORD)' })
     .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 web', 'Start/reuse the Roku TV web preview')
-    .example('$0 run --platform ios --target web', 'Start/reuse the iPhone-shaped web runtime profile')
-    .example('$0 run --platform android --target web --device pixel-8', 'Start/reuse the Android-shaped web runtime profile')
-    .example('$0 run --platform apple-tv --target web --no-open', 'Start/reuse the Apple TV web runtime profile without opening a browser')
-    .example('$0 run --platform android-tv --target web', 'Start/reuse the Android TV web runtime profile')
+    .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 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 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 roku --target device --device "living room"', 'Build, deploy, launch, and stream logs on a Roku device'), async (args) => {
-    var _a, _b, _c;
-    try {
-        const mod = await Promise.resolve().then(() => __importStar(require('./run/run-controller.js')));
-        const result = await mod.runHosanna({
-            cwd: process.cwd(),
-            platform: args.platform,
-            target: args.target,
-            device: args.device,
-            appName: args.appName,
-            vitePort: args.vitePort,
-            webAppPort: args.webAppPort,
-            deviceAppPort: args.deviceAppPort,
-            extensionPort: args.extensionPort,
-            managementPort: args.managementPort,
-            reuse: Boolean(args.reuse),
-            replace: Boolean(args.replace),
-            open: args['no-open'] ? false : args.open === true ? true : undefined,
-            nonInteractive: Boolean(args['non-interactive']),
-            noBuild: Boolean(args['no-build']),
-            noLogs: Boolean(args['no-logs']),
-            buildCmd: args['build-cmd'],
-            appPackage: args['app-package'],
-            sourceRoot: args['source-root'],
-            sourceMapRoot: args['source-map-root'],
-            files: args.files,
-            installerPassword: args['installer-password'],
-            logs: Boolean(args.logs),
-            applySourceMapToPaths: Boolean(args.applySourceMapToPaths),
-            env: process.env,
-        });
-        if (args.json) {
-            console.info(JSON.stringify(result, null, 2));
-        }
-        else if (result.status === 'reused') {
-            console.info(`hst run: reusing ${(_a = result.appName) !== null && _a !== void 0 ? _a : 'app'} at ${(_b = result.url) !== null && _b !== void 0 ? _b : '(unknown URL)'}`);
-        }
-        else if (result.url) {
-            console.info(`hst run: ${(_c = result.appName) !== null && _c !== void 0 ? _c : 'app'} available at ${result.url}`);
-        }
-    }
-    catch (err) {
-        console.error('❌ run failed');
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    .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) => {
+    await runRunPlanCommand('run', args);
 })
     .command('device:run', 'Build, deploy, launch, and stream logs for a device', yargs => yargs
     .parserConfiguration({ 'boolean-negation': false })
@@ -1409,6 +1727,16 @@ catch (err) {
     type: 'boolean',
     default: false,
     describe: 'Connect to telnet and pipe Roku device log output to terminal. In log mode, press r to redeploy (use --log-output, not --log-output true)'
+})
+    .option('deploy-timeout-ms', {
+    type: 'number',
+    default: 30000,
+    describe: 'Roku deploy request timeout in milliseconds'
+})
+    .option('log-connect-timeout-ms', {
+    type: 'number',
+    default: 10000,
+    describe: 'Roku telnet log connection timeout in milliseconds'
 })
     .option('applySourceMapToPaths', {
     type: 'boolean',
@@ -1450,6 +1778,8 @@ catch (err) {
             logs: Boolean(args.logs),
             logOutput: Boolean(args['log-output']),
             applySourceMapToPaths: Boolean(args['applySourceMapToPaths']),
+            deployTimeoutMs: args['deploy-timeout-ms'],
+            logConnectTimeoutMs: args['log-connect-timeout-ms'],
             dotenv: true,
         });
         process.exit(0);