@tantawowa/hosanna-tools 3.18.0 → 3.18.1

package/README.md

@@ -100,6 +100,8 @@ Common build-script replacements:
 | `npx hst capture ios --device 'iPhone 17 Pro'` | `await capture.start({ platform: 'ios', device: 'iPhone 17 Pro' })` |
 | `npx hst secrets:check` | `await secrets.check({ cwd: process.cwd() })` |
 | `npx hst env check` | `await env.check({ cwd: process.cwd() })` |
+| `npx hst doctor` | `await env.check({ cwd: process.cwd() })` |
+| `npx hst doctor --fix` | `await env.check({ cwd: process.cwd(), fix: true })` |
 
 Long-running APIs such as `dev.run`, `debugger.start`, `mcp.start`, and RASP-owned certification capture workflows keep the same operational behavior as the corresponding CLI commands: they start services, attach to debuggers, or wait for user/session activity. `mcp.start` and `dev.run` are wired for programmatic no-exit behavior through the top-level API.
 
@@ -449,10 +451,56 @@ npm run apple:build-code
 Shared options: `--file` (secrets path), `--template` (template path for `check` / `init` / `list --template`), `--format text|json`.
 
 ### Environment Commands (`env ...`) - Environment Management
+- `doctor` - Run the same read-only checks as `env check`, including required app packages
+- `doctor --fix` - Run the same repair path as `env fix`
 - `env check` - Print environment information and run checks
 - `env fix` - Check and repair environment issues
 - `env prepare-gitignore` - Ensure .gitignore contains required entries
 
+#### Hosanna consumer dependencies
+
+The installed SDK owns its app dependency contract in
+`hosanna-ui/hosanna-consumer-dependencies.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "dependencies": { "lottie-web": "^5.13.0" },
+  "devDependencies": { "@types/crypto-js": "^4.2.2" }
+}
+```
+
+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.
+
+`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
+does not remove unrelated packages. It may move a compatible required package
+out of `devDependencies` or `optionalDependencies` so a runtime requirement is
+installed reliably. Existing compatible app ranges are preserved. An existing
+range that can select versions outside the SDK's required range is reported as
+a conflict and is not overwritten.
+
+Projects that select another package manager or ship its lockfile are left for
+that package manager to repair. Workspace members are audited, but automatic
+repair is blocked so an ancestor lockfile is never changed without a matching
+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.
+
+Library callers can inspect or run the same focused operation through
+`env.dependencies.audit({ projectRoot })` and
+`env.dependencies.reconcile({ projectRoot })`; both return structured audit and
+repair results without exiting the process.
+
 ### Framework Source Symlinks (semver-keyed registry)
 
 `hst` symlinks framework source folders from the `hosanna-ui/` checkout into the
@@ -679,6 +727,8 @@ hst secrets:exec -- npm run build
 hst secrets:init
 
 # Environment management
+hst doctor                   # Read-only environment and package audit
+hst doctor --fix             # Repair issues and install missing requirements
 hst env fix                  # Check and fix environment issues
 hst env prepare-gitignore      # Update .gitignore
 

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "buildDate": "2026-08-14T06:25:48+00:00",
-  "buildDateISO": "2026-08-14T06:25:48.573Z",
+  "buildDate": "2026-08-15T19:50:20+00:00",
+  "buildDateISO": "2026-08-15T19:50:20.748Z",
   "timeZone": "UTC",
-  "gitHash": "ba52fa6"
+  "gitHash": "1be28fb"
 }

package/dist/cli.js

@@ -399,10 +399,49 @@ catch (err) {
 /*******************************************************************
  * CLI Handling
  *******************************************************************/
+async function runEnvironmentCommand(action, verbose) {
+    if (verbose) {
+        process.env.HOSANNA_VERBOSE = '1';
+        process.env.HOSANNA_UPDATER_VERBOSE = '1';
+    }
+    const info = (0, env_info_js_1.collectEnvInfo)(process.cwd());
+    console.info((0, env_info_js_1.formatEnvReportWithChecks)(info));
+    const ok = (0, env_info_js_1.allEnvChecksPass)(info);
+    if (action === 'check') {
+        if (!process.env.VITEST)
+            process.exit(ok ? 0 : 1);
+        return;
+    }
+    if (ok) {
+        console.info('\n✅ All environment checks passed - no fixes needed.');
+        if (!process.env.VITEST)
+            process.exit(0);
+        return;
+    }
+    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);
+}
 // Let yargs handle all commands including env
 (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
     .version(`${buildVersion}\n  git: ${buildGitHash}\n  built: ${buildDate}`)
-    .usage('$0 [command] [options]', `Hosanna Tools CLI\nVersion: ${buildVersion}\nBuild Date: ${buildDate}\n\nCommand Groups:\n  compiler:*    Compiler lifecycle (install, status, list)\n  config        hosanna.json management (wizard, show, set)\n  env           Environment checks and repair (check, fix, prepare-gitignore)\n  dev:*         Local development execution\n  debugger:*    Command debugger control\n  mcp:*         Hosanna MCP server control\n  build         Cross-platform build orchestration\n  run           Cross-platform launch orchestration\n  capture       Standalone scenario video capture\n  native:*      Native platform bootstrap and validation\n  target:*      Run target discovery and inventory\n  roku:*        Roku deployment, commands & packaging (run, command, package, map-stack)\n  device:*      Device discovery and run workflows\n  generate:*    Code and asset generation\n  sdk:*         Hosanna SDK/framework installation\n  build-config:* Build/runtime configuration resolution\n  ci:*          Continuous integration helpers\n  framework:*   Framework distribution helpers\n  license:*     Hosanna framework licensing\n  secrets:*     Portable .secrets files\n  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  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         Cross-platform build orchestration\n  run           Cross-platform launch orchestration\n  capture       Standalone scenario video capture\n  native:*      Native platform bootstrap and validation\n  target:*      Run target discovery and inventory\n  roku:*        Roku deployment, commands & packaging (run, command, package, map-stack)\n  device:*      Device discovery and run workflows\n  generate:*    Code and asset generation\n  sdk:*         Hosanna SDK/framework installation\n  build-config:* Build/runtime configuration resolution\n  ci:*          Continuous integration helpers\n  framework:*   Framework distribution helpers\n  license:*     Hosanna framework licensing\n  secrets:*     Portable .secrets files\n  rasp:*        RASP cert scripts`)
     .option('verbose', {
     type: 'boolean',
     default: false,
@@ -1180,56 +1219,24 @@ catch (err) {
     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';
-    }
     if (args.action === 'prepare-gitignore') {
+        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.');
         return;
     }
-    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);
-    }
+    await runEnvironmentCommand(args.action, Boolean(args.verbose));
+})
+    .command('doctor', 'Check the local Hosanna environment and required consumer packages', yargs => yargs.option('fix', {
+    type: 'boolean',
+    default: false,
+    describe: 'Repair environment issues and install missing consumer packages',
+}), async (args) => {
+    await runEnvironmentCommand(args.fix ? 'fix' : 'check', Boolean(args.verbose));
 })
     .command('debugger:start', 'Start the command debugger WebSocket proxy', yargs => yargs
     .option('webAppPort', { type: 'number', description: 'Port for web app client', default: 59151 })