@tantawowa/hosanna-tools 2.22.0 → 2.23.0

package/dist/cli.js

@@ -57,10 +57,9 @@ function parseGenerationMode(mode) {
 const compiler_installer_js_1 = require("./updater/compiler-installer.js");
 const generation_utils_js_2 = require("./generation/generation-utils.js");
 const env_info_js_1 = require("./lib/env-info.js");
-const cli_configure_hosanna_url_js_1 = require("./lib/cli.configure-hosanna-url.js");
 const hosanna_tools_utils_js_1 = require("./lib/hosanna-tools-utils.js");
-const env_cloud_agent_setup_help_js_1 = require("./lib/env-cloud-agent-setup-help.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");
 // Read build date, version, and git hash embedded at build time
 let buildDate = 'unknown';
 let buildVersion = 'unknown';
@@ -87,18 +86,18 @@ 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  run:*        Development execution (dev, roku, debugger, mcp)\n  stop:mcp     Stop the Hosanna MCP server (PID lock; alias: run:stop)\n  roku:*       Roku deployment & packaging (run, package)\n  generate:*   Code generation (structs, clean)\n  install:*    Setup & installation (compiler, template)\n  build-config Build/runtime configuration resolution\n  ci:*         Continuous integration (extract-pkg-key)\n  secrets:*    Portable .secrets (list, check, exec, init)\n  test:*       UI testing (replay recordings, visual regression)\n  rasp:*       RASP cert scripts (capture, export, validate)\n  env:*        Environment management (prepare-gitignore, cloud-agent-setup)`)
+    .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`)
     .option('verbose', {
     type: 'boolean',
     default: false,
     describe: 'Enable verbose logging for all operations',
     global: true
 })
