@tantawowa/hosanna-tools 4.0.0 → 5.0.0

package/README.md

@@ -1,5 +1,9 @@
 # hosanna-tools
 
+This package lives in `packages/tools` in the Hosanna UI monorepo. It retains its
+own package name, version, and lockfile. Run its development commands from this
+directory; framework source remains at the repository root.
+
 ## Agent skills
 
 The repository instructions use TantaWowa's ClickUp workflow skills, Matt
@@ -7,7 +11,7 @@ Pocock's engineering skills, and pstack's `unslop` skill. Install them once on
 each developer machine:
 
 ```sh
-npx -y skills add TantaWowa/hosanna-tools --global --skill work-on-ticket hope-platform-planning hope-platform-architecture-ownership --agent '*' --full-depth --yes
+npx -y skills add TantaWowa/hosanna-tools --global --skill work-on-ticket --agent '*' --full-depth --yes
 npx -y skills add mattpocock/skills --global --all
 npx -y skills add cursor/plugins --global --skill unslop --agent '*' --full-depth --yes
 ```
@@ -24,7 +28,7 @@ Run `npx -y skills update --global --yes` to update the installed skills later.
 - **[Video capture](docs/video-capture.md)** — standalone, agent-driven, and test-run recording for Roku capture cards and browser emulator windows.
 - **[Roku and browser emulation](docs/roku-browser-emulation.md)** — supported launch commands, device selection, and emulator configuration.
 - **[docs/README.md](docs/README.md)** — index of docs in this repo (MCP + source-map note).
-- **hosanna-ui** (separate repo): `docs/README.md` for agentic debugging and links back to this README.
+- **[Hosanna UI framework](../../docs/README.md)** for agentic debugging and framework documentation.
 
 ## To use the tool
 
@@ -38,46 +42,68 @@ Note, if you are developing hosanna-tools, you will install the package locally.
 npm install . -g # path to the hosanna-tools directory
 ```
 
-## Hosanna source install modes
+## Install the framework
+
+The framework is an npm dependency. Install it with the tools in each app:
+
+```bash
+npm install --save-dev --save-exact @tantawowa/hosanna-tools@5 @tantawowa/hosanna-ui@2 @tantawowa/hosanna-eslint-plugin@2
+npx hst sdk:install
+```
+
+Commit `package.json` and `package-lock.json`. A fresh checkout runs `npm ci`
+followed by `npx hst sdk:install`. The command validates the installed package
+and maintains these app paths:
+
+```text
+hosanna-ui -> node_modules/@tantawowa/hosanna-ui
+src/hosanna-ui -> ../hosanna-ui/src/hosanna-ui
+```
+
+The other framework source folders use the same links. Existing `@hs-src`
+imports, generated app files and compiler paths continue to work. Update the
+framework with npm, then run `hst sdk:install` again. The command also reconciles
+the framework's declared app dependencies. Use `--skip-consumer-dependencies`
+when the app package manager has already installed them. Tools 5 requires
+Vitest `>=3.2.0 <5`; update an older app test dependency during the npm upgrade.
+
+For an app using the previous framework installer, install the npm packages
+with `--ignore-scripts` first so old install hooks cannot run removed commands,
+then run:
+
+```bash
+npm install --ignore-scripts --save-dev --save-exact @tantawowa/hosanna-tools@5 @tantawowa/hosanna-ui@2 @tantawowa/hosanna-eslint-plugin@2
+npx hst sdk:migrate --replace-existing
+```
+
+Migration removes the old framework version/source settings and private source
+override, preserves compiler and app settings, and replaces the old SDK folder
+with the npm compatibility link. The previous real SDK folder and its Git
+history remain in `hosanna-ui.before-npm`. It requires explicit replacement
+and refuses to discard changes in a Git checkout. Move or commit those changes first.
+Migration also updates exact known install, update, generation and cleanup
+scripts. Custom scripts that select a framework source or generate inside the
+SDK must be updated manually before migration; the command names them before
+changing files. A failed migration restores app configuration, dependency
+manifests, links and the previous SDK folder. After migration, run `npm rebuild`
+if dependencies need their install scripts.
 
-Client projects can switch between private Keygen source tarballs, an embedded
-copy, a shared local checkout, and the legacy git/local modes:
+For local framework development, use npm's normal local package support:
 
 ```bash
