@tantawowa/hosanna-tools 3.13.0 → 3.14.0

package/README.md

@@ -102,6 +102,75 @@ Common build-script replacements:
 
 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.
 
+## Precompiled AppConfig and static asset bundles
+
+Projects enable the compiler in `.hosanna-tools/run.json`. Normal `hst run` and
+`hst build` plans then compile before starting or packaging the target:
+
+```json
+{
+  "defaults": {
+    "appConfigCompiler": {
+      "enabled": true,
+      "shapeDelivery": "bundled",
+      "fontDelivery": "bundled",
+      "bundleOutputDir": "public/asset-bundles",
+      "assetUrlRoot": "/asset-bundles",
+      "staticBundleManifest": "asset-bundles/static-bundles.json"
+    }
+  }
+}
+```
+
+`staticBundleManifest` is optional. It adds scoped image, mask, JSON, media, or
+other project-owned assets to the same precompile step:
+
+```json
+{
+  "schemaVersion": 1,
+  "bundles": [
+    {
+      "bundleId": "sample-home",
+      "cacheBundleId": "sample-shared",
+      "sourceDir": "sample-assets",
+      "assets": [
+        "content/home.json",
+        "images/hero.jpg",
+        {
+          "source": "images/mask.png",
+          "fileName": "masks/home.png",
+          "required": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+Paths are relative to the manifest. `assetsFile` may replace or supplement the
+inline `assets` array; it accepts either an array or an object containing an
+`assets` array. Existing descriptor-shaped source lists are accepted by using
+each entry's `fileName` as its source.
+
+Generated descriptors use `sha256:<digest>` versions derived from asset
+contents, keys, required flags, bundle/cache ids, and optional revisions.
+Descriptors that share a `cacheBundleId` also share one aggregate version, so
+loading a second scoped descriptor cannot invalidate assets retained by the
+first.
+Compiler ledgers remove stale owned files. Missing required sources fail before
+the application starts; optional missing sources are omitted. Re-running the
+command preserves byte-identical output and does not rewrite unchanged files.
+
+Useful commands:
+
+```bash
+npx hst app-config:compile --expression tv --platform web \
+  --static-bundle-manifest asset-bundles/static-bundles.json
+npx hst run web dev browser --rebuild-app-config
+npx hst app-config:clean --expression tv --platform web \
+  --static-bundle-manifest asset-bundles/static-bundles.json
+```
+
 # Getting started
 
 Ensure you have Node.js 24.17.0.

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "buildDate": "2026-07-31T15:02:33+00:00",
-  "buildDateISO": "2026-07-31T15:02:33.275Z",
+  "buildDate": "2026-08-05T08:18:35+00:00",
+  "buildDateISO": "2026-08-05T08:18:35.471Z",
   "timeZone": "UTC",
-  "gitHash": "64c10e3"
+  "gitHash": "63ba7f3"
 }

package/dist/cli.js

@@ -574,7 +574,7 @@ catch (err) {
         process.exit(1);
     }
 })
-    .command('app-config:compile', 'Resolve AppConfig and materialize precompiled theme shapes, bundled fonts, and an asset-bundle manifest', yargs => yargs
+    .command('app-config:compile', 'Resolve AppConfig and materialize precompiled theme shapes, bundled fonts, and static asset bundles', yargs => yargs
     .option('input', { type: 'string', describe: 'Input path, app.config.<name>.json filename, or short selector' })
     .option('cwd', { type: 'string', describe: 'Project root (default: current working directory)' })
     .option('expression', { type: 'string', describe: 'Expression selector such as tv, phone, or tablet' })
@@ -588,6 +588,7 @@ catch (err) {
     .option('bundle-config-key', { type: 'string', default: 'compiledTheme', describe: 'Key written beneath AppConfig assetBundles' })
     .option('bundle-output-dir', { type: 'string', default: 'public/asset-bundles', describe: 'Publishable asset-bundle output root' })
     .option('asset-url-root', { type: 'string', default: '/asset-bundles', describe: 'HTTP URL root written into bundle asset descriptors' })
+    .option('static-bundle-manifest', { type: 'string', describe: 'Static asset-bundle input manifest compiled alongside AppConfig assets' })
     .option('watch', { type: 'boolean', default: false, describe: 'Watch AppConfig inheritance and local bundled files' })
     .option('rebuild', { type: 'boolean', default: false, describe: 'Re-render compiler assets instead of reusing the incremental cache' })
     .option('force', { type: 'boolean', default: false, describe: 'Rewrite unchanged compiler-owned files' }), async (args) => {
@@ -606,6 +607,7 @@ catch (err) {
             bundleConfigKey: args.bundleConfigKey,
             bundleOutputDir: args.bundleOutputDir,
             assetUrlRoot: args.assetUrlRoot,
+            staticBundleManifest: args.staticBundleManifest,
             watch: Boolean(args.watch),
             rebuild: Boolean(args.rebuild),
             force: Boolean(args.force),
@@ -626,7 +628,8 @@ catch (err) {
     .option('platform', { type: 'string', default: 'roku', describe: 'Compilation platform' })
     .option('generated-dir', { type: 'string', describe: 'Generated target root (contains package/)' })
     .option('bundle-id', { type: 'string', describe: 'Asset bundle id to remove' })
-    .option('bundle-output-dir', { type: 'string', default: 'public/asset-bundles', describe: 'Asset-bundle output root' }), args => {
+    .option('bundle-output-dir', { type: 'string', default: 'public/asset-bundles', describe: 'Asset-bundle output root' })
+    .option('static-bundle-manifest', { type: 'string', describe: 'Static asset-bundle input manifest whose compiler-owned outputs should be removed' }), args => {
     try {
         (0, cli_app_config_compile_js_1.runAppConfigCleanCommand)({
             cwd: args.cwd,
@@ -636,6 +639,7 @@ catch (err) {
             generatedDir: args.generatedDir,
             bundleId: args.bundleId,
             bundleOutputDir: args.bundleOutputDir,
+            staticBundleManifest: args.staticBundleManifest,
         });
         process.exit(0);
     }
@@ -758,14 +762,14 @@ catch (err) {
     .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('env', { type: 'string', default: 'prod', describe: 'Safe environment name used only 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 roku:package --ip 192.168.1.10 --installer-password secret --dev-id ABC --signing-password sss --key-pkg mykey.pkg', 'Package and sign with explicit args')
     .example('$0 roku:package --key-pkg-base64 <base64-string>', 'Package using base64-encoded key package')
-    .example('$0 roku:package --env prod', 'Use env vars including ROKU_PKG_KEY_BASE64'), async (args) => {
+    .example('$0 roku:package --env staging', 'Use a custom environment name with env vars including ROKU_PKG_KEY_BASE64'), async (args) => {
     if (args.verbose) {
         process.env.HOSANNA_VERBOSE = '1';
         process.env.HOSANNA_UPDATER_VERBOSE = '1';