-    .command('game prep-level <input>', 'Normalize a Tiled JSON map into the Hs2d canonical runtime subset', yargs => yargs
+    .command('game:prep-level <input>', 'Normalize a Tiled JSON map into the Hs2d canonical runtime subset', yargs => yargs
     .positional('input', { type: 'string', demandOption: true, describe: 'Path to a Tiled .json/.tmj map export' })
     .option('out', { alias: 'o', type: 'string', describe: 'Output path (defaults to overwriting the input file)' })
     .option('pretty', { type: 'boolean', default: false, describe: 'Pretty-print the output JSON (device payloads default to compact)' })
-    .example('$0 game prep-level levels/level-1.json -o asset-bundles/my-game/levels/level-1.json', 'Decode/normalize a Tiled export into an asset bundle')
+    .example('$0 game:prep-level levels/level-1.json -o asset-bundles/my-game/levels/level-1.json', 'Decode/normalize a Tiled export into an asset bundle')
     .epilog([
     'Converts what Tiled produces into what the Hs2d device parser reads:',
     '  - decodes base64 (+zlib/gzip) tile data into plain arrays',
@@ -128,7 +127,7 @@ catch (err) {
         process.exit(1);
     }
 })
-    .command('build-config resolve', 'Resolve Hosanna build config overlays into the canonical runtime build-config.json', yargs => yargs
+    .command('build-config:resolve', 'Resolve Hosanna build config overlays into the canonical runtime build-config.json', yargs => yargs
     .option('env', { type: 'string', describe: 'Environment, e.g. dev, qa, or prod (or HS_ENV / HOSANNA_BUILD_ENV)' })
     .option('platform', { type: 'string', describe: 'Platform, e.g. web, roku, android, apple, or ios (or HS_PLATFORM / HOSANNA_BUILD_PLATFORM)' })
     .option('profile', { type: 'string', describe: 'Optional explicit local developer profile (or HS_BUILD_PROFILE)' })
@@ -137,9 +136,9 @@ catch (err) {
     .option('manifest-out', { type: 'string', describe: 'Write a sanitized source manifest to this file' })
     .option('explain', { type: 'boolean', default: false, describe: 'Print source summary without secret values' })
     .option('allow-profile-in-prod', { type: 'boolean', default: false, describe: 'Allow applying --profile with --env prod (or HS_ALLOW_PROFILE_IN_PROD=true)' })
-    .example('$0 build-config resolve --env dev --platform web --format json', 'Resolve dev web config to stdout')
-    .example('HS_ENV=dev HS_PLATFORM=roku $0 build-config resolve --out assets/meta/build-config.json', 'Resolve config from env-prefixed shell arguments')
-    .example('$0 build-config resolve --env prod --platform roku --out assets/meta/build-config.json', 'Resolve prod Roku config to a runtime file')
+    .example('$0 build-config:resolve --env dev --platform web --format json', 'Resolve dev web config to stdout')
+    .example('HS_ENV=dev HS_PLATFORM=roku $0 build-config:resolve --out assets/meta/build-config.json', 'Resolve config from env-prefixed shell arguments')
+    .example('$0 build-config:resolve --env prod --platform roku --out assets/meta/build-config.json', 'Resolve prod Roku config to a runtime file')
     .epilog([
     'Environment fallbacks:',
     '  --env: HS_ENV or HOSANNA_BUILD_ENV',
@@ -211,7 +210,7 @@ catch (err) {
         process.exit(1);
     }
 })
-    .command(['version', 'v'], 'Print the version number', yargs => yargs, () => {
+    .command('version', 'Print the version number', yargs => yargs, () => {
     console.log(buildVersion);
     console.log(`  git: ${buildGitHash}`);
     console.log(`  built: ${buildDate}`);
@@ -317,50 +316,6 @@ catch (err) {
         console.error(`❌ Failed to map Roku stack trace: ${msg}`);
         process.exit(1);
     }
-})
-    .command('publish-roku', '[DEPRECATED] Use "roku:package" instead. 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)' })
-    .option('installer-password', { type: 'string', describe: 'Dev Application Installer password (env: ROKU_DEVPASSWORD)' })
-    .option('dev-id', { type: 'string', describe: 'Signing Developer ID (env: ROKU_DEV_ID)' })
-    .option('signing-password', { type: 'string', describe: 'Signing password (env: ROKU_DEV_PASSWORD)' })
-    .option('key-pkg', { type: 'string', describe: 'Path or filename of the signed key package (.pkg) (env: ROKU_PKG_NAME)' })
-    .option('key-pkg-base64', { type: 'string', describe: 'Base64-encoded signed key package (.pkg) (env: ROKU_PKG_KEY_BASE64)' })
-    .option('env', { type: 'string', choices: ['prod', 'dev'], default: 'prod', describe: 'Used in output naming; does not modify project config' })
-    .option('rootDir', { type: 'string', describe: 'Roku project root (default: ./platforms/roku/src)' })
-    .option('outDir', { type: 'string', describe: 'Output directory (default: ./build)' })
-    .option('prebuild', { type: 'string', describe: 'Shell command to run before packaging (e.g. "npm run transpile:prod")' })
-    .option('quiet', { type: 'boolean', default: false, describe: 'Reduce output; print only errors and success' })
-    .example('$0 publish-roku --ip 192.168.1.10', '[DEPRECATED] Use "roku:package" instead'), async (args) => {
-    console.warn('⚠️  DEPRECATED: The command "publish-roku" is deprecated. Use "roku:package" instead.');
-    console.warn('   This command will be removed in a future version.');
-    if (args.verbose) {
-        process.env.HOSANNA_VERBOSE = '1';
-        process.env.HOSANNA_UPDATER_VERBOSE = '1';
-    }
-    try {
-        const mod = await Promise.resolve().then(() => __importStar(require('./support-tools/publish-roku.js')));
-        const res = await mod.publishRoku({
-            ip: args.ip,
-            installerPassword: args['installer-password'],
-            devId: args['dev-id'],
-            signingPassword: args['signing-password'],
-            keyPkg: args['key-pkg'],
-            keyPkgBase64: args['key-pkg-base64'],
-            env: args.env,
-            rootDir: args.rootDir,
-            outDir: args.outDir,
-            prebuild: args.prebuild,
-            quiet: Boolean(args.quiet),
-            dotenv: true,
-        });
-        if (!args.quiet)
-            console.info(`✅ Success: ${res.outPath}`);
-        process.exit(0);
-    }
-    catch (err) {
-        console.error('❌ Failed to publish Roku package:', err);
-        process.exit(1);
-    }
 })
     .command('ci:extract-pkg-key <input-pkg>', 'Extract signing key from an existing signed Roku package as base64 for CI use', yargs => yargs
     .positional('input-pkg', { type: 'string', describe: 'Path to existing signed Roku package (.pkg) file to extract key from' })
@@ -514,24 +469,46 @@ catch (err) {
     }
 })
     // remove old --env flag; env is now a subcommand
-    .command('env', 'Print environment information and run checks. Use --fix to auto-correct SDK, compiler, and tools version mismatches.', yargs => yargs
-    .option('fix', { type: 'boolean', default: false, describe: 'Auto-fix SDK, compiler, and tools version mismatches' }), async (args) => {
+    .command('config [action]', 'Show or update hosanna.json configuration from a curated catalog', yargs => yargs
+    .positional('action', {
+    type: 'string',
+    choices: ['show', 'set', 'wizard'],
+    describe: 'show prints current config, set writes values from flags, wizard runs the interactive setup',
+})
+    .option('git-url', { type: 'string', describe: 'Set hosanna.json git-url' })
+    .option('sdk-version', { type: 'string', describe: 'Set hosanna.json sdk-version' })
+    .option('branch', { type: 'string', describe: 'Set hosanna.json branch; use an empty string to prefer sdk-version' })
+    .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('fix', { type: 'boolean', default: false, describe: 'Run hst env fix after updating config' }), async (args) => {
     if (args.verbose) {
         process.env.HOSANNA_VERBOSE = '1';
         process.env.HOSANNA_UPDATER_VERBOSE = '1';
     }
-    const info = (0, env_info_js_1.collectEnvInfo)(process.cwd());
-    const report = (0, env_info_js_1.formatEnvReportWithChecks)(info);
-    console.info(report);
-    if (args.fix) {
-        // Handle comprehensive auto-fix
-        const { fixAllEnvironmentIssues } = await Promise.resolve().then(() => __importStar(require('./lib/env-info.js')));
-        const ok = (0, env_info_js_1.allEnvChecksPass)(info);
-        if (ok) {
-            console.info('\n✅ All environment checks passed - no fixes needed.');
-        }
-        else {
-            console.info('');
+    const actionArg = typeof args.action === 'string' ? args.action : undefined;
+    const action = actionArg === 'show' || actionArg === 'set' ? actionArg : 'wizard';
+    const updates = {};
+    if (typeof args.gitUrl === 'string')
+        updates['git-url'] = args.gitUrl;
+    if (typeof args.sdkVersion === 'string')
+        updates['sdk-version'] = args.sdkVersion;
+    if (typeof args.branch === 'string')
+        updates.branch = args.branch;
+    if (typeof args.transpilerVersion === 'string')
+        updates['transpiler-version'] = args.transpilerVersion;
+    if (typeof args.configCatalogUrl === 'string')
+        updates['config-catalog-url'] = args.configCatalogUrl;
+    try {
+        const result = await (0, hosanna_config_js_1.runHosannaConfig)({
+            action,
+            cwd: process.cwd(),
+            catalogUrl: typeof args.catalogUrl === 'string' ? args.catalogUrl : undefined,
+            updates,
+            writeStdout: text => console.info(text),
+        });
+        if ((args.fix || result.runFix) && action !== 'show') {
+            const { fixAllEnvironmentIssues } = await Promise.resolve().then(() => __importStar(require('./lib/env-info.js')));
             const fixResult = await fixAllEnvironmentIssues(process.cwd());
             console.info(`\n${fixResult.message}`);
             if (fixResult.remainingIssues.length > 0) {
@@ -540,60 +517,77 @@ catch (err) {
                     console.info(`   • ${issue}`);
                 }
             }
-            // If fixes were successful with no remaining issues, exit with success
-            // Don't rely on immediate re-check which may fail due to timing (npm install, PATH refresh, etc.)
-            if (fixResult.success && fixResult.remainingIssues.length === 0) {
-                // Fixes completed successfully - exit with 0 regardless of re-check
-                if (!process.env.VITEST) {
-                    process.exit(0);
-                }
-                return; // Exit early since we handled the exit
-            }
-            // If there were remaining issues or fixes didn't complete successfully,
-            // re-check to see current state and exit accordingly
-            const updatedInfo = (0, env_info_js_1.collectEnvInfo)(process.cwd());
-            const updatedOk = (0, env_info_js_1.allEnvChecksPass)(updatedInfo);
-            if (!process.env.VITEST) {
-                process.exit(updatedOk ? 0 : 1);
-            }
-            return; // Exit early since we handled the exit
+            if (!process.env.VITEST)
+                process.exit(fixResult.success ? 0 : 1);
+            return;
         }
+        if (!process.env.VITEST)
+            process.exit(0);
     }
-    const ok = (0, env_info_js_1.allEnvChecksPass)(info);
-    if (!process.env.VITEST) {
-        process.exit(ok ? 0 : 1);
+    catch (err) {
+        console.error('❌ Failed to configure hosanna.json:', err instanceof Error ? err.message : err);
+        if (!process.env.VITEST)
+            process.exit(1);
     }
 })
-    .command('env:cloud-agent-setup', 'Restore debug flags, patch remoteDebug for agents, optionally start debugger and npm dev (see --help for Cursor Cloud Agents)', yargs => yargs
-    .option('output-dir', { type: 'string', describe: 'Directory for cloud-agent.json build config profile (default: build-config/profiles)' })
-    .option('start-debugger', { type: 'boolean', default: false, describe: 'Start command debugger in-process (non-blocking)' })
-    .option('start-app', { type: 'boolean', default: false, describe: 'Spawn npm run dev detached and wait for Vite port' })
-    .option('vite-port', { type: 'number', default: 5173, describe: 'Port to wait on when --start-app is set' })
-    .option('format', { type: 'string', choices: ['text', 'json'], default: 'text', describe: 'Summary format' })
-    .example('$0 env:cloud-agent-setup --start-debugger --start-app', 'Full bootstrap for a cloud agent')
-    .epilog(env_cloud_agent_setup_help_js_1.ENV_CLOUD_AGENT_SETUP_EPILOG), async (args) => {
+    .command('env <action>', 'Check or repair the local Hosanna environment', yargs => yargs
+    .positional('action', {
+    type: 'string',
+    choices: ['check', 'fix', 'prepare-gitignore'],
+    describe: 'check prints environment status, fix repairs version mismatches, prepare-gitignore updates .gitignore',
+}), async (args) => {
     if (args.verbose) {
         process.env.HOSANNA_VERBOSE = '1';
         process.env.HOSANNA_UPDATER_VERBOSE = '1';
     }
-    try {
-        const mod = await Promise.resolve().then(() => __importStar(require('./support-tools/cloud-agent-setup.js')));
-        await mod.runCloudAgentSetup({
-            cwd: process.cwd(),
-            outputDir: args['output-dir'],
-            startDebugger: Boolean(args['start-debugger']),
-            startApp: Boolean(args['start-app']),
-            vitePort: args['vite-port'],
-            format: args.format,
-        });
-        process.exit(0);
+    if (args.action === 'prepare-gitignore') {
+        console.info('Preparing .gitignore...');
+        (0, sdk_manager_js_1.prepareGitIgnore)();
+        console.info('.gitignore preparation completed.');
+        return;
     }
-    catch (err) {
-        console.error('❌ env:cloud-agent-setup failed:', err);
-        process.exit(1);
+    const info = (0, env_info_js_1.collectEnvInfo)(process.cwd());
+    const report = (0, env_info_js_1.formatEnvReportWithChecks)(info);
+    console.info(report);
+    const ok = (0, env_info_js_1.allEnvChecksPass)(info);
+    if (args.action === 'check') {
+        if (!process.env.VITEST) {
+            process.exit(ok ? 0 : 1);
+        }
+        return;
+    }
+    if (ok) {
+        console.info('\n✅ All environment checks passed - no fixes needed.');
+    }
+    else {
+        const { fixAllEnvironmentIssues } = await Promise.resolve().then(() => __importStar(require('./lib/env-info.js')));
+        console.info('');
+        const fixResult = await fixAllEnvironmentIssues(process.cwd());
+        console.info(`\n${fixResult.message}`);
+        if (fixResult.remainingIssues.length > 0) {
+            console.info('\n❌ Remaining issues:');
+            for (const issue of fixResult.remainingIssues) {
+                console.info(`   • ${issue}`);
+            }
+        }
+        if (fixResult.success && fixResult.remainingIssues.length === 0) {
+            if (!process.env.VITEST) {
+                process.exit(0);
+            }
+            return;
+        }
+        const updatedInfo = (0, env_info_js_1.collectEnvInfo)(process.cwd());
+        const updatedOk = (0, env_info_js_1.allEnvChecksPass)(updatedInfo);
+        if (!process.env.VITEST) {
+            process.exit(updatedOk ? 0 : 1);
+        }
+        return;
+    }
+    if (!process.env.VITEST) {
+        process.exit(0);
     }
 })
-    .command('run:debugger', 'Start the command debugger WebSocket proxy', yargs => yargs
+    .command('debugger:start', 'Start the command debugger WebSocket proxy', yargs => yargs
     .option('webAppPort', { type: 'number', description: 'Port for web app client', default: 59151 })
     .option('deviceAppPort', { type: 'number', description: 'Port for device app client', default: 59152 })
     .option('extensionPort', { type: 'number', description: 'Port for extension client', default: 59153 })
@@ -611,14 +605,14 @@ catch (err) {
     const { checkExistingDebugger } = await Promise.resolve().then(() => __importStar(require('./lib/debugger-probe.js')));
     const { checkPortInUse } = await Promise.resolve().then(() => __importStar(require('./lib/port-utils.js')));
     if (await checkExistingDebugger(managementPort)) {
-        console.log('[run:debugger] Command debugger is already running at http://localhost:' + managementPort);
-        console.log('[run:debugger] Your apps can connect via the management API (/assign-port). No need to start another debugger.');
+        console.log('[debugger:start] Command debugger is already running at http://localhost:' + managementPort);
+        console.log('[debugger:start] Your apps can connect via the management API (/assign-port). No need to start another debugger.');
         process.exit(0);
     }
     // TCP fallback: if management port is in use (e.g. debugger still starting, HTTP not ready), assume debugger is running
     if (await checkPortInUse(managementPort)) {
-        console.log('[run:debugger] Debugger port ' + managementPort + ' is in use — a debugger is already running.');
-        console.log('[run:debugger] Not starting a debugger server. Your apps can connect via the management API (/assign-port).');
+        console.log('[debugger:start] Debugger port ' + managementPort + ' is in use — a debugger is already running.');
+        console.log('[debugger:start] Not starting a debugger server. Your apps can connect via the management API (/assign-port).');
         process.exit(0);
     }
     // Check if any required ports are already in use (e.g. another process on our ports)
@@ -635,11 +629,11 @@ catch (err) {
         }
     }
     if (portsInUse.length > 0) {
-        console.error('[run:debugger] ❌ Error: One or more ports are already in use:');
+        console.error('[debugger:start] ❌ Error: One or more ports are already in use:');
         for (const { port, name } of portsInUse) {
-            console.error(`[run:debugger]    • Port ${port} (${name})`);
+            console.error(`[debugger:start]    • Port ${port} (${name})`);
         }
-        console.error('[run:debugger] Please free these ports or use different ports (e.g. --deviceAppPort 59156) and try again.');
+        console.error('[debugger:start] Please free these ports or use different ports (e.g. --deviceAppPort 59156) and try again.');
         process.exit(1);
     }
     const { startCommandDebugger } = await Promise.resolve().then(() => __importStar(require('./support-tools/command-debugger.js')));
@@ -651,8 +645,8 @@ catch (err) {
         defaultAppName: typeof args.appName === 'string' && args.appName.trim() !== '' ? args.appName.trim() : undefined,
     });
 })
-    .command('install:compiler [version]', 'Install or update the Hosanna compiler (hsc) locally. Downloads to /tmp cache and installs to ./bin/hsc. If [version] is omitted, uses hosanna.json transpiler-version.', yargs => yargs
-    .positional('version', { type: 'string', describe: 'hsc version (x.y.z). Overrides hosanna.json when provided.' })
+    .command('compiler:install [compilerVersion]', 'Install or update the Hosanna compiler (hsc) locally. Downloads to /tmp cache and installs to ./bin/hsc. If [compilerVersion] is omitted, uses hosanna.json transpiler-version.', yargs => yargs
+    .positional('compilerVersion', { type: 'string', describe: 'hsc version (x.y.z). Overrides hosanna.json when provided.' })
     .option('force', { type: 'boolean', default: false, describe: 'Force install even if version matches or compiler is npm-installed' })
     .option('sudo', { type: 'boolean', default: false, describe: 'If needed, use sudo for file operations (legacy option, rarely needed)' }), async (args) => {
     if (args.verbose) {
@@ -660,9 +654,9 @@ catch (err) {
         process.env.HOSANNA_UPDATER_VERBOSE = '1';
     }
     let version;
-    const provided = args.version;
+    const provided = args.compilerVersion;
     if (typeof provided === 'string') {
-        const trimmed = provided.trim();
+        const trimmed = provided.trim().replace(/^v(?=\d+\.\d+\.\d+)/, '');
         version = trimmed.length > 0 ? trimmed : undefined;
     }
     try {
@@ -699,17 +693,51 @@ catch (err) {
         process.exit(1);
     }
 })
-    .command('generate', 'Generate structs and command handler maps', yargs => yargs
+    .command('compiler:status', 'Print local Hosanna compiler status for this project', yargs => yargs.option('format', { type: 'string', choices: ['text', 'json'], default: 'text', describe: 'Output format' }), args => {
+    var _a;
+    const status = (0, compiler_installer_js_1.getCompilerStatus)(process.cwd());
+    if (args.format === 'json') {
+        console.log(JSON.stringify(status, null, 2));
+    }
+    else {
+        console.info('Hosanna compiler status:');
+        console.info(`  configured: ${(_a = status.configuredVersion) !== null && _a !== void 0 ? _a : '(not set)'}`);
+        console.info(`  installed:  ${status.installed ? status.installType : 'missing'}`);
+        if (status.installedVersion)
+            console.info(`  version:    ${status.installedVersion}`);
+        console.info(`  path:       ${status.installedPath}`);
+        console.info(`  matches:    ${status.matchesConfigured === undefined ? '(not applicable)' : status.matchesConfigured ? 'yes' : 'no'}`);
+        console.info(`  cache:      ${status.cacheDir}`);
+        console.info(`  cached:     ${status.cachedVersions.length ? status.cachedVersions.join(', ') : '(none)'}`);
+    }
+    process.exit(status.configuredVersion && status.matchesConfigured === false ? 1 : 0);
+})
+    .command('compiler:list', 'List compiler versions known locally from hosanna.json, bin/hsc, and the local hsc cache', yargs => yargs.option('format', { type: 'string', choices: ['text', 'json'], default: 'text', describe: 'Output format' }), args => {
+    const entries = (0, compiler_installer_js_1.listCompilerVersions)(process.cwd());
+    if (args.format === 'json') {
+        console.log(JSON.stringify(entries, null, 2));
+    }
+    else if (entries.length === 0) {
+        console.info('No local compiler versions found.');
+    }
+    else {
+        for (const entry of entries) {
+            console.info(`${entry.version} (${entry.sources.join(', ')})`);
+        }
+    }
+    process.exit(0);
+})
+    .command('generate:all', 'Generate structs and command handler maps', yargs => yargs
     .option('watch', { type: 'boolean', description: 'Watch for file changes' })
     .option('rootFolder', { type: 'string', description: 'Root folder for the operation (defaults to ./src)' })
     .option('generatedFolder', { type: 'string', description: 'Folder to output generated files (defaults to src-generated)' })
     .option('quiet', { type: 'boolean', description: 'Reduce output; print only errors and success', default: false })
     .option('mode', { type: 'string', choices: ['runtime', 'types', 'both'], default: 'runtime', description: 'Generate runtime .ts, types .d.ts+.map, or both' })
     .option('fileFilter', { type: 'string', description: 'Regex pattern to filter filenames (applied to relative paths from rootFolder)' })
-    .example('$0 generate --rootFolder ./src', 'Generate structs and command handler maps for the specified root folder')
-    .example('$0 generate --watch', 'Generate structs and command handler maps and watch for file changes')
-    .example('$0 generate --generatedFolder ./gen', 'Generate structs and command handler maps in ./gen folder')
-    .example('$0 generate --fileFilter "Button"', 'Generate structs only for files containing "Button" in their path'), args => {
+    .example('$0 generate:all --rootFolder ./src', 'Generate structs and command handler maps for the specified root folder')
+    .example('$0 generate:all --watch', 'Generate structs and command handler maps and watch for file changes')
+    .example('$0 generate:all --generatedFolder ./gen', 'Generate structs and command handler maps in ./gen folder')
+    .example('$0 generate:all --fileFilter "Button"', 'Generate structs only for files containing "Button" in their path'), args => {
     const rootFolder = args.rootFolder ? path.resolve(args.rootFolder) : path.resolve(process.cwd(), 'src');
     const generatedFolder = args.generatedFolder ? path.resolve(args.generatedFolder) : path.resolve(process.cwd(), 'src-generated');
     if (args.quiet) {
@@ -906,40 +934,154 @@ catch (err) {
         process.exit(1);
     }
 })
-    .command('env:prepare-gitignore', 'Ensure .gitignore contains required entries', yargs => yargs, (args) => {
+    .command('sdk:install', 'Install the SDK. Uses git (hosanna.json git-url) or license-gated keygen artifacts (hosanna.json "distribution": "keygen")', yargs => yargs
+    .option('force', { type: 'boolean', default: false, describe: 'Reinstall even if the requested version is already installed (keygen mode)' }), async (args) => {
     if (args.verbose) {
         process.env.HOSANNA_VERBOSE = '1';
         process.env.HOSANNA_UPDATER_VERBOSE = '1';
     }
-    console.info('Preparing .gitignore...');
-    (0, sdk_manager_js_1.prepareGitIgnore)();
-    console.info('.gitignore preparation completed.');
+    console.info('Running sdk:install command...');
+    try {
+        // Keygen-distributed projects bypass the git flow entirely.
+        const hosannaJsonPath = path.resolve(process.cwd(), 'hosanna.json');
+        let distribution;
+        if (fs.existsSync(hosannaJsonPath)) {
+            try {
+                distribution = JSON.parse(fs.readFileSync(hosannaJsonPath, 'utf-8')).distribution;
+            }
+            catch ( /* fall through to git flow which reports config errors */_a) { /* fall through to git flow which reports config errors */ }
+        }
+        if (distribution === 'keygen') {
+            const mod = await Promise.resolve().then(() => __importStar(require('./updater/framework-installer.js')));
+            await mod.installFrameworkFromKeygen({ force: Boolean(args.force) });
+        }
+        else {
+            await (0, sdk_manager_js_1.installSdk)(); // Ensure installSdk is awaited
+        }
+        console.info('sdk:install command completed.');
+        process.exit(0); // Exit after successful completion
+    }
+    catch (err) {
+        console.error('An error occurred during the install process:', err);
+        process.exit(1); // Exit with error code on failure
+    }
 })
-    .command('install', 'Install the SDK by creating hosanna.json and setting up the environment', yargs => yargs, async (args) => {
+    .command('framework:update', 'Update the keygen-distributed hosanna-ui folder to the version in hosanna.json (no-op when already current)', yargs => yargs
+    .option('force', { type: 'boolean', default: false, describe: 'Reinstall even if the requested version is already installed' }), async (args) => {
     if (args.verbose) {
         process.env.HOSANNA_VERBOSE = '1';
         process.env.HOSANNA_UPDATER_VERBOSE = '1';
     }
-    console.info('Running install-sdk command...');
     try {
-        await (0, sdk_manager_js_1.installSdk)(); // Ensure installSdk is awaited
-        console.info('install-sdk command completed.');
-        process.exit(0); // Exit after successful completion
+        const mod = await Promise.resolve().then(() => __importStar(require('./updater/framework-installer.js')));
+        await mod.installFrameworkFromKeygen({ force: Boolean(args.force) });
+        process.exit(0);
     }
     catch (err) {
-        console.error('An error occurred during the install process:', err);
-        process.exit(1); // Exit with error code on failure
+        console.error('❌ framework:update failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+})
+    .command('framework:sync', 'Maintainer: fast-forward tier-1 client forks (branches + tags) from upstream, driven by ~/.hosanna/sync-clients.json', yargs => yargs
+    .option('client', { type: 'string', describe: 'Sync a single named client from the registry (default: all clients)' })
+    .option('registry', { type: 'string', describe: 'Path to the sync registry (default: ~/.hosanna/sync-clients.json)' })
+    .option('dry-run', { type: 'boolean', default: false, describe: 'Show what would be pushed without pushing' })
+    .option('init', { type: 'boolean', default: false, describe: 'Create a template registry file and exit' })
+    .example('$0 framework:sync', 'Sync all registered client forks')
+    .example('$0 framework:sync --client ewtn --dry-run', 'Preview a sync for one client'), async (args) => {
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require('./support-tools/framework-sync.js')));
+        if (args.init) {
+            const filePath = mod.initRegistry(args.registry);
+            console.info(`✅ Created sync registry template: ${filePath}`);
+            console.info('Edit it to add your clients, then run: hst framework:sync');
+            process.exit(0);
+        }
+        const results = await mod.syncFrameworkForks({
+            registryPath: args.registry,
+            client: args.client,
+            dryRun: Boolean(args['dry-run']),
+        });
+        const ok = mod.printSyncSummary(results, Boolean(args['dry-run']));
+        process.exit(ok ? 0 : 1);
+    }
+    catch (err) {
+        console.error('❌ framework:sync failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+})
+    .command('framework:doctor', 'Maintainer: validate tier-1 client forks (reachability, hosanna.json git-url/schema, sdk-version tags)', yargs => yargs
+    .option('client', { type: 'string', describe: 'Check a single named client from the registry (default: all clients)' })
+    .option('registry', { type: 'string', describe: 'Path to the sync registry (default: ~/.hosanna/sync-clients.json)' })
+    .example('$0 framework:doctor', 'Validate all registered client forks'), async (args) => {
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require('./support-tools/framework-sync.js')));
+        const issues = await mod.doctorFrameworkForks({
+            registryPath: args.registry,
+            client: args.client,
+        });
+        const ok = mod.printDoctorSummary(issues);
+        process.exit(ok ? 0 : 1);
+    }
+    catch (err) {
+        console.error('❌ framework:doctor failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
     }
 })
-    .command('install:template', 'Create a new template app with the Hosanna SDK', yargs => yargs, async (args) => {
+    .command('license:activate <key>', 'Store your Hosanna framework license key (~/.hosanna/license.key) after validating it', yargs => yargs
+    .positional('key', { type: 'string', demandOption: true, describe: 'License key issued for your organization' }), async (args) => {
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require('./updater/license-manager.js')));
+        const key = String(args.key).trim();
+        const validation = await mod.validateLicense(key);
+        if (!validation.valid) {
+            console.error(`❌ License is not valid: ${validation.code} ${validation.detail}`.trim());
+            process.exit(1);
+        }
+        const filePath = mod.storeLicenseKey(key);
+        console.info(`✅ License validated and stored at ${filePath}`);
+        if (validation.expiry)
+            console.info(`   Expires: ${validation.expiry}`);
+        process.exit(0);
+    }
+    catch (err) {
+        console.error('❌ license:activate failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+})
+    .command('license:status', 'Validate the stored license and print its entitlements (flavour, platforms, tier)', yargs => yargs, async () => {
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require('./updater/license-manager.js')));
+        const key = mod.requireLicenseKey();
+        const info = await mod.getLicenseInfo(key);
+        if (!info.validation.valid) {
+            console.error(`❌ License is not valid: ${info.validation.code} ${info.validation.detail}`.trim());
+            process.exit(1);
+        }
+        console.info('✅ License is valid');
+        if (info.validation.expiry)
+            console.info(`   Expires: ${info.validation.expiry}`);
+        const flavours = mod.entitledFlavours(info.entitlements);
+        const platforms = mod.entitledPlatforms(info.entitlements);
+        console.info(`   Flavour:   ${flavours.length ? flavours[flavours.length - 1] : '(none)'}`);
+        console.info(`   Platforms: ${platforms.length ? platforms.join(', ') : '(none)'}`);
+        console.info(`   Entitlements: ${info.entitlements.join(', ') || '(none)'}`);
+        process.exit(0);
+    }
+    catch (err) {
+        console.error('❌ license:status failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+})
+    .command('template:create', 'Create a new template app with the Hosanna SDK', yargs => yargs, async (args) => {
     if (args.verbose) {
         process.env.HOSANNA_VERBOSE = '1';
         process.env.HOSANNA_UPDATER_VERBOSE = '1';
     }
-    console.info('Running install:template command...');
+    console.info('Running template:create command...');
     try {
         await (0, sdk_manager_js_1.createTemplateApp)();
-        console.info('install:template command completed.');
+        console.info('template:create command completed.');
         process.exit(0);
     }
     catch (err) {
@@ -976,7 +1118,7 @@ catch (err) {
         process.exit(1);
     }
 })
-    .command('device:list', 'List devices discovered by hst, merged with .hs-devices.json preferences', yargs => yargs
+    .command('device:list', 'List devices discovered by hst, merged with .hosanna-tools/devices.json preferences', yargs => yargs
     .option('type', {
     type: 'string',
     choices: ['roku', 'ios', 'apple-tv', 'android', 'android-tv'],
@@ -1005,8 +1147,154 @@ catch (err) {
         console.error(err instanceof Error ? err.message : String(err));
         process.exit(1);
     }
+})
+    .command('target:list', 'List run targets discovered by hst, including web previews, simulators, and physical devices', yargs => yargs
+    .option('platform', {
+    type: 'string',
+    choices: ['web', 'roku', 'ios', 'apple-tv', 'android', 'android-tv'],
+    describe: 'Filter by launch platform',
+})
+    .option('target', {
+    type: 'string',
+    choices: ['web', 'device', 'simulator', 'emulator', 'simulated', 'emulated'],
+    describe: 'Filter by target kind',
+})
+    .option('form-factor', {
+    type: 'string',
+    choices: ['desktop', 'mobile', 'tablet', 'tv'],
+    describe: 'Filter by form factor for broad agent inventory queries',
+})
+    .option('json', {
+    type: 'boolean',
+    default: false,
+    describe: 'Print machine-readable JSON',
+})
+    .example('$0 target:list --platform roku', 'List Roku web/device targets')
+    .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')
+    .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 --form-factor tv --json', 'List TV-class targets as JSON'), async (args) => {
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require('./run/targets.js')));
+        const filters = mod.parseRunTargetFilters({
+            platform: args.platform,
+            target: args.target,
+            formFactor: args['form-factor'],
+        });
+        const targets = await mod.collectRunTargets(Object.assign(Object.assign({ cwd: process.cwd() }, filters), { env: process.env }));
+        if (args.json) {
+            console.info(JSON.stringify(mod.formatRunTargetsJson(targets), null, 2));
+        }
+        else {
+            console.info(mod.formatRunTargetsText(targets));
+        }
+        process.exit(0);
+    }
+    catch (err) {
+        console.error('❌ target:list failed');
+        console.error(err instanceof Error ? err.message : String(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 })
+    .option('platform', {
+    type: 'string',
+    choices: ['web', 'roku', 'ios', 'apple-tv', 'android', 'android-tv'],
+    demandOption: true,
+    describe: 'Launch platform. Required to keep agent runs deterministic.',
+})
+    .option('target', {
+    type: 'string',
+    choices: ['web', 'device', 'simulator', 'emulator', 'simulated', 'emulated'],
+    describe: 'Target kind. Defaults to web for web/roku.',
+})
+    .option('device', {
+    type: 'string',
+    describe: 'Device IP, serial/UDID, or case-insensitive name substring for device/simulator runs',
+})
+    .option('appName', {
+    type: 'string',
+    describe: 'App name used for debugger/session identity',
+})
+    .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('reuse', { type: 'boolean', default: false, describe: 'Explicitly allow reuse of a matching hst session' })
+    .option('replace', { type: 'boolean', default: false, describe: 'Replace conflicting web/device sessions or occupied device log resources' })
+    .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('no-build', { type: 'boolean', default: false, describe: 'Skip the platform build step for device runs' })
+    .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('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('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 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),
+            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);
+    }
 })
     .command('device:run', 'Build, deploy, launch, and stream logs for a device', yargs => yargs
+    .parserConfiguration({ 'boolean-negation': false })
     .option('type', {
     type: 'string',
     choices: ['roku', 'ios', 'apple-tv', 'android', 'android-tv'],
@@ -1165,12 +1453,12 @@ catch (err) {
         process.exit(1);
     }
 })
-    .command('run:mcp', 'Start the Hosanna MCP server for AI agent debugging', yargs => yargs
+    .command('mcp:start', 'Start the Hosanna MCP server for AI agent debugging', yargs => yargs
     .option('managementPort', { type: 'number', description: 'Management server port', default: 59150 })
     .option('managementHost', { type: 'string', description: 'Management server host', default: 'localhost' })
     .option('extensionPort', {
     type: 'number',
-    description: 'Debugger extension WebSocket port (must match hst run:debugger)',
+    description: 'Debugger extension WebSocket port (must match hst debugger:start)',
     default: 59153,
 }), async (args) => {
     if (args.verbose) {
@@ -1184,12 +1472,12 @@ catch (err) {
         extensionPort: args.extensionPort,
     });
 })
-    .command(['stop:mcp', 'run:stop'], 'Stop the Hosanna MCP server (reads PID from the same lock file as run:mcp). Alias: run:stop', yargs => {
+    .command('mcp:stop', 'Stop the Hosanna MCP server (reads PID from the same lock file as mcp:start).', yargs => {
     var _a;
     return yargs
         .option('managementPort', {
         type: 'number',
-        description: 'Must match the running instance (same as run:mcp)',
+        description: 'Must match the running instance (same as mcp:start)',
         default: parseInt((_a = process.env.HOSANNA_MANAGEMENT_PORT) !== null && _a !== void 0 ? _a : '59150', 10),
     })
         .option('force', {
@@ -1225,7 +1513,7 @@ catch (err) {
         process.exit(1);
     }
 })
-    .command('run:dev', 'Run dev processes: vite, generator watch, and optional debugger', yargs => yargs
+    .command('dev:start', 'Run dev processes: vite, generator watch, and optional debugger', yargs => yargs
     .option('vitePort', { type: 'number', description: 'Port for Vite dev server', default: 5173 })
     .option('webAppPort', { type: 'number', description: 'Port for web app client', default: 59151 })
     .option('deviceAppPort', { type: 'number', description: 'Port for device app client', default: 59152 })
@@ -1245,17 +1533,9 @@ catch (err) {
         defaultClientType: args.defaultClientType || 'web',
         appName: args.appName,
     });
-})
-    .command('ci:configure-hosanna-url [gitUrl]', 'Configure hosanna.json git-url from an argument or HOSANNA_UI_GIT_URL', yargs => yargs
-    .positional('gitUrl', { type: 'string', describe: 'Git URL to set in hosanna.json (defaults to env HOSANNA_UI_GIT_URL)' }), args => {
-    if (args.verbose) {
-        process.env.HOSANNA_VERBOSE = '1';
-        process.env.HOSANNA_UPDATER_VERBOSE = '1';
-    }
-    (0, cli_configure_hosanna_url_js_1.runConfigureHosannaUrl)(typeof args.gitUrl === 'string' ? args.gitUrl : undefined);
 })
     .command('test:ui [recordings..]', 'Replay UI test recordings against a running Hosanna app and exit with pass/fail. ' +
-    'Requires a running debug proxy (hst run:debugger) and a connected app.', yargs => yargs
+    'Requires a running debug proxy (hst debugger:start) and a connected app.', yargs => yargs
     .positional('recordings', {
     describe: 'Recording IDs to replay (omit to run all)',
     type: 'string',
@@ -2020,5 +2300,5 @@ catch (err) {
     .demandCommand(0)
     .strict()
     .parse();
-// Note: legacy --env flag removed; use `hst env`
+// Note: legacy --env flag removed; use `hst env check`
 //# sourceMappingURL=cli.js.map