-hst config source                                                        # show current mode and immutable install identity
-hst config source keygen --sdk-version latest --install                  # newest valid private publication across all lanes
-hst config source keygen --sdk-version v1.29.1 --install                 # pin an exact immutable production release
-hst config source embedded --source-path ../hosanna-ui --install         # filtered, reproducible copy
-hst config source shared --source-path ../hosanna-ui --install           # portable relative link for local development
-hst config source git --install                                           # legacy git checkout
-hst config source local                                                   # caller-provided LOCAL_SDK checkout
-```
-
-Keygen mode writes `distribution: "keygen"`, `flavour: "fullSource"`, and no
-platform list to `hosanna.json`. Bare `latest` means the newest valid published
-full-source release by Keygen publication time, whether it came from a nightly,
-manual, or tag run. `@latest` remains the stable-lane alias and `@nightly`
-remains the development-lane alias. Exact versions are immutable pins.
-The same `HSC_LICENSE_KEY` used by the compiler authorizes source installation;
-there is no separate Hosanna source-license environment variable.
-
-Local `shared`, `embedded`, and `local` selections are private developer
-overrides. They do not rewrite `hosanna.json`: Git projects store the selection
-in worktree-specific Git metadata, so activating a local checkout cannot dirty
-the project or leak a machine path into a commit. `hst config source` and
-`hst env check` prominently report the active override, resolved checkout, and
-the committed distribution/version it temporarily supersedes. Running
-`hst sdk:install` or `hst framework:update` while an override is active preserves
-the local checkout. Select `keygen` or `git` with `--install
---replace-existing` to clear the override and return to the committed source.
-
-Use `--replace-existing` with `--install` when switching an existing project
-between modes. Replacement is refused for an unrecognized or modified source
-root; `--force` is required for a dirty git checkout. Embedded installs exclude
-repository/build/secret state, write a content-hash manifest, and never modify
-the source checkout. Shared installs validate the source and create a relative
-symlink. Granular flavours and platform subsets are deliberately rejected with
-`NOT SUPPORTED YET — use flavour "fullSource"`.
+npm install --save-dev ../hosanna-ui
+npx hst sdk:install
+```
+
+A declared dependency can also be redirected with `npm link`; the installer
+resolves the linked package through the same npm path. To return to a release,
+install the desired npm version and rerun `hst sdk:install`.
+
+`hosanna.json` retains `transpiler-version` and app integration settings such as
+`symlink-extra-folders`. Compiler installation and licensing are unchanged.
+`config source`, `framework:update`, `framework:sync` and `framework:doctor`
+were removed in tools 5. Framework delivery no longer uses Git clones, Keygen
+source artifacts or private source overrides.
 
 ## Embedding as a library
 
@@ -295,25 +321,15 @@ See [RELEASE.md](RELEASE.md) for the full release process.
 
 Quick reference:
 ```bash
-npm run release -- patch   # 2.14.0 → 2.14.1
-npm run release -- minor   # 2.14.0 → 2.15.0
-npm run release -- major   # 2.14.0 → 3.0.0
+npm run release -- patch --dry-run
+npm run release -- minor --dry-run
+npm run release -- major --dry-run
 ```
 
