@tantawowa/hosanna-tools 2.19.0 → 2.20.0

package/README.md

@@ -18,6 +18,43 @@ Note, if you are developing hosanna-tools, you will install the package locally.
 npm install . -g # path to the hosanna-tools directory
 ```
 
+## Embedding as a library
+
+Hosanna Tools can also be imported by app build chains. The CLI remains available as `hst`, but package imports are library-safe and do not parse CLI arguments or call `process.exit` during import. Public wrappers for process-oriented commands use no-exit mode where supported, so API callers receive structured results or thrown errors instead of forced process termination.
+
+```ts
+import { buildConfig, env, generate, install, roku, secrets } from '@tantawowa/hosanna-tools';
+
+await generate.all({
+  rootFolder: './src',
+  generatedFolder: './src-generated',
+  mode: 'runtime',
+});
+
+await buildConfig.resolve({
+  env: 'dev',
+  platform: 'roku',
+  out: 'assets/meta/build-config.json',
+});
+
+await install.compiler({ version: '0.33.7' });
+await roku.package({ env: 'prod', prebuild: 'npm run roku:build:prod' });
+```
+
+Common build-script replacements:
+
+| CLI command | Programmatic API |
+| --- | --- |
+| `npx hst generate --rootFolder ./src` | `await generate.all({ rootFolder: './src' })` |
+| `npx hst generate:clean` | `await generate.clean()` |
+| `npx hst build-config resolve --env dev --platform roku --out assets/meta/build-config.json` | `await buildConfig.resolve({ env: 'dev', platform: 'roku', out: 'assets/meta/build-config.json' })` |
+| `npx hst install:compiler 0.33.7` | `await install.compiler({ version: '0.33.7' })` |
+| `npx hst roku:package --env prod --prebuild 'npm run roku:build:prod'` | `await roku.package({ env: 'prod', prebuild: 'npm run roku:build:prod' })` |
+| `npx hst secrets:check` | `await secrets.check({ cwd: process.cwd() })` |
+| `npx hst env` | `await env.check({ cwd: process.cwd() })` |
+
+Long-running APIs such as `dev.run`, `debugger.start`, `mcp.start`, `test.record`, and RASP capture-style 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`, `dev.run`, and `test.ui` are wired for programmatic no-exit behavior through the top-level API.
+
 # Getting started
 
 Ensure you have Node.js 20 or higher.
@@ -113,6 +150,22 @@ The CLI commands are organized into logical groups using colon-separated namespa
 ### Roku Commands (`roku:*`) - Roku Deployment & Packaging
 - `roku:run` - Deploy a Roku app to a device (supports .zip file or folder)
 - `roku:package` - Package and sign a Roku channel using roku-deploy
+- `roku:map-stack` - Resolve Roku `.brs` stack traces, compile errors, and crash snippets to original TypeScript locations using `.brs.map` files
+
+Resolve pasted Roku output:
+
+```bash
+pbpaste | hst roku:map-stack --source-map-root platforms/roku/src
+```
+
+Resolve a saved crash report or a single line:
+
+```bash
+hst roku:map-stack --file crash.txt --source-map-root platforms/roku/src
+hst roku:map-stack --text "file/line: pkg:/components/source_0.brs(7475)"
+```
+
+Supported inputs include `file/line: pkg:/components/source_0.brs(7475)`, `at ... (pkg:/components/source_1.brs:6636)`, `in pkg:/components/source_3.brs(4710)`, and bare generated references such as `source_10.brs:8211`. See [docs/roku-map-stack.md](docs/roku-map-stack.md).
 
 ### Generate Commands (`generate:*`) - Code Generation
 - `generate` - Generate structs and command handler maps
@@ -142,11 +195,12 @@ npm run apple:build-code
 
 ### CI Commands (`ci:*`) - Continuous Integration
 - `ci:extract-pkg-key` - Extract signing key from an existing signed Roku package as base64