-For tokenless agent releases, dispatch **Release Patch** or **Release Minor**
-in GitHub Actions. Both wrappers invoke the OIDC-trusted `release.yml`
-workflow on `main`; agents do not need npm credentials.
-
-## CLI: configure-hosanna-url
-
-- **purpose**: Updates `hosanna.json` with a new Hosanna UI Git URL under the `git-url` key.
-- **usage**:
-  - `hst configure-hosanna-url https://github.com/YourOrg/hosanna-ui.git`
-  - `HOSANNA_UI_GIT_URL=https://github.com/YourOrg/hosanna-ui.git hst configure-hosanna-url`
-- **behavior**:
-  - If no positional `gitUrl` is provided, the command falls back to the `HOSANNA_UI_GIT_URL` environment variable.
-  - If neither is provided, it prints a message and leaves `hosanna.json` unchanged.
-  - On success, it prints a sanitized URL (protocol + host + path) for logs.
+The wrapper delegates to the root monorepo release command. Publication uses the
+central `monorepo-release.yml` workflow after this package's npm trusted publisher
+has been migrated. See [RELEASE.md](RELEASE.md) for the configuration and validation
+requirements.
 
 # Hosanna Tools CLI
 
@@ -337,12 +353,12 @@ Hosanna launches native Roku or Roku emulated in the browser. Other platform lau
 ```bash
 hst run
 hst run --last
-hst run roku dev device --device 192.168.1.229
+hst run roku dev device --device 192.0.2.50
 hst run roku dev emulator
 hst run browser dev emulator
 hst build roku dev device
 hst target:list --json
-hst launch roku --app-id dev --device 192.168.1.229
+hst launch roku --app-id dev --device 192.0.2.50
 ```
 
 `web` aliases `browser`. Browser launches default to the `rokufhd` device preset. Existing development sessions are reused only when the requested app and port match. Configured run defaults live in `.hosanna-tools/run.json`.
@@ -430,10 +446,9 @@ npm run roku:build
 ### CI Commands (`ci:*`) - Continuous Integration
 - `ci:project-actions --base <ref> [--head <ref>]` - Select `hst.json` `prScopeRules` actions for changed files; add `--run` to execute matched npm scripts
 - `ci:extract-pkg-key` - Extract signing key from an existing signed Roku package as base64
-- `config set --git-url` - Configure hosanna.json git-url from argument or environment
 