-- `ci:extract-config` - Extract debug-flags JSON files as base64 environment variables
-- `ci:restore-flags` - Restore debug-flags JSON files from base64 environment variables
-- `ci:prepare-debug-flags` - Prepare one runtime `debug-flags.json` from `DEBUG_FLAGS_<ENV>_BASE64` or a local source file
 - `ci:configure-hosanna-url` - Configure hosanna.json git-url from argument or environment
 
+### Build Config Commands (`build-config:*`) - Build/runtime config
+- `build-config resolve` - Merge build config overlays into `assets/meta/build-config.json`
+- `build-config:restore-secrets` - Restore ignored `secrets/*.json` overlays from `BUILD_CONFIG_SECRETS_*_BASE64`
+
 ### Secrets Commands (`secrets:*`) - Portable `.secrets` files
 - `secrets:list` - Print key names from `.secrets` (or `--template` for `.secrets.example`); `--format json`
 - `secrets:check` - Compare `.secrets` to the template; report missing, empty, and extra keys; `--strict` fails on extras
@@ -158,13 +212,13 @@ Shared options: `--file` (secrets path), `--template` (template path for `check`
 ### Environment Commands (`env:*`) - Environment Management
 - `env` - Print environment information and run checks with auto-fix option
 - `env:prepare-gitignore` - Ensure .gitignore contains required entries
-- `env:cloud-agent-setup` - Restore debug flags, patch `remoteDebug` for cloud agents, optionally start debugger and `npm run dev`
+- `env:cloud-agent-setup` - Write `build-config/profiles/cloud-agent.json`, patch `remoteDebug` for cloud agents, optionally start debugger and `npm run dev` with `HS_BUILD_PROFILE=cloud-agent`
 
 ### MCP Debugging Commands (`run:mcp`, `stop:mcp`) - AI Agent Debugging
 - `run:mcp` - Start the Hosanna MCP server for AI agent debugging
 - `stop:mcp` - Stop the Hosanna MCP server
 
-**Cursor agents and MCP:** Cursor does not magically attach to a terminal `hst run:mcp`. You add Hosanna as an MCP server (project **`.cursor/mcp.json`** or **Cursor Settings → MCP → Add Custom MCP**) so Cursor spawns **`hosanna-mcp`** (stdio transport). That process talks to the **command debugger** on HTTP **59150** and extension WebSocket **59153** by default. In **Cursor Cloud Agents**, run **`npx hst env:cloud-agent-setup --start-debugger --start-app`** (and set **`DEBUG_FLAGS_DEV_BASE64`** in agent secrets) so those services and `debug-flags.dev.json` exist before the agent uses MCP tools. See [Cursor MCP settings](#cursor-settings--mcp-hosanna-debugger) below.
+**Cursor agents and MCP:** Cursor does not magically attach to a terminal `hst run:mcp`. You add Hosanna as an MCP server (project **`.cursor/mcp.json`** or **Cursor Settings → MCP → Add Custom MCP**) so Cursor spawns **`hosanna-mcp`** (stdio transport). That process talks to the **command debugger** on HTTP **59150** and extension WebSocket **59153** by default. In **Cursor Cloud Agents**, run **`npx hst env:cloud-agent-setup --start-debugger --start-app`** so those services are up before the agent uses MCP tools. See [Cursor MCP settings](#cursor-settings--mcp-hosanna-debugger) below.
 
 ### UI Test Commands (`test:*`) - UI Test Automation
 - `test:ui` - Replay UI test recordings against a running Hosanna app
@@ -189,9 +243,8 @@ hst install:template           # Create new template app
 
 # CI/CD operations
 hst ci:extract-pkg-key myapp.pkg  # Extract signing key for CI
-hst ci:extract-config           # Extract debug config for CI
-hst ci:restore-flags           # Restore config from CI variables
-hst ci:prepare-debug-flags --env prod --source assets/meta/debug-flags.prod.json --output-file build/debug-flags/prod/debug-flags.json
+hst build-config:restore-secrets
+hst build-config resolve --env prod --platform roku --out assets/meta/build-config.json
 
 # Secrets (.secrets / .secrets.example)
 hst secrets:list

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "buildDate": "2026-06-02T15:26:13+01:00",
-  "buildDateISO": "2026-06-02T14:26:13.016Z",
+  "buildDate": "2026-06-04T12:18:05+01:00",
+  "buildDateISO": "2026-06-04T11:18:05.597Z",
   "timeZone": "Europe/London",
-  "gitHash": "de31d2c"
+  "gitHash": "4ea6b0e"
 }

package/dist/cli.js

@@ -87,7 +87,7 @@ catch (err) {
 // Let yargs handle all commands including env
 (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
     .version(`${buildVersion}\n  git: ${buildGitHash}\n  built: ${buildDate}`)
-    .usage('$0 [command] [options]', `Hosanna Tools CLI\nVersion: ${buildVersion}\nBuild Date: ${buildDate}\n\nCommand Groups:\n  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, extract-config, restore-flags)\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  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)`)
     .option('verbose', {
     type: 'boolean',
     default: false,
@@ -144,6 +144,38 @@ catch (err) {
         console.error('❌ Failed to resolve build config:', err);
         process.exit(1);
     }
+})
+    .command('build-config:restore-secrets', 'Restore ignored build config secret overlays from BUILD_CONFIG_SECRETS_*_BASE64 environment variables', yargs => yargs
+    .option('out-dir', { type: 'string', describe: 'Output directory for secret overlays (default: secrets)' })
+    .option('env', { type: 'string', describe: 'Restore only one environment overlay, e.g. dev or prod' })
+    .option('profile', { type: 'string', describe: 'Restore only one profile overlay, e.g. george' })
+    .option('quiet', { type: 'boolean', default: false, describe: 'Reduce output' })
+    .example('$0 build-config:restore-secrets', 'Restore all build config secret overlays from the environment')
+    .example('$0 build-config:restore-secrets --env prod', 'Restore only BUILD_CONFIG_SECRETS_PROD_BASE64')
+    .epilog([
+    'Environment variables:',
+    '  BUILD_CONFIG_SECRETS_<ENV>_BASE64 -> secrets/<env>.json',
+    '  BUILD_CONFIG_PROFILE_SECRETS_<PROFILE>_BASE64 -> secrets/profiles/<profile>.json',
+    'Values must be base64-encoded JSON objects. Secret values are never printed.',
+].join('\n')), 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/build-config-secrets.js')));
+        mod.restoreBuildConfigSecrets({
+            outDir: args['out-dir'],
+            env: args.env,
+            profile: args.profile,
+            quiet: Boolean(args.quiet),
+        });
+        process.exit(0);
+    }
+    catch (err) {
+        console.error('❌ Failed to restore build config secret overlays:', err);
+        process.exit(1);
+    }
 })
     .command(['version', 'v'], 'Print the version number', yargs => yargs, () => {
     console.log(buildVersion);
@@ -216,6 +248,41 @@ catch (err) {
         console.error('❌ Failed to publish Roku package:', err);
         process.exit(1);
     }
+})
+    .command('roku:map-stack', 'Resolve Roku BrightScript stack traces or compile errors to original TypeScript locations using .brs.map files', yargs => yargs
+    .option('source-map-root', {
+    type: 'string',
+    default: 'platforms/roku/src',
+    describe: 'Path to packaged Roku source root containing .brs.map files, e.g. platforms/roku/src'
+})
+    .option('file', {
+    type: 'string',
+    describe: 'Read stack trace text from a file instead of stdin'
+})
+    .option('text', {
+    type: 'string',
+    describe: 'Resolve this stack trace text directly instead of stdin'
+})
+    .example('pbpaste | $0 roku:map-stack --source-map-root platforms/roku/src', 'Resolve a pasted Roku crash or compiler log')
+    .example('$0 roku:map-stack --file crash.txt --source-map-root platforms/roku/src', 'Resolve stack trace text from a file')
+    .example('$0 roku:map-stack --text "file/line: pkg:/components/source_0.brs(7475)"', 'Resolve a single Roku backtrace line'), async (args) => {
+    if (args.verbose) {
+        process.env.HOSANNA_VERBOSE = '1';
+    }
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require('./support-tools/roku-map-stack.js')));
+        await mod.runRokuMapStackCommand({
+            sourceMapRoot: args['source-map-root'],
+            file: args.file,
+            text: args.text,
+        });
+        process.exit(0);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(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)' })
@@ -309,74 +376,6 @@ catch (err) {
         console.error('❌ Failed to create CI package:', err);
         process.exit(1);
     }
-})
-    .command('ci:extract-config', 'Extract debug-flags JSON files as base64 environment variables for CI', yargs => yargs
-    .option('output-dir', { type: 'string', describe: 'Directory containing debug-flags files (default: assets/meta)' })
-    .option('root-keys', { type: 'string', describe: 'Comma-separated list of root keys to include (default: env,remoteDebug,services,appController,config,remoteStyleFile)' })
-    .example('$0 ci:extract-config', 'Extract all debug-flags.*.json files as base64 environment variables')
-    .example('$0 ci:extract-config --output-dir ./config', 'Extract from custom directory')
-    .example('$0 ci:extract-config --root-keys env,remoteDebug', 'Extract only specific root keys'), 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/extract-ci-config.js')));
-        await mod.extractCiConfig({
-            outputDir: args['output-dir'],
-            rootKeys: args['root-keys'],
-        });
-        process.exit(0);
-    }
-    catch (err) {
-        console.error('❌ Failed to extract CI config:', err);
-        process.exit(1);
-    }
-})
-    .command('ci:restore-flags', 'Restore debug-flags JSON files from DEBUG_FLAGS_*_BASE64 environment variables', yargs => yargs
-    .option('output-dir', { type: 'string', describe: 'Directory to restore debug-flags files (default: assets/meta)' })
-    .example('$0 ci:restore-flags', 'Restore debug-flags files from environment variables')
-    .example('$0 ci:restore-flags --output-dir ./config', 'Restore to custom directory'), 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/restore-debug-flags.js')));
-        await mod.restoreDebugFlags({
-            outputDir: args['output-dir'],
-        });
-        process.exit(0);
-    }
-    catch (err) {
-        console.error('❌ Failed to restore debug flags:', err);
-        process.exit(1);
-    }
-})
-    .command('ci:prepare-debug-flags', 'Prepare one runtime debug-flags.json file from DEBUG_FLAGS_<ENV>_BASE64 or a local source file', yargs => yargs
-    .option('env', { type: 'string', demandOption: true, describe: 'Environment to prepare, e.g. dev or prod' })
-    .option('source', { type: 'string', demandOption: true, describe: 'Local debug-flags source file to use when the env var is absent' })
-    .option('output-file', { type: 'string', demandOption: true, describe: 'Runtime debug-flags.json output path' })
-    .option('quiet', { type: 'boolean', default: false, describe: 'Reduce output' })
-    .example('$0 ci:prepare-debug-flags --env prod --source assets/meta/debug-flags.prod.json --output-file build/debug-flags/prod/debug-flags.json', 'Prepare prod runtime debug flags without overwriting the local source file'), 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/restore-debug-flags.js')));
-        await mod.prepareDebugFlags({
-            env: args.env,
-            source: args.source,
-            outputFile: args['output-file'],
-            quiet: Boolean(args.quiet),
-        });
-        process.exit(0);
-    }
-    catch (err) {
-        console.error('❌ Failed to prepare debug flags:', err);
-        process.exit(1);
-    }
 })
     .command('secrets:list', 'Print secret key names from .secrets (values hidden). Use --template for .secrets.example', yargs => yargs
     .option('file', { type: 'string', describe: 'Path to .secrets (default: .secrets in cwd or git root)' })
@@ -532,7 +531,7 @@ catch (err) {
     }
 })
     .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 debug-flags.dev.json (default: assets/meta)' })
+    .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' })
@@ -1077,7 +1076,7 @@ catch (err) {
         process.env.HOSANNA_VERBOSE = '1';
         process.env.HOSANNA_UPDATER_VERBOSE = '1';
     }
-    return (0, cli_configure_hosanna_url_js_1.runConfigureHosannaUrl)(typeof args.gitUrl === 'string' ? args.gitUrl : undefined);
+    (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