-Project-specific PR rules belong in `hst.json`; SDK source/version settings
-remain in `hosanna.json`:
+Project-specific PR rules belong in `hst.json`. The framework dependency and
+version belong in `package.json` and `package-lock.json`:
 
 ```json
 {
@@ -490,8 +505,8 @@ The installed SDK owns its app dependency contract in
 Both maps are required. `hst doctor` and `hst env check` validate the exact
 manifest, the app's direct `package.json` declarations, and the versions
 actually available through the app's Node resolution path (including a
-workspace-hoisted install). An older SDK without the manifest is reported as a
-supported legacy install with no requirements.
+workspace-hoisted install). The npm SDK must include this manifest; an
+incomplete package fails the environment check.
 
 `hst doctor --fix` and `hst env fix` add missing requirements and run one
 app-root `npm install`. The repair is additive to the app's dependency set: it
@@ -508,10 +523,8 @@ rollback snapshot; run the workspace's package manager from its root instead.
 If `npm install` fails, or the installed
 versions still fail the audit afterward, `package.json` and npm lockfiles
 (`package-lock.json` and `npm-shrinkwrap.json`) are restored to their original
-contents. SDK installs and updates—including
-Git, Keygen, local, embedded, and shared source modes—run the same reconciliation
-after the new SDK is ready, so a framework upgrade cannot leave new app
-requirements undeclared.
+contents. `sdk:install` and `sdk:migrate` run the same reconciliation after
+resolving the npm package, so framework requirements remain declared in the app.
 
 Library callers can inspect or run the same focused operation through
 `env.dependencies.audit({ projectRoot })` and
@@ -520,13 +533,12 @@ repair results without exiting the process.
 
 ### Framework Source Symlinks (semver-keyed registry)
 
-`hst` symlinks framework source folders from the `hosanna-ui/` checkout into the
+`hst` symlinks framework source folders through the `hosanna-ui/` npm compatibility link into the
 project (`src/hosanna-ui -> ../hosanna-ui/src/hosanna-ui`, etc.). Which folders
 get linked is decided by a **semver-keyed registry**: an entry applies when the
 installed framework version is **>=** its key, and the highest applicable key
 wins. The installed version is read from `hosanna-ui/package.json` (prerelease
-suffixes are ignored, so `1.31.0-next` counts as `1.31.0`) — this works for
-tags, branches, `@latest`, and `LOCAL_SDK` alike.
+suffixes are ignored, so `2.0.0-next` counts as `2.0.0`).
 
 **Built-in defaults** (`src/updater/symlink-registry.ts`):
 
@@ -534,10 +546,7 @@ tags, branches, `@latest`, and `LOCAL_SDK` alike.
 |---|---|
 | >= 1.0.0 | `hosanna-bridge-core`, `hosanna-bridge-http`, `hosanna-bridge-lib`, `hosanna-bridge-targets`, `hosanna-list`, `hosanna-ui` |
 
-Prefer folder existence over version gates when adding registry entries: a
-checkout's `package.json` version can lag the tag it was cut from (hosanna-ui
-`v1.28.3` reads `1.28.1-next`), and folders absent from a checkout are already
-skipped safely at sync time.
+Folders absent from the installed package are skipped when syncing links.
 
 `hst env check` always prints the active set, the matched registry version, and the
 source (`built-in`, `hosanna.json override`, `+ N extra`). `hst env fix`
@@ -551,8 +560,6 @@ to the resolved defaults; cannot break them. Folder names are forgiving
 
 ```json
 {
-  "git-url": "git@github.com:TantaWowa/hosanna-ui.git",
-  "sdk-version": "v1.31.0",
   "symlink-extra-folders": ["hosanna-game/", "hosanna-game-examples/"]
 }
 ```
@@ -599,6 +606,8 @@ silently break an install.
 
 Applications own regular Vitest suites. Global setup comes from `@tantawowa/hosanna-tools/testing/vitest`; worker fixtures and matchers come from `@tantawowa/hosanna-tools/testing/vitest/fixture`; shared lifecycle, types, and helpers come from `@tantawowa/hosanna-tools/testing`. There is no HST test CLI or recording/replay format.
 
+`timeoutMs` sets the limit for each launch/readiness stage and browser navigation during initial launch, runtime relaunch, and `hs.app.deepLink(...)`. Navigation still waits for the page's `load` event. The default is 60 seconds; a positive, finite `HS_TEST_TIMEOUT_MS` overrides the config. This is a per-stage limit, not a deadline for the whole test. Vitest's `testTimeout` and `hookTimeout`, and timeouts passed to individual assertion waits, remain separate.
+
 Add `createHosannaReporter(config)` from `@tantawowa/hosanna-tools/testing/vitest/reporter` to the application's Vitest reporters. Every run then writes a self-contained JSON and HTML report under `test-results/<testRunId>/`, updates `test-results/latest.json` and `test-results/latest.html`, and includes every Vitest result plus any named visual proofs captured by the tests.
 
 Tests can record a complete browser emulator or Roku device run:

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "buildDate": "2026-11-03T23:23:08+00:00",
-  "buildDateISO": "2026-11-03T23:23:08.559Z",
+  "buildDate": "2026-11-12T23:40:49+00:00",
+  "buildDateISO": "2026-11-12T23:40:49.615Z",
   "timeZone": "UTC",
-  "gitHash": "a1fefb6"
+  "gitHash": "08a7d43e7"
 }

package/dist/cli.js

@@ -243,14 +243,6 @@ const RUN_PLATFORM_CHOICES = ['browser', 'web', 'roku'];
 function stringArg(value) {
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
-function stringArrayArg(value) {
-    if (typeof value === 'string')
-        return [value];
-    if (Array.isArray(value)) {
-        return value.filter((item) => typeof item === 'string');
-    }
-    return undefined;
-}
 function parseVideoCaptureRect(value) {
     if (value === undefined)
         return undefined;
@@ -391,7 +383,7 @@ async function runEnvironmentCommand(action, verbose) {
 // 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(`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  doctor        Friendly environment/package check (use --fix to repair)\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         Roku and Roku browser emulator builds\n  run           Roku and Roku browser emulator launches\n  capture       Standalone scenario video capture\n  target:*      Run target discovery and inventory\n  roku:*        Roku deployment, commands & packaging (run, command, package, map-stack)\n  device:*      Device discovery and run workflows\n  generate:*    Code and asset generation\n  sdk:*         Hosanna SDK/framework installation\n  build-config:* Build/runtime configuration resolution\n  ci:*          Continuous integration helpers\n  framework:*   Framework distribution helpers\n  license:*     Hosanna framework licensing\n  secrets:*     Portable .secrets files\n  rasp:*        RASP cert scripts`)
+    .usage(`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  doctor        Friendly environment/package check (use --fix to repair)\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         Roku and Roku browser emulator builds\n  run           Roku and Roku browser emulator launches\n  capture       Standalone scenario video capture\n  target:*      Run target discovery and inventory\n  roku:*        Roku deployment, commands & packaging (run, command, package, map-stack)\n  device:*      Device discovery and run workflows\n  generate:*    Code and asset generation\n  sdk:*         Hosanna SDK/framework installation\n  build-config:* Build/runtime configuration resolution\n  ci:*          Continuous integration helpers\n  license:*     Hosanna compiler licensing\n  secrets:*     Portable .secrets files\n  rasp:*        RASP cert scripts`)
     .option('verbose', {
     type: 'boolean',
     default: false,
@@ -962,84 +954,23 @@ async function runEnvironmentCommand(action, verbose) {
     }
 })
     // remove old --env flag; env is now a subcommand
-    .command('config [action] [mode]', 'Show or update hosanna.json configuration from a curated catalog', yargs => yargs
+    .command('config [action]', 'Show or update hosanna.json configuration from a curated catalog', yargs => yargs
     .positional('action', {
     type: 'string',
-    choices: ['show', 'set', 'wizard', 'source'],
-    describe: 'show prints current config, set writes values from flags, wizard runs the interactive setup, source switches install mode',
+    choices: ['show', 'set', 'wizard'],
+    describe: 'show prints compiler config, set writes values from flags, wizard runs compiler setup',
 })
-    .positional('mode', {
-    type: 'string',
-    choices: ['show', 'keygen', 'git', 'local', 'embedded', 'shared'],
-    describe: 'Source install mode when action is source',
-})
-    .option('git-url', { type: 'string', describe: 'Set hosanna.json git-url' })
-    .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('flavour', { type: 'string', choices: ['fullSource', 'core', 'game', 'full'], describe: 'Keygen source flavour when action is source (supported: fullSource)' })
-    .option('platforms', { type: 'string', array: true, describe: 'Future split-platform selection; omit for fullSource' })
-    .option('source-path', { type: 'string', describe: 'Hosanna UI checkout to copy for embedded mode or link for shared mode' })
-    .option('install', { type: 'boolean', default: false, describe: 'Install the selected source mode atomically after updating config' })
-    .option('replace-existing', { type: 'boolean', default: false, describe: 'Allow --install to replace an existing hosanna-ui source root when switching modes' })
-    .option('force', { type: 'boolean', default: false, describe: 'Allow --install to replace a dirty git checkout when used with --replace-existing' })
     .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 actionArg = typeof args.action === 'string' ? args.action : undefined;
-    if (actionArg === 'source') {
-        try {
-            const result = await (0, hosanna_config_js_1.runHosannaSourceConfig)({
-                cwd: process.cwd(),
-                mode: (typeof args.mode === 'string' ? args.mode : 'show'),
-                flavour: args.flavour,
-                platforms: (0, hosanna_config_js_1.parsePlatformList)(stringArrayArg(args.platforms)),
-                sourcePath: typeof args.sourcePath === 'string' ? args.sourcePath : undefined,
-                sdkVersion: typeof args.sdkVersion === 'string' ? args.sdkVersion : undefined,
-                gitUrl: typeof args.gitUrl === 'string' ? args.gitUrl : undefined,
-                branch: typeof args.branch === 'string' ? args.branch : undefined,
-                install: Boolean(args.install),
-                replaceExisting: Boolean(args.replaceExisting),
-                force: Boolean(args.force),
-                writeStdout: text => console.info(text),
-            });
-            if (args.fix && result.updated) {
-                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) {
-                    console.info('\n❌ Remaining issues:');
-                    for (const issue of fixResult.remainingIssues) {
-                        console.info(`   • ${issue}`);
-                    }
-                }
-                if (!process.env.VITEST)
-                    process.exit(fixResult.success ? 0 : 1);
-                return;
-            }
-            if (!process.env.VITEST)
-                process.exit(0);
-            return;
-        }
-        catch (err) {
-            console.error('❌ Failed to configure source install mode:', err instanceof Error ? err.message : err);
-            if (!process.env.VITEST)
-                process.exit(1);
-            return;
-        }
-    }
     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')
@@ -1447,124 +1378,33 @@ async function runEnvironmentCommand(action, verbose) {
         process.exit(1);
     }
 })
-    .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)' })
-    .option('skip-consumer-dependencies', { type: 'boolean', default: false, describe: 'Install the SDK without changing the app dependency manifest or installing app dependencies' }), async (args) => {
-    if (args.verbose) {
-        process.env.HOSANNA_VERBOSE = '1';
-        process.env.HOSANNA_UPDATER_VERBOSE = '1';
-    }
-    console.info('Running sdk:install command...');
-    try {
-        const skipConsumerDependencyReconciliation = Boolean(args['skip-consumer-dependencies']);
-        const { assertLocalSourceOverrideInstalled, readLocalSourceOverride } = await Promise.resolve().then(() => __importStar(require('./lib/local-source-override.js')));
-        const localOverride = readLocalSourceOverride(process.cwd());
-        if (localOverride) {
-            assertLocalSourceOverrideInstalled(process.cwd(), localOverride);
-            const { prepareLocalSdkIntegration } = await Promise.resolve().then(() => __importStar(require('./updater/local-sdk-manager.js')));
-            prepareLocalSdkIntegration(process.cwd(), { skipConsumerDependencyReconciliation });
-            console.info(`Private ${localOverride.mode} Hosanna source override is active; preserved the local SDK and skipped the committed distribution install.`);
-            console.info('sdk:install command completed.');
-            process.exit(0);
-            return;
-        }
-        // 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), skipConsumerDependencyReconciliation });
-        }
-        else {
-            await (0, sdk_manager_js_1.installSdk)(false, false, true, { skipConsumerDependencyReconciliation });
-        }
-        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('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';
-    }
+    .command('sdk:install', 'Integrate the npm-installed @tantawowa/hosanna-ui package and repair its source links', yargs => yargs.option('skip-consumer-dependencies', { type: 'boolean', default: false, describe: 'Repair links without changing app dependency declarations' }), async (args) => {
     try {
-        const { assertLocalSourceOverrideInstalled, readLocalSourceOverride } = await Promise.resolve().then(() => __importStar(require('./lib/local-source-override.js')));
-        const localOverride = readLocalSourceOverride(process.cwd());
-        if (localOverride) {
-            assertLocalSourceOverrideInstalled(process.cwd(), localOverride);
-            const { prepareLocalSdkIntegration } = await Promise.resolve().then(() => __importStar(require('./updater/local-sdk-manager.js')));
-            prepareLocalSdkIntegration(process.cwd());
-            console.info(`Private ${localOverride.mode} Hosanna source override is active; preserved the local SDK and skipped framework:update.`);
+        await (0, sdk_manager_js_1.installSdk)({ skipConsumerDependencyReconciliation: Boolean(args['skip-consumer-dependencies']) });
+        if (!process.env.VITEST)
             process.exit(0);
-            return;
-        }
-        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('❌ framework:update failed:', err instanceof Error ? err.message : err);
-        process.exit(1);
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        if (!process.env.VITEST)
+            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) => {
+    .command('sdk:migrate', 'Migrate an existing app to its npm-installed framework, preserving compiler configuration', yargs => yargs
+    .option('replace-existing', { type: 'boolean', default: false, describe: 'Replace the old SDK folder or link; dirty Git checkouts are always protected' })
+    .option('skip-consumer-dependencies', { type: 'boolean', default: false, describe: 'Migrate config and links without changing app dependency declarations' }), 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');
+        await (0, sdk_manager_js_1.migrateSdk)({ replaceExisting: Boolean(args['replace-existing']), skipConsumerDependencyReconciliation: Boolean(args['skip-consumer-dependencies']) });
+        if (!process.env.VITEST)
             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);
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        if (!process.env.VITEST)
+            process.exit(1);
     }
 })
-    .command('license:activate <key>', 'Store your Hosanna framework license key (~/.hosanna/license.key) after validating it', yargs => yargs
+    .command('license:activate <key>', 'Store your Hosanna compiler 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')));
@@ -1591,7 +1431,7 @@ async function runEnvironmentCommand(action, verbose) {
         process.exit(1);
     }
 })
-    .command('license:status', 'Validate the stored license and print its entitlements (flavour, platforms, tier)', yargs => yargs, async () => {
+    .command('license:status', 'Validate the stored compiler license and print its entitlements', yargs => yargs, async () => {
     try {
         const mod = await Promise.resolve().then(() => __importStar(require('./updater/license-manager.js')));
         const credential = mod.requireLicenseCredential();
@@ -1607,10 +1447,6 @@ async function runEnvironmentCommand(action, verbose) {
         if (info.validation.expiry)
             console.info(`   Expires: ${info.validation.expiry}`);
         console.info(`   Credential: ${credential.source === 'environment' ? 'HSC_LICENSE_KEY' : credential.filePath}`);
-        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)'}`);
         for (const warning of mod.getLicenseConfigurationWarnings()) {
             console.warn(`   ⚠ ${warning}`);
@@ -1943,8 +1779,8 @@ async function runEnvironmentCommand(action, verbose) {
     .example('$0 run --last', 'Immediately run on the last selected destination')
     .example('$0 run --platform roku --target emulator', 'Start/reuse the Roku TV web emulator')
     .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) => {
+    .example('$0 run roku dev device --app client2', 'Run a configured monorepo app/flavor')
+    .example('$0 run roku prod device --hsc-project platforms/hsconfig.client2.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
@@ -2519,9 +2355,9 @@ async function runEnvironmentCommand(action, verbose) {
     default: false,
     describe: 'Keep the temporary RASP capture JSON/screenshots after the script is written.',
 })
-    .example('$0 rasp:capture login --channel-name "Criterion"', 'Record and export to rasp-scripts/login.rasp')
-    .example('$0 rasp:capture login --channel-name "Criterion" --login-text "user@example.com" --password-text "MyPass1!"', 'Default credential flow with custom text')
-    .example('$0 rasp:capture login --channel-name "Criterion" --credential-flow ./flow.rasp --login-text U --password-text P', 'Override flow via YAML file'), async (args) => {
+    .example('$0 rasp:capture login --channel-name "Client2"', 'Record and export to rasp-scripts/login.rasp')
+    .example('$0 rasp:capture login --channel-name "Client2" --login-text "user@example.com" --password-text "MyPass1!"', 'Default credential flow with custom text')
+    .example('$0 rasp:capture login --channel-name "Client2" --credential-flow ./flow.rasp --login-text U --password-text P', 'Override flow via YAML file'), async (args) => {
     var _a, _b;
     const path = await Promise.resolve().then(() => __importStar(require('path')));
     const fs = await Promise.resolve().then(() => __importStar(require('fs')));