@adea-ai/app-framework 0.0.0-stage → 0.24.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (358) hide show
  1. package/LICENSE +201 -0
  2. package/NOTICE +30 -0
  3. package/README.md +1009 -2
  4. package/dist/app/application.d.ts +47 -0
  5. package/dist/app/application.js +115 -0
  6. package/dist/app/create-application.d.ts +13 -0
  7. package/dist/app/create-application.js +178 -0
  8. package/dist/app/service-registry.d.ts +44 -0
  9. package/dist/app/service-registry.js +116 -0
  10. package/dist/appearance/appearance-host.d.ts +62 -0
  11. package/dist/appearance/appearance-host.js +115 -0
  12. package/dist/appearance/appearance-preferences.d.ts +106 -0
  13. package/dist/appearance/appearance-preferences.js +175 -0
  14. package/dist/appearance/composition.d.ts +11 -0
  15. package/dist/appearance/composition.js +16 -0
  16. package/dist/appearance/custom-theme-import.d.ts +14 -0
  17. package/dist/appearance/custom-theme-import.js +315 -0
  18. package/dist/appearance/custom-theme-library.d.ts +146 -0
  19. package/dist/appearance/custom-theme-library.js +378 -0
  20. package/dist/appearance/editor.d.ts +20 -0
  21. package/dist/appearance/editor.js +47 -0
  22. package/dist/appearance/theme-file-importer.d.ts +23 -0
  23. package/dist/appearance/theme-file-importer.js +66 -0
  24. package/dist/appearance/theme-record-adapter.d.ts +26 -0
  25. package/dist/appearance/theme-record-adapter.js +64 -0
  26. package/dist/appearance/theme-registry.d.ts +10 -0
  27. package/dist/appearance/theme-registry.js +16 -0
  28. package/dist/appearance/window-surface.d.ts +5 -0
  29. package/dist/appearance/window-surface.js +9 -0
  30. package/dist/ci/toolchain-identity.d.ts +39 -0
  31. package/dist/ci/toolchain-identity.js +196 -0
  32. package/dist/cli/cef-helper-cli.d.ts +2 -0
  33. package/dist/cli/cef-helper-cli.js +18 -0
  34. package/dist/cli/cli-runner.d.ts +8 -0
  35. package/dist/cli/cli-runner.js +23 -0
  36. package/dist/cli/create-application-cli.d.ts +2 -0
  37. package/dist/cli/create-application-cli.js +40 -0
  38. package/dist/cli/electrobun-shortcut-patch-cli.d.ts +2 -0
  39. package/dist/cli/electrobun-shortcut-patch-cli.js +17 -0
  40. package/dist/cli/framework-update-cli.d.ts +2 -0
  41. package/dist/cli/framework-update-cli.js +40 -0
  42. package/dist/cli/release-assets-plan-cli.d.ts +2 -0
  43. package/dist/cli/release-assets-plan-cli.js +14 -0
  44. package/dist/cli/release-cut-cli.d.ts +2 -0
  45. package/dist/cli/release-cut-cli.js +27 -0
  46. package/dist/cli/release-descriptor-staging-cli.d.ts +2 -0
  47. package/dist/cli/release-descriptor-staging-cli.js +45 -0
  48. package/dist/cli/release-finalize-cli.d.ts +1 -0
  49. package/dist/cli/release-finalize-cli.js +30 -0
  50. package/dist/cli/release-promote-cli.d.ts +2 -0
  51. package/dist/cli/release-promote-cli.js +32 -0
  52. package/dist/cli/release-publish-cli.d.ts +2 -0
  53. package/dist/cli/release-publish-cli.js +48 -0
  54. package/dist/cli/release-sign-cli.d.ts +2 -0
  55. package/dist/cli/release-sign-cli.js +13 -0
  56. package/dist/cli/release-step-cli.d.ts +2 -0
  57. package/dist/cli/release-step-cli.js +44 -0
  58. package/dist/cli/toolchain-identity-cli.d.ts +2 -0
  59. package/dist/cli/toolchain-identity-cli.js +10 -0
  60. package/dist/cli/update-helper-cli.d.ts +1 -0
  61. package/dist/cli/update-helper-cli.js +10 -0
  62. package/dist/cli/windows-runtime-patch-cli.d.ts +2 -0
  63. package/dist/cli/windows-runtime-patch-cli.js +17 -0
  64. package/dist/desktop/application-command-client.d.ts +15 -0
  65. package/dist/desktop/application-command-client.js +21 -0
  66. package/dist/desktop/channel-handshake.d.ts +32 -0
  67. package/dist/desktop/channel-handshake.js +111 -0
  68. package/dist/desktop/channel-proof.d.ts +43 -0
  69. package/dist/desktop/channel-proof.js +85 -0
  70. package/dist/desktop/client-assets.d.ts +7 -0
  71. package/dist/desktop/client-assets.js +59 -0
  72. package/dist/desktop/desktop-client.d.ts +23 -0
  73. package/dist/desktop/desktop-client.js +231 -0
  74. package/dist/desktop/desktop-gateway.d.ts +18 -0
  75. package/dist/desktop/desktop-gateway.js +146 -0
  76. package/dist/desktop/desktop-host.d.ts +48 -0
  77. package/dist/desktop/desktop-host.js +208 -0
  78. package/dist/desktop/desktop-stream.d.ts +36 -0
  79. package/dist/desktop/desktop-stream.js +231 -0
  80. package/dist/desktop/loopback-policy.d.ts +19 -0
  81. package/dist/desktop/loopback-policy.js +23 -0
  82. package/dist/desktop/open-url-channel.d.ts +15 -0
  83. package/dist/desktop/open-url-channel.js +55 -0
  84. package/dist/desktop/string-policy.d.ts +2 -0
  85. package/dist/desktop/string-policy.js +11 -0
  86. package/dist/framework-source.json +1 -0
  87. package/dist/installer/archive-entry.d.ts +6 -0
  88. package/dist/installer/archive-entry.js +14 -0
  89. package/dist/installer/command-artifact.d.ts +47 -0
  90. package/dist/installer/command-artifact.js +261 -0
  91. package/dist/installer/command-qualification-command.d.ts +12 -0
  92. package/dist/installer/command-qualification-command.js +71 -0
  93. package/dist/installer/hosted-runner.d.ts +4 -0
  94. package/dist/installer/hosted-runner.js +10 -0
  95. package/dist/installer/installed-payload.d.ts +29 -0
  96. package/dist/installer/installed-payload.js +312 -0
  97. package/dist/installer/installer-ci-bootstrap.d.ts +26 -0
  98. package/dist/installer/installer-ci-bootstrap.js +160 -0
  99. package/dist/installer/installer-ci-preflight.d.ts +1 -0
  100. package/dist/installer/installer-ci-preflight.js +49 -0
  101. package/dist/installer/installer-ci-worker.d.ts +1 -0
  102. package/dist/installer/installer-ci-worker.js +105 -0
  103. package/dist/installer/installer-extraction.d.ts +14 -0
  104. package/dist/installer/installer-extraction.js +289 -0
  105. package/dist/installer/installer-fetch-guard.d.ts +15 -0
  106. package/dist/installer/installer-fetch-guard.js +50 -0
  107. package/dist/installer/installer-identity.d.ts +23 -0
  108. package/dist/installer/installer-identity.js +286 -0
  109. package/dist/installer/installer-layout.d.ts +21 -0
  110. package/dist/installer/installer-layout.js +89 -0
  111. package/dist/installer/installer-observation.d.ts +64 -0
  112. package/dist/installer/installer-observation.js +473 -0
  113. package/dist/installer/installer-process-cleanup.d.ts +18 -0
  114. package/dist/installer/installer-process-cleanup.js +158 -0
  115. package/dist/installer/installer-qualification-command.d.ts +11 -0
  116. package/dist/installer/installer-qualification-command.js +71 -0
  117. package/dist/installer/installer-renderer-evidence.d.ts +43 -0
  118. package/dist/installer/installer-renderer-evidence.js +136 -0
  119. package/dist/installer/installer-upgrade-command.d.ts +37 -0
  120. package/dist/installer/installer-upgrade-command.js +172 -0
  121. package/dist/installer/installer-worker-guard.d.ts +21 -0
  122. package/dist/installer/installer-worker-guard.js +72 -0
  123. package/dist/installer/native-executable.d.ts +5 -0
  124. package/dist/installer/native-executable.js +21 -0
  125. package/dist/installer/upgrade-asset-download.d.ts +13 -0
  126. package/dist/installer/upgrade-asset-download.js +41 -0
  127. package/dist/installer/write-all.d.ts +6 -0
  128. package/dist/installer/write-all.js +11 -0
  129. package/dist/native/app-bundle.d.ts +28 -0
  130. package/dist/native/app-bundle.js +60 -0
  131. package/dist/native/cef-helper.d.ts +28 -0
  132. package/dist/native/cef-helper.js +402 -0
  133. package/dist/native/desktop-build-hook.d.ts +7 -0
  134. package/dist/native/desktop-build-hook.js +20 -0
  135. package/dist/native/electrobun-source-patch.d.ts +25 -0
  136. package/dist/native/electrobun-source-patch.js +93 -0
  137. package/dist/native/linux-cef-links.d.ts +2 -0
  138. package/dist/native/linux-cef-links.js +15 -0
  139. package/dist/native/native-secret-store.d.ts +27 -0
  140. package/dist/native/native-secret-store.js +70 -0
  141. package/dist/native/native-utilities.d.ts +24 -0
  142. package/dist/native/native-utilities.js +85 -0
  143. package/dist/native/partitioned-window.d.ts +34 -0
  144. package/dist/native/partitioned-window.js +44 -0
  145. package/dist/native/renderer-profile.d.ts +53 -0
  146. package/dist/native/renderer-profile.js +30 -0
  147. package/dist/native/secure-window.d.ts +38 -0
  148. package/dist/native/secure-window.js +77 -0
  149. package/dist/native/sidecar-services.d.ts +23 -0
  150. package/dist/native/sidecar-services.js +46 -0
  151. package/dist/native/sidecar.d.ts +81 -0
  152. package/dist/native/sidecar.js +250 -0
  153. package/dist/native/window-bootstrap.d.ts +24 -0
  154. package/dist/native/window-bootstrap.js +63 -0
  155. package/dist/native/window-options.d.ts +32 -0
  156. package/dist/native/window-options.js +23 -0
  157. package/dist/native/windows-build-hook-internal.d.ts +2 -0
  158. package/dist/native/windows-build-hook-internal.js +32 -0
  159. package/dist/native/windows-build-hook.d.ts +2 -0
  160. package/dist/native/windows-build-hook.js +12 -0
  161. package/dist/native/windows-runtime-patch-internal.d.ts +3 -0
  162. package/dist/native/windows-runtime-patch-internal.js +20 -0
  163. package/dist/native/windows-runtime-patch.d.ts +4 -0
  164. package/dist/native/windows-runtime-patch.js +12 -0
  165. package/dist/release/feed-release-cut.d.ts +23 -0
  166. package/dist/release/feed-release-cut.js +93 -0
  167. package/dist/release/feed-state.d.ts +25 -0
  168. package/dist/release/feed-state.js +81 -0
  169. package/dist/release/framework-package-publish.d.ts +21 -0
  170. package/dist/release/framework-package-publish.js +127 -0
  171. package/dist/release/framework-update.d.ts +30 -0
  172. package/dist/release/framework-update.js +139 -0
  173. package/dist/release/github-cli.d.ts +6 -0
  174. package/dist/release/github-cli.js +16 -0
  175. package/dist/release/github-release-assets.d.ts +3 -0
  176. package/dist/release/github-release-assets.js +24 -0
  177. package/dist/release/github-release-cut.d.ts +14 -0
  178. package/dist/release/github-release-cut.js +174 -0
  179. package/dist/release/github-release-lookup.d.ts +7 -0
  180. package/dist/release/github-release-lookup.js +29 -0
  181. package/dist/release/github-release-promotion.d.ts +10 -0
  182. package/dist/release/github-release-promotion.js +78 -0
  183. package/dist/release/github-release-provenance.d.ts +9 -0
  184. package/dist/release/github-release-provenance.js +27 -0
  185. package/dist/release/github-release-publisher.d.ts +9 -0
  186. package/dist/release/github-release-publisher.js +63 -0
  187. package/dist/release/github-release-qualification.d.ts +12 -0
  188. package/dist/release/github-release-qualification.js +80 -0
  189. package/dist/release/local-provenance.d.ts +24 -0
  190. package/dist/release/local-provenance.js +72 -0
  191. package/dist/release/local-release.d.ts +133 -0
  192. package/dist/release/local-release.js +387 -0
  193. package/dist/release/macos-dmg.d.ts +22 -0
  194. package/dist/release/macos-dmg.js +91 -0
  195. package/dist/release/release-artifact.d.ts +6 -0
  196. package/dist/release/release-artifact.js +38 -0
  197. package/dist/release/release-assets-plan.d.ts +14 -0
  198. package/dist/release/release-assets-plan.js +65 -0
  199. package/dist/release/release-config.d.ts +76 -0
  200. package/dist/release/release-config.js +180 -0
  201. package/dist/release/release-cut-command.d.ts +13 -0
  202. package/dist/release/release-cut-command.js +39 -0
  203. package/dist/release/release-cut.d.ts +54 -0
  204. package/dist/release/release-cut.js +76 -0
  205. package/dist/release/release-descriptor-staging.d.ts +34 -0
  206. package/dist/release/release-descriptor-staging.js +147 -0
  207. package/dist/release/release-finalize.d.ts +16 -0
  208. package/dist/release/release-finalize.js +104 -0
  209. package/dist/release/release-promotion-command.d.ts +12 -0
  210. package/dist/release/release-promotion-command.js +28 -0
  211. package/dist/release/release-promotion.d.ts +29 -0
  212. package/dist/release/release-promotion.js +57 -0
  213. package/dist/release/release-publication.d.ts +33 -0
  214. package/dist/release/release-publication.js +138 -0
  215. package/dist/release/release-publish-command.d.ts +7 -0
  216. package/dist/release/release-publish-command.js +91 -0
  217. package/dist/release/release-qualification.d.ts +106 -0
  218. package/dist/release/release-qualification.js +135 -0
  219. package/dist/release/release-staging.d.ts +9 -0
  220. package/dist/release/release-staging.js +61 -0
  221. package/dist/release/release-steps.d.ts +38 -0
  222. package/dist/release/release-steps.js +147 -0
  223. package/dist/release/retained-release-build.d.ts +19 -0
  224. package/dist/release/retained-release-build.js +122 -0
  225. package/dist/shell/app-shell.d.ts +61 -0
  226. package/dist/shell/app-shell.js +306 -0
  227. package/dist/shell/app-utilities.d.ts +122 -0
  228. package/dist/shell/app-utilities.js +334 -0
  229. package/dist/shell/application-menu-commands.d.ts +5 -0
  230. package/dist/shell/application-menu-commands.js +11 -0
  231. package/dist/shell/application-menu.d.ts +61 -0
  232. package/dist/shell/application-menu.js +208 -0
  233. package/dist/shell/help-shortcuts.d.ts +12 -0
  234. package/dist/shell/help-shortcuts.js +22 -0
  235. package/dist/shell/navigation-drawer.d.ts +12 -0
  236. package/dist/shell/navigation-drawer.js +42 -0
  237. package/dist/shell/settings-sections.d.ts +31 -0
  238. package/dist/shell/settings-sections.js +50 -0
  239. package/dist/shell/shortcut-platform.d.ts +17 -0
  240. package/dist/shell/shortcut-platform.js +25 -0
  241. package/dist/update-helper.bundle.js +260 -0
  242. package/dist/updates/channel-update-manager.d.ts +46 -0
  243. package/dist/updates/channel-update-manager.js +114 -0
  244. package/dist/updates/desktop-updater.d.ts +104 -0
  245. package/dist/updates/desktop-updater.js +345 -0
  246. package/dist/updates/release-feed.d.ts +61 -0
  247. package/dist/updates/release-feed.js +111 -0
  248. package/dist/updates/release-location.d.ts +9 -0
  249. package/dist/updates/release-location.js +80 -0
  250. package/dist/updates/release-version.d.ts +12 -0
  251. package/dist/updates/release-version.js +43 -0
  252. package/dist/updates/signed-release.d.ts +63 -0
  253. package/dist/updates/signed-release.js +162 -0
  254. package/dist/updates/stable-file.d.ts +10 -0
  255. package/dist/updates/stable-file.js +22 -0
  256. package/dist/updates/update-adapter.d.ts +57 -0
  257. package/dist/updates/update-adapter.js +72 -0
  258. package/dist/updates/update-arm.d.ts +24 -0
  259. package/dist/updates/update-arm.js +95 -0
  260. package/dist/updates/update-channel-store.d.ts +8 -0
  261. package/dist/updates/update-channel-store.js +72 -0
  262. package/dist/updates/update-discovery.d.ts +13 -0
  263. package/dist/updates/update-discovery.js +56 -0
  264. package/dist/updates/update-download.d.ts +14 -0
  265. package/dist/updates/update-download.js +67 -0
  266. package/dist/updates/update-exclusive-rename.d.ts +2 -0
  267. package/dist/updates/update-exclusive-rename.js +52 -0
  268. package/dist/updates/update-extraction.d.ts +18 -0
  269. package/dist/updates/update-extraction.js +183 -0
  270. package/dist/updates/update-handoff-plan.d.ts +22 -0
  271. package/dist/updates/update-handoff-plan.js +28 -0
  272. package/dist/updates/update-helper.d.ts +24 -0
  273. package/dist/updates/update-helper.js +56 -0
  274. package/dist/updates/update-launch.d.ts +5 -0
  275. package/dist/updates/update-launch.js +27 -0
  276. package/dist/updates/update-manager.d.ts +40 -0
  277. package/dist/updates/update-manager.js +83 -0
  278. package/dist/updates/update-process-fence.d.ts +10 -0
  279. package/dist/updates/update-process-fence.js +114 -0
  280. package/dist/updates/update-resume.d.ts +13 -0
  281. package/dist/updates/update-resume.js +34 -0
  282. package/dist/updates/update-shutdown.d.ts +15 -0
  283. package/dist/updates/update-shutdown.js +29 -0
  284. package/dist/updates/update-state.d.ts +30 -0
  285. package/dist/updates/update-state.js +18 -0
  286. package/dist/updates/update-swap-stage.d.ts +27 -0
  287. package/dist/updates/update-swap-stage.js +58 -0
  288. package/dist/updates/update-swap.d.ts +10 -0
  289. package/dist/updates/update-swap.js +30 -0
  290. package/dist/views/app-about.d.ts +22 -0
  291. package/dist/views/app-about.js +43 -0
  292. package/dist/views/app-appearance.d.ts +11 -0
  293. package/dist/views/app-appearance.js +42 -0
  294. package/dist/views/app-help.d.ts +17 -0
  295. package/dist/views/app-help.js +42 -0
  296. package/dist/views/app-settings.d.ts +26 -0
  297. package/dist/views/app-settings.js +97 -0
  298. package/dist/views/appearance-surface.d.ts +9 -0
  299. package/dist/views/appearance-surface.js +334 -0
  300. package/dist/views/update-surface.d.ts +34 -0
  301. package/dist/views/update-surface.js +64 -0
  302. package/package.json +374 -4
  303. package/src/app/application.tsx +138 -0
  304. package/src/appearance/appearance-host.tsx +205 -0
  305. package/src/appearance/appearance-preferences.ts +287 -0
  306. package/src/appearance/composition.ts +29 -0
  307. package/src/appearance/custom-theme-import.ts +424 -0
  308. package/src/appearance/custom-theme-library.ts +600 -0
  309. package/src/appearance/editor.ts +94 -0
  310. package/src/appearance/theme-file-importer.ts +103 -0
  311. package/src/appearance/theme-record-adapter.ts +106 -0
  312. package/src/appearance/theme-registry.ts +20 -0
  313. package/src/appearance/window-surface.ts +18 -0
  314. package/src/desktop/client-assets.ts +75 -0
  315. package/src/native/electrobun-cef-main-frame-bridges.patch +63 -0
  316. package/src/native/electrobun-windows-shortcut-com.patch +923 -0
  317. package/src/native/renderer-profile.ts +27 -0
  318. package/src/native/window-options.ts +24 -0
  319. package/src/shell/app-shell.tsx +294 -0
  320. package/src/shell/app-utilities.tsx +437 -0
  321. package/src/shell/help-shortcuts.ts +24 -0
  322. package/src/shell/navigation-drawer.tsx +36 -0
  323. package/src/shell/settings-sections.ts +74 -0
  324. package/src/shell/shortcut-platform.ts +35 -0
  325. package/src/updates/release-version.ts +57 -0
  326. package/src/updates/update-adapter.ts +129 -0
  327. package/src/updates/update-state.ts +34 -0
  328. package/src/views/app-about.tsx +44 -0
  329. package/src/views/app-appearance.tsx +32 -0
  330. package/src/views/app-help.tsx +43 -0
  331. package/src/views/app-settings.tsx +88 -0
  332. package/src/views/appearance-surface.tsx +427 -0
  333. package/src/views/update-surface.tsx +85 -0
  334. package/templates/application/.gitattributes +1 -0
  335. package/templates/application/.github/workflows/release-assets.yml +29 -0
  336. package/templates/application/.github/workflows/release-finalize.yml +29 -0
  337. package/templates/application/.github/workflows/release-please.yml +19 -0
  338. package/templates/application/.github/workflows/release.yml +29 -0
  339. package/templates/application/.github/workflows/validation.yml +28 -0
  340. package/templates/application/.oxfmtrc.json +6 -0
  341. package/templates/application/.oxlintrc.json +48 -0
  342. package/templates/application/.release-please-manifest.json +3 -0
  343. package/templates/application/README.md +47 -0
  344. package/templates/application/electrobun.config.ts +22 -0
  345. package/templates/application/release-please-config.json +12 -0
  346. package/templates/application/scripts/app-version.ts +9 -0
  347. package/templates/application/scripts/build-desktop.ts +34 -0
  348. package/templates/application/scripts/secure-build.ts +1 -0
  349. package/templates/application/scripts/stage-release.ts +21 -0
  350. package/templates/application/src/bun/index.ts +80 -0
  351. package/templates/application/src/electrobun.d.ts +27 -0
  352. package/templates/application/src/web/index.html +12 -0
  353. package/templates/application/src/web/main.tsx +97 -0
  354. package/templates/application/src/web/public/icon.svg +1 -0
  355. package/templates/application/src/web/style.css +3 -0
  356. package/templates/application/tests/app-config.test.ts +9 -0
  357. package/templates/application/tsconfig.json +15 -0
  358. package/templates/application/vite.config.ts +10 -0
package/README.md CHANGED
@@ -1,3 +1,1010 @@
1
- # Temporary Holding Version
1
+ # App framework
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Reusable application framework for Adea and Cortana. It provides the shared
4
+ application shell and appearance surfaces, an Electrobun desktop host and
5
+ service bridge, application generation, packaging, updater, and release tools.
6
+ Each consuming app supplies its identity, navigation, views, services, and
7
+ application-specific security policy. The [framework contract](docs/framework-contract.md)
8
+ defines that ownership split and the acceptance gates.
9
+
10
+ `serveClient(request, { root, deniedPaths, transformHtml })` serves a local SPA,
11
+ rejects paths that escape its root, and lets the app exclude asset trees and
12
+ inject its bootstrap into HTML. It does not authenticate bridge requests or
13
+ start an HTTP server; the host application owns both.
14
+
15
+ `serveClient` is one of the framework's desktop building blocks. Source adapted from
16
+ `adea-ai/adea` at commit `6155d18941acbb14d9099bc2a33a50ee9683a068`,
17
+ `apps/desktop/shell/src/client-assets.ts` (Apache-2.0).
18
+
19
+ `toUpdateState` maps native update snapshots to the published UI update-dialog
20
+ contract. Applications retain ownership of updater trust, confirmation, and
21
+ whether release notes are shown.
22
+
23
+ `release-version` retains Adea's existing channel validation and orders update
24
+ versions by semver on every channel. It was adapted from
25
+ `apps/desktop/shell/src/updates.ts` in `adea-ai/adea` at commit
26
+ `6155d18941acbb14d9099bc2a33a50ee9683a068` (Apache-2.0). Shared release,
27
+ platform packaging, and signed-update modules are documented below; application
28
+ credentials and product-specific release policy stay with each consumer.
29
+
30
+ Release qualification checks attested platform installer evidence and asset
31
+ sizes and SHA-256 digests against the release, and checks the exact producing
32
+ workflow run and installer jobs. Both validation functions must succeed before
33
+ promotion; inputs must come from the authenticated release provider and the
34
+ application's trusted release configuration. These functions do not fetch or
35
+ verify release signatures, create artifacts, publish releases, or promote them.
36
+
37
+ ## Package entry points
38
+
39
+ Import a subpath; the package has no root export. Entries marked _solid_ also
40
+ export TypeScript source under the `solid` condition, which a Vite consumer with
41
+ `vite-plugin-solid` compiles itself. Entries marked _source only_ export
42
+ TypeScript source alone, and the rest resolve to `dist`. The package ships only
43
+ the source those entries reach, plus the Electrobun patches in `src/native`; a
44
+ test checks the file list against the exports.
45
+
46
+ | Area | Subpaths (`@adea-ai/app-framework/<subpath>`) |
47
+ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
48
+ | Application and shell | `application`, `app-shell`, `app-utilities`, `app-settings`, `app-help`, `app-about`, `update-surface` (all _solid_), `service-registry`, `application-menu`, `application-command-client` |
49
+ | Appearance | `appearance-host`, `appearance-preferences`, `appearance-surface`, `custom-theme-library`, `window-surface` (all _solid_) |
50
+ | Desktop host | `desktop-host`, `desktop-gateway`, `desktop-client`, `desktop-stream`, `channel-handshake`, `channel-proof`, `loopback-policy`, `open-url-channel`, `client-assets` (source only) |
51
+ | Native windows and OS | `renderer-profile`, `secure-window`, `partitioned-window`, `window-options` (source only), `native-utilities`, `native-secret-store`, `app-bundle`, `sidecar`, `sidecar-services`, `desktop-build-hook`, `windows-runtime-patch` |
52
+ | Updates | `desktop-updater`, `update-manager`, `channel-update-manager`, `update-channel-store`, `update-discovery`, `update-download`, `update-extraction`, `signed-release`, `update-adapter` (_solid_), `update-state` and `release-version` (source only), `update-helper.js` (bundled helper) |
53
+ | Release tooling | `release-config`, `release-cut`, `release-steps`, `release-staging`, `release-artifact`, `release-assets-plan`, `release-descriptor-staging`, `release-publication`, `release-publish-command`, `release-promotion`, `retained-release-build`, `github-release-publisher`, `github-release-qualification`, `github-release-promotion`, `macos-dmg` |
54
+ | Installer qualification | `installer-layout`, `installer-identity`, `installer-extraction`, `installed-payload`, `installer-observation`, `installer-qualification-command`, `installer-renderer-evidence` |
55
+ | CI | `toolchain-identity` |
56
+
57
+ Commands (package `bin` entries):
58
+
59
+ | Command | Purpose |
60
+ | --------------------------------- | --------------------------------------------------------------------------------------------------- |
61
+ | `create-adea-app` | Generate an application from the starter template. |
62
+ | `adea-update-app-framework` | Move an app's framework tarball, lockfile and workflow pins to a published release together. |
63
+ | `adea-cut-release` | Cut a `dev` or `daily` release from trusted `main`. |
64
+ | `adea-plan-release-assets` | Validate a dispatched release-assets run and resolve its source and version. |
65
+ | `adea-release-step` | Run a per-platform step: `select-retained`, `stage-build`, `inspect`, `qualify`, `qualify-upgrade`. |
66
+ | `adea-sign-release` | Sign one staged archive's release identity. |
67
+ | `adea-sign-release-descriptors` | Sign channel descriptors for payloads every receipt qualified. |
68
+ | `adea-publish-release` | Publish the current trusted release-assets attempt. |
69
+ | `adea-finalize-release` | Publish a qualified Release Please draft as a prerelease. |
70
+ | `adea-promote-release` | Promote the newest qualified daily to stable after the soak. |
71
+ | `adea-cef-helper` | Print the CEF helper cache key, or build the helper. |
72
+ | `adea-patch-windows-runtime` | Apply the checksum-guarded Windows runtime correction. |
73
+ | `adea-patch-electrobun-shortcuts` | Apply the shipped Windows shortcut patch to an Electrobun checkout. |
74
+ | `adea-toolchain-identity` | Fail a cached task when the Node/Bun toolchain differs from its key. |
75
+
76
+ ## Shared application shell
77
+
78
+ `ApplicationShell` composes the published `@adea-ai/ui` rail, toolbar,
79
+ contextual sidebar, resize handle, skip link and tooltip provider. The host
80
+ supplies the app name, mark, destination IDs and icons, active destination,
81
+ navigation callback and view content. Optional slots provide workspace and
82
+ history controls, search, toolbar actions, rail footer and status content.
83
+ The host controls sidebar state and persisted width; the shell restores focus
84
+ after the narrow-screen sidebar closes and handles the advertised search chord.
85
+ The narrow-screen drawer loads the first time the window is narrow, so a wide
86
+ window never loads its dialog code.
87
+
88
+ Consumers must import `@adea-ai/ui/globals.css` and configure Tailwind to scan
89
+ the UI and framework package source. `tests/consumer` shows a buildable packed
90
+ consumer. Run `bun run test`, `bun run typecheck` and `bun run test:packed`
91
+ (the last requires Playwright Chromium, installed with `bunx playwright install
92
+ chromium`). The packed test builds an isolated consumer and exercises keyboard
93
+ navigation, resizing and narrow-screen focus; it does not establish the native
94
+ Electrobun or release requirements.
95
+
96
+ `createServiceRegistry` registers application service handlers with explicit
97
+ input parsing and per-call authorization. A registration can be retired without
98
+ removing a later replacement; if it is retired while authorization is pending,
99
+ the handler will not start. Retirement does not cancel work already started. A host can pass a synchronous
100
+ channel and scope recheck to `dispatch`; the check runs immediately before the handler
101
+ starts, after asynchronous authorization. Long-running services must perform
102
+ their own checks at later mutation boundaries.
103
+ A handler that throws `ServiceError(code, message)` returns
104
+ `{ ok: false, code: 'service_error', error: { code, message } }` so the caller
105
+ can show the message; any other thrown value becomes a bare `service_failed`.
106
+ The registry is an in-process boundary, not an authentication mechanism: only a
107
+ transport that has independently verified the caller may supply its principal.
108
+ Host code remains responsible for capability and resource authorization,
109
+ bounded transport payloads, and safe result serialization.
110
+
111
+ `ApplicationThemeProvider` uses the shared theme provider with a required
112
+ application-specific storage key. `ApplicationUtilities`, mounted in the shell
113
+ footer, supplies the account menu and lazily loaded About, Appearance, and
114
+ Updates dialogs. The app supplies identity, optional native link and clipboard
115
+ adapters, and an updater and channel adapter when available. The default
116
+ appearance panel applies changes through the shared provider. A host may supply
117
+ its own appearance surface; Adea's existing preview, cancellation, imported
118
+ theme library and V2 preference behavior are available through the appearance
119
+ provider and editor described below.
120
+
121
+ `ApplicationSettings` is the shared settings dialog: grouped section navigation
122
+ that becomes a horizontal strip on narrow windows, beside the selected panel.
123
+ Pass `utilities.settings.sections` (validated by `defineSettingsSections`); the
124
+ framework adds its Appearance section first and opens the dialog from the
125
+ account menu's Settings item, the platform settings chord (⌘, or Ctrl+,) and
126
+ `#settings/<section>` deep links. Each app owns its sections' content and
127
+ persistence. `utilities.help` supplies the shared Help Center with the app's
128
+ links and shortcuts; the framework appends the chords it binds itself. The
129
+ `commands` callback returns functions that open Settings, Appearance, About,
130
+ Help and Updates so native menus and app-owned triggers reuse the same
131
+ surfaces. Apps that already supply `onSettings` or `onHelp` keep their own
132
+ surfaces.
133
+
134
+ `utilities.accountMenu` adjusts the account menu without replacing it: `label`
135
+ (default `Application settings`), `busy` for an in-flight sign-in or sign-out,
136
+ `onIntent` (hover or focus, for prefetching), `settingsShortcut` and
137
+ `settingsKeyshortcuts` for the Settings row, `appearance: false` to hide the
138
+ Appearance item, and `updates: 'always'` to keep Updates visible and enabled on
139
+ every runtime (without an updater it opens the dialog's desktop-only
140
+ explanation). `onUpdates` replaces the shared updates dialog with an app-owned
141
+ one. `utilities.settings.appearance` places the framework Appearance section
142
+ (`{ position: 'start' | 'end' | index, group, label }`) or omits it with
143
+ `false`, in which case `openAppearance` opens the standalone Appearance dialog.
144
+ `defaultSection` names the section opened when none is requested. `open`, `section`, `onOpenChange`
145
+ and `onSectionChange` let an app-owned store drive and observe the dialog; omit
146
+ them for the default local state.
147
+
148
+ `identity.platform` is the label About shows. Shortcut hints use
149
+ `identity.shortcutPlatform` (`'mac'` or `'other'`); when it is omitted, a
150
+ platform label naming an Apple OS means `mac` and any other label (`desktop`,
151
+ `web`) defers to the browser's platform.
152
+
153
+ The shared surfaces are also exported standalone for apps that keep their own
154
+ menu, each as its own module to load with `lazy()`: `app-about`
155
+ (`ApplicationAbout`), `app-help` and `update-surface`
156
+ (`ApplicationUpdateSurface`). The update surface accepts a channel as
157
+ `{ read, persist }` or as a service with `{ channel, setChannel }`, optional
158
+ `channelLabels` and `channelDescriptions`, and `onUpdateState` to mirror every
159
+ updater snapshot into a pending-update badge without a second checker.
160
+ `update-adapter` holds the dependency-free helpers for boot code:
161
+ `nativeUpdateAdapter` bridges a snake_case native updater, `mirrorUpdateState`
162
+ wraps an adapter, `updateChannelStore` normalizes either channel shape and
163
+ `browserUpdateAdapter` describes a build without an installer.
164
+
165
+ Modules that hold shared state (`window-surface`, `custom-theme-library`,
166
+ `appearance-preferences`) are exported with the same `solid`
167
+ source condition as the components that import them, so a Vite consumer loads
168
+ one copy of each; a test enforces this for every `solid` export.
169
+
170
+ `application-menu` builds the native application, Edit, View, Window and Help
171
+ menus for macOS and Windows (Electrobun has no Linux application menu; the same
172
+ surfaces stay in the window's account menu). Pass the result to Electrobun's
173
+ `ApplicationMenu.setApplicationMenu` and route `application-menu-clicked` events
174
+ through `createApplicationMenuHandler`. Help links must be HTTPS and open in the
175
+ system browser; app-owned sections deliver their actions to the app.
176
+ `createApplicationCommandBroadcaster` registers the `shell.commands` desktop
177
+ stream, and `connectApplicationCommands` in the window opens About, Settings,
178
+ Help and Updates through `ApplicationUtilities` commands. Commands carry only a
179
+ name over the authenticated channel. The generated app wires both sides.
180
+
181
+ `defineApplication` validates an app's identity, storage key, unique view IDs,
182
+ initial view, labels and render functions. `Application` mounts those views in
183
+ the shared shell and utilities, with local navigation by default or a supplied
184
+ router. Optional theme-provider configuration, footer and toolbar slots let a
185
+ host preserve its own preference store and integrations. The packed-consumer
186
+ fixture demonstrates this API. `create-adea-app` generates a desktop-capable
187
+ application, and the framework provides the Electrobun host and release tools;
188
+ each consumer still configures its own identity, services, credentials, and
189
+ release policy.
190
+
191
+ `createLoopbackPolicy` and the request-metadata predicates screen foreign Host,
192
+ Origin and browser fetch-site values before privileged requests reach a native
193
+ transport. These headers can be forged by a local process and are not
194
+ credentials: they must not be used alone to disclose bootstrap secrets or
195
+ invoke services. The Electrobun host authenticates its native window channel
196
+ before dispatching privileged services; service authorization and resource
197
+ policy remain application-owned.
198
+
199
+ `appearance-preferences` exposes Adea's V2 appearance codec, persistence, and
200
+ first-paint script. The codec stores the `appearance` document and quarantines
201
+ unreadable or newer records before replacing them. Pass
202
+ `createAppearancePersistence()` as the shared theme provider's `persistence`
203
+ option and put `appearanceThemeScript()` in the document head before rendering. The appearance provider and editor below
204
+ include imported-theme management and reversible preview settings. See NOTICE
205
+ for donor attribution.
206
+
207
+ `custom-theme-library` retains imported theme records and their existing storage
208
+ format, including the separate recovery key and the original color-contrast
209
+ validation. The appearance host combines the published built-in catalogue with
210
+ the imported variants. The appearance editor handles theme import and editing.
211
+
212
+ `appearance-host` supplies the V2 appearance provider and context, including
213
+ imported variants, draft previews, native translucency capability, and a
214
+ first-paint script component. Supply `Application`'s `themeProvider` to its
215
+ `ThemeProvider` when preserving that contract; the default provider remains
216
+ available for apps using their own storage key. The appearance editor can be provided to the utilities surface.
217
+
218
+ `appearance-surface` exports the shared appearance editor and its popover,
219
+ including reversible previews, theme-file import, and font and surface settings.
220
+ Use it with the V2 appearance provider; pass `AppearancePanel` as the utilities
221
+ appearance slot. Desktop hosts can register a native surface mirror through
222
+ `window-surface`. The host remains responsible for implementing the native
223
+ window operation.
224
+
225
+ `channel-proof` verifies the existing signed invoke proof over a channel,
226
+ credential, timestamp, nonce and exact body. It checks the host's current
227
+ channel lookup on every call and rejects replays and forged proofs. This is
228
+ not a channel handshake or authorization: the native host must securely
229
+ deliver credentials, bound request bodies before buffering, revoke channels,
230
+ and recheck authorization and channel lifetime after asynchronous work. The
231
+ legacy proof does not bind an HTTP method or path: routes sharing that proof
232
+ context must share one replay verifier and enforce their own request routing.
233
+ The host must preserve the exact UTF-8 body bytes used to produce the proof.
234
+
235
+ `channel-handshake` creates expiring, single-use bootstrap capabilities and
236
+ channel credentials and supports revocation. The host must deliver bootstrap
237
+ secrets through the trusted native window, not a loopback HTTP response, and
238
+ revoke channels when that window is replaced or closed. This in-process API
239
+ does not implement the native window, transport, streaming, or authorization.
240
+
241
+ `desktop-gateway` connects the channel handshake, signed invoke proof, and
242
+ service registry using bounded UTF-8 JSON requests. It screens loopback origin
243
+ metadata, but authenticates with the channel credentials rather than headers.
244
+ The gateway bounds concurrent requests and body-read time. Invoke bodies are
245
+ limited to 256 KiB unless a service registers a larger `maxBodyBytes` (at most
246
+ 16 MiB); that limit applies to that service alone. Native bootstrap
247
+ delivery, streaming, window lifecycle, timeouts for service work, and
248
+ application-specific authorization remain host work.
249
+
250
+ `renderer-profile` selects the desktop renderer consistently for both the
251
+ Electrobun build and window. `createRendererProfile()` selects the operating
252
+ system webview and sets `bundleCEF: false` on macOS, Windows and Linux; pass
253
+ `'cef'` to opt into bundling Chromium. Merge the per-platform `build` fragments
254
+ with the app's signing and packaging options, and pass the profile's `renderer`
255
+ to `createWindowOptions`. Native-renderer dependencies and installed artifact
256
+ contents still need platform-specific packaging verification.
257
+
258
+ The internal `window-bootstrap` module is an experimental native-window proof and preload. Its
259
+ secret must never be served as an unauthenticated HTTP response or logged. It
260
+ requires a native renderer that protects the preload source from untrusted
261
+ frames and prevents untrusted main-frame navigation before script injection.
262
+ Packaged native probes exercise these boundaries on macOS, Windows and Linux;
263
+ installed-app and product-specific qualification remain separate requirements.
264
+
265
+ `desktop-host` and `desktop-client` are the in-progress native host and signed
266
+ service client. The host creates a blank window with Electrobun's bridge
267
+ sandbox enabled, installs its
268
+ navigation rules, and only then loads the loopback client. The client obtains a
269
+ window-bound bootstrap, signs service calls and supports explicit reconnect;
270
+ it does not replay a failed call. Set `portFile` to a path in an existing,
271
+ app-owned data directory to preserve the loopback origin and its browser
272
+ preferences across restarts. A malformed record or occupied port fails closed;
273
+ the host never silently selects a new origin. Electrobun 2.0.5 configures CEF
274
+ with Chromium's operating-system sandbox disabled; the bridge sandbox and
275
+ web-security flags do not provide that OS process isolation. A packaged native
276
+ probe exercises both
277
+ renderer profiles with `bun run build && bun scripts/test-native-window.ts`
278
+ and `bun scripts/test-native-window.ts --cef`. Hosted probes have exercised both renderers on all three platforms for 2.0.1, including persistence across restarts. Electrobun 2.0.5 still requires hosted platform qualification.
279
+ Streaming, additional native services, installed-app qualification, and Adea
280
+ compatibility remain open.
281
+
282
+ Electrobun's `BrowserView` accepts a browser-data `partition`, but its
283
+ `BrowserWindow` (2.0.1 through 2.0.5) does not forward one to the view it
284
+ creates. `constructPartitionedWindow()` from `partitioned-window` constructs a
285
+ window on stock Electrobun with its view in the requested partition, for
286
+ example `persist:<profile>` for a separate persistent profile:
287
+
288
+ ```ts
289
+ import { BrowserView, BrowserWindow } from 'electrobun/bun'
290
+ import { constructPartitionedWindow } from '@adea-ai/app-framework/partitioned-window'
291
+
292
+ const window = constructPartitionedWindow({
293
+ BrowserView,
294
+ partition: `persist:${profileId}`,
295
+ construct: () => new BrowserWindow({ title: 'Example', url: null }),
296
+ })
297
+ ```
298
+
299
+ It applies the partition only during that synchronous construction and fails
300
+ closed, closing the window, unless the window's single view reports the
301
+ requested partition. Without a partition it is a plain constructor call, and it
302
+ can wrap the `construct` callback given to `desktop-host`.
303
+
304
+ The `create-adea-app` command generates a new application
305
+ from an identity, framework package specifier and renderer choice. The starter
306
+ provides the shared shell, appearance, one view and one desktop service. The
307
+ framework package specifier must refer to a distributable package available to
308
+ the new project. Its release workflows call this framework release's reusable
309
+ workflows on the shared schedule (pinned to the release tag; run
310
+ `bunx adea-update-app-framework` to pin the commit) and stay off until the
311
+ repository sets `DESKTOP_RELEASES_ENABLED=true` with a release signing key.
312
+ Native application services and product-specific authorization must still be
313
+ added before distribution. Run `bun run test:generated` for an isolated packed-consumer web
314
+ build and browser check; `bun scripts/test-generated.ts --desktop` additionally
315
+ builds the native bundle for the current platform.
316
+
317
+ `signed-release` provides a separate version 2 Ed25519 descriptor that binds
318
+ application, repository, channel, version, source and workflow commits, run,
319
+ platform, architecture, asset URL, size and digest. The verifier requires a
320
+ matching application-owned trust policy and key ID before checking artifact
321
+ bytes, including through a bounded streaming hash. Daily artifacts correspond
322
+ to the existing opt-in pre-release channel; stable promotion requires a newly
323
+ signed stable descriptor. This API does not publish, discover, install or roll
324
+ back releases. Callers must set download deadlines, enforce version policy and
325
+ protect signing keys.
326
+
327
+ `release-artifact` hashes a staged archive and signs its complete release
328
+ identity. The `adea-sign-release` command accepts an identity JSON file and
329
+ archive path, reads `ADEA_RELEASE_SIGNING_KEY` as a PKCS#8 PEM private key,
330
+ and writes the signed descriptor to standard output. Keep the staged archive
331
+ immutable between hashing, qualification and upload; the signer detects size
332
+ and metadata changes while reading but cannot prevent later replacement.
333
+ Provide the key through the CI secret store and restrict signing to trusted
334
+ release jobs. The command does not publish the artifact.
335
+
336
+ The CEF profile suppresses Electrobun's insecure web-security and remote-debug
337
+ defaults. The pinned Electrobun 2.0.5 Windows system-webview implementation
338
+ hardcodes `--disable-web-security`; its `chromiumFlags` configuration does not
339
+ control WebView2. The `desktop-build-hook` applies the checksum-guarded runtime
340
+ correction before packaging; the packaged Windows system-webview probe exercises
341
+ cross-origin isolation, navigation, service calls and restart persistence.
342
+
343
+ Electrobun 2.0.5's CEF renderer helper installs `__electrobunEventBridge`,
344
+ `__electrobunHostBridge`, `__electrobunBunBridge` and
345
+ `__electrobunInternalBridge` in every frame, and their messages reach the
346
+ browser process as if the app's main frame sent them, so a cross-origin iframe
347
+ could drive Electrobun's internal RPC. `electrobun-cef-main-frame-bridges.patch`
348
+ installs them in the main frame only. The `desktop-build-hook` replaces every
349
+ bundled CEF helper with that build before Electrobun signs the bundle, so the
350
+ helper is signed with the app; bundles without CEF are untouched. It accepts
351
+ only the pinned stock helper bytes and fails closed on anything else, and on any
352
+ CEF target other than macOS arm64, Linux x64 or Windows x64. The patched helper
353
+ is built once per pinned source, patch and CEF version: the hook fetches the
354
+ three helper sources at the pinned commit, applies the digest-pinned patch,
355
+ downloads the digest-pinned CEF minimal distribution, and compiles the helper
356
+ as Electrobun's own build does (CMake and Xcode on macOS, CMake and g++ on
357
+ Linux, CMake and Visual Studio C++ on Windows). The result is cached under
358
+ `ADEA_CEF_HELPER_CACHE` when set, otherwise the user cache directory;
359
+ `adea-cef-helper key` prints the cache key for CI and `adea-cef-helper build`
360
+ fills the cache ahead of a build. The packaged native probe loads a cross-site
361
+ frame in an unsandboxed CEF window and requires all four bridges in the main
362
+ frame and none in the subframe.
363
+
364
+ `release-publication` validates installer receipts and signed discovery
365
+ descriptors against the exact staged payloads before publication. It refuses
366
+ asset replacement, rechecks source and workflow provenance, uploads the
367
+ qualification receipt before discovery assets, and verifies provider-reported
368
+ digests. `github-release-publisher` provides the GitHub adapter using `gh` and
369
+ a trusted release-job token. The caller must protect the staged files from
370
+ concurrent changes, configure trusted keys and run the installer and completed
371
+ workflow qualification checks before promotion. This does not create releases,
372
+ configure schedules, install artifacts or promote stable releases.
373
+
374
+ The experimental Windows SDK lane checks out Electrobun 2.0.5 at its exact
375
+ source commit, verifies the native wrapper source digest, removes the upstream
376
+ WebView2 arguments that disable browser security, and builds a replacement from
377
+ source. Its packaged probe confirms service access, cross-origin isolation,
378
+ window lifecycle and navigation. The checksum-guarded pre-packaging hook applies
379
+ the equivalent correction to the pinned distributed runtime.
380
+
381
+ For the pinned unsigned Electrobun 2.0.5 Windows x64 wrapper, the experimental
382
+ `adea-patch-windows-runtime` command provides a deterministic alternative to
383
+ rebuilding the SDK. It verifies the exact upstream DLL hash, PE architecture,
384
+ unsigned status, argument bytes and patched output hash, then writes a new file
385
+ without overwriting the original. Apply it before any application code signing.
386
+ The packaged Windows probe exercises the hook before it is used by generated apps.
387
+
388
+ Electrobun 2.0.5's Windows installer creates its Desktop and Start Menu
389
+ shortcuts through PowerShell and waits without a bound. The experimental
390
+ `adea-patch-electrobun-shortcuts <checkout>` command applies the shipped
391
+ `electrobun-windows-shortcut-com.patch` to a checkout of the exact 2.0.5 source
392
+ commit. It verifies the patch, input and output digests and replaces that step
393
+ with Windows Shell Link COM in an isolated extractor helper process. Each
394
+ shortcut waits at most 30 seconds; on timeout only the helper is terminated and
395
+ the installation fails. COM and file-write failures also fail it, and neither
396
+ shortcut is skipped. The Windows SDK lane applies it, builds the extractor and
397
+ runs its native shortcut tests. Apps that ship the patched extractor build it
398
+ from that source and point `HUTCH_ELECTROBUN_DEVKIT_ROOT` at a copy of the
399
+ pinned devkit that contains it.
400
+
401
+ `release-promotion` implements the daily-to-stable selection policy with a
402
+ configurable soak (96 hours by default), a hold switch and qualification of
403
+ every candidate. It delegates release listing, exact-run qualification and
404
+ idempotent stable updates to a trusted provider. The GitHub provider verifies
405
+ the immutable receipt, installer jobs and exact successful workflow attempt,
406
+ then rechecks qualification before updating the stable release. It does not
407
+ schedule promotion. Stable and daily signed discovery assets
408
+ must have distinct immutable names so promotion never replaces daily bytes.
409
+
410
+ `adea-promote-release` runs that policy in a main-branch GitHub Actions
411
+ scheduled or manually dispatched workflow. Its configuration names the
412
+ required macOS ARM64, Windows x64 and Linux x64 installer assets, separate
413
+ daily and stable discovery assets, and the soak duration. It rechecks the
414
+ exact qualified attempt immediately before the stable update. The caller
415
+ must grant a narrowly scoped `GH_TOKEN` and provide the configuration and
416
+ release-assets workflow; no schedule is installed by this command.
417
+
418
+ For example, a promotion configuration can name the app's actual assets:
419
+
420
+ ```json
421
+ {
422
+ "appName": "Example",
423
+ "soakHours": 96,
424
+ "platforms": {
425
+ "macos-arm64": ["Example-{tag}-macos-arm64.dmg"],
426
+ "windows-x64": ["Example-{tag}-windows-x64-Setup.zip"],
427
+ "linux-x64": ["Example-{tag}-linux-x64-Setup.tar.gz"]
428
+ },
429
+ "releaseAssets": ["daily.json", "stable.json", "dev.json"],
430
+ "dailyDiscoveryAssets": ["daily.json"],
431
+ "stableDiscoveryAssets": ["stable.json"],
432
+ "devDiscoveryAssets": ["dev.json"]
433
+ }
434
+ ```
435
+
436
+ Each discovery file must be a separately signed descriptor, and the release
437
+ qualification must include every named asset. Use `STABLE_PROMOTION_HELD=true`
438
+ to hold promotion. A caller workflow must supply `GH_TOKEN` and invoke
439
+ `adea-promote-release path/to/config.json` from trusted `main`.
440
+
441
+ `installer-layout` checks portable application names, hosted-runner context,
442
+ expected installer and payload paths, packaged renderer selection and CEF
443
+ security flags. It does not extract or execute an installer; callers must
444
+ validate archive link targets and entry types, test the installed application,
445
+ and collect the native renderer evidence before qualifying a release.
446
+
447
+ `adea-cut-release daily|dev path/to/config.json` selects an immutable source
448
+ and creates or repairs a prerelease from a trusted `main` GitHub Actions
449
+ workflow. The configuration also supplies `appName` and `releaseWorkflows`,
450
+ the caller workflow files whose runs carry release provenance:
451
+
452
+ ```json
453
+ "releaseWorkflows": {
454
+ "control": ".github/workflows/release.yml",
455
+ "assets": ".github/workflows/release-assets.yml"
456
+ }
457
+ ```
458
+
459
+ Both are required, must differ and must name a `.yml` or `.yaml` file directly
460
+ under `.github/workflows/`. Cuts run only from the `control` workflow; the
461
+ `assets` workflow is dispatched for each tag, and planning, retained-build
462
+ reuse, publication, qualification, promotion and finalization accept only its
463
+ runs. The caller must serialize release cuts and give the `assets` workflow a
464
+ run name of `framework-release-assets:<tag>`; uncertain qualification or build
465
+ state blocks dispatch. No release is cut outside the trusted workflow.
466
+ Release Please owns the version. `versionSource` names the manifest it bumps,
467
+ for example `{ "kind": "source-manifest", "path": "apps/desktop/package.json" }`,
468
+ and every release carries that version:
469
+
470
+ - A daily (and later stable) release is the Release Please release `v<version>`.
471
+ The framework resolves the tag's exact commit and requires the manifest at
472
+ that commit to match the tag before building, publishing or qualifying it.
473
+ - A dev release is `v<next>-dev.N`, cut from each push to `main`, where `<next>`
474
+ is the next minor version after the manifest's. Release Please writes a
475
+ version to the manifest only when it releases it, so the manifest always names
476
+ the latest release and dev builds are numbered for the version after it. `N`
477
+ starts at 1 for every next version and counts up until a release moves it:
478
+ while the manifest says `0.111.0`, main cuts `v0.112.0-dev.1` … `v0.112.0-dev.15`;
479
+ the commit that releases `v0.112.0` and those after it cut `v0.113.0-dev.1`. A
480
+ patch release such as `v0.112.1` leaves the next minor in place, so the counter
481
+ keeps rising. A rerun for the same commit reuses the newest dev release; a
482
+ commit that does not descend from it and an existing tag without a trusted
483
+ release are refused.
484
+
485
+ Every dev release sorts above the latest release and below the release it leads
486
+ to, so the dev channel moves from `v0.112.0` to `v0.113.0-dev.1` and the daily
487
+ channel from `v0.112.0-dev.15` to `v0.112.0`. Versions order the same way on
488
+ every channel. Calendar-tagged releases (`v2026.10.31-dev.1525`) from before
489
+ Release Please sort above every version and are never chosen as an upgrade
490
+ source; their installations reinstall once. An unchanged version reuses the same daily tag,
491
+ which is why the daily cadence can be any interval. Promotion orders qualified
492
+ dailies by semver and will not move stable below an already published stable
493
+ version. Older stable releases without qualification evidence serve only as a
494
+ downgrade fence. Serialize release cuts and promotions; this check cannot
495
+ atomically fence a concurrent external change to the release list.
496
+ Channel descriptors and payloads must still pass signature and digest checks.
497
+
498
+ Release Please drafts are staged privately; a separate finalize workflow
499
+ rechecks the exact successful installer attempt before publishing a prerelease.
500
+ A run started with the workflow token never triggers `workflow_run`, so the
501
+ assets workflow starts it: pass `finalize-workflow: <your finalize file>` to
502
+ `desktop-release-assets.yml` and grant that caller job `actions: write`. A daily
503
+ run then dispatches the finalize workflow with its own run ID and attempt, and
504
+ finalization waits for that run to complete before qualifying it.
505
+ If that finalization job fails, dispatch the finalize workflow from `main`
506
+ with the tag, successful release-assets run ID and attempt number. Its own file
507
+ name is not configured: finalization trusts only the qualified `assets` run. The retry
508
+ rechecks the same qualification before changing release visibility.
509
+
510
+ ### Release feed and local release mode
511
+
512
+ Apps publish to and update from an HTTPS release feed, named in the release
513
+ configuration as `"releaseFeed": { "base": "https://adea.dev/releases/", "app": "adea" }`:
514
+ an https origin and path prefix ending in `/` (no credentials, port, query or
515
+ fragment) and the app's key prefix. Keys are relative to `base`:
516
+
517
+ - `<app>/<tag>/<asset>`: immutable payloads and signed channel descriptors, whose
518
+ asset URL is exactly `<base><app>/<tag>/<asset>`;
519
+ - `<app>/<tag>/release.json`: `{ tag, channel, publishedAt, assets: [{ name, size, sha256 }] }`;
520
+ - `<app>/index.json`: the ledger `{ schema: 1, app, releases: [{ tag, kind, version, sourceSha, publishedAt }] }`,
521
+ newest first and at most 500 entries; stable entries add `promotedAt`;
522
+ - `<app>/channels/<dev|daily|stable>.json`: a copy of the newest release.json on that channel.
523
+
524
+ The updater reads the channel pointer, downloads the listed descriptor from the
525
+ same release, checks its bytes against release.json, verifies its signature and
526
+ identity, and then the payload's size and digest. Requests carry no credentials
527
+ and follow at most five redirects that stay under `<base><app>/`.
528
+
529
+ Without GitHub Actions the release CLIs run with `--local` from a clean checkout
530
+ of a commit on the fetched `origin/main`: version state comes from the feed's
531
+ ledger, read anonymously, and the commit itself stands in for the workflow run.
532
+ Nothing is uploaded; publishing steps write a tree mirroring the feed's keys and
533
+ `upload-plan.json`, ordered assets, release.json, index.json, channel pointers.
534
+
535
+ - `adea-cut-release --local dev|daily <config> <sha>` prints the tag and
536
+ `dispatched` when this machine's platform still has to be built.
537
+ - `adea-release-step stage-build <platform> <dir>` (with `RELEASE_TAG`) stages
538
+ the build; installer qualification needs a hosted runner and is skipped.
539
+ - `adea-sign-release-descriptors --local <dir> <config>` with `RELEASE_TAG`,
540
+ `SOURCE_SHA`, `RELEASE_RUN_ID` and the signing key signs this platform's descriptors.
541
+ - `adea-publish-release --local <dir> <config> <out>` merges this platform into
542
+ the feed's release and stages the upload.
543
+ - `adea-promote-release --local <config> <out>` promotes a qualified daily
544
+ after the soak and stages release.json, index.json and the stable pointer.
545
+ - `adea-finalize-release --local <config> <tag>` verifies a published release
546
+ from the feed and lists its verified and missing platforms.
547
+
548
+ ### Updating the framework pin
549
+
550
+ An application references the framework in three places: the exact npm
551
+ version in each `package.json`, the matching `bun.lock` entry, and the commit
552
+ SHA on each reusable-workflow `uses:`. Move them together from the repository
553
+ root:
554
+
555
+ ```sh
556
+ bunx adea-update-app-framework # the latest npm version
557
+ bunx adea-update-app-framework 0.24.0 # a specific version
558
+ ```
559
+
560
+ The command takes only a version npm serves from `registry.npmjs.org` whose
561
+ tarball matches its sha512 integrity, contains the version it claims and names
562
+ its source commit in `dist/framework-source.json`. Every `package.json` must
563
+ already pin an exact version. It rewrites those versions, pins every framework
564
+ workflow to the source commit (`@<sha> # v<version>`), regenerates `bun.lock`
565
+ with `bun install` (keeping comments such as release-please's version marker),
566
+ checks the lock names exactly that version and integrity, and then requires
567
+ `bun install --frozen-lockfile` to pass. If any step fails, it restores every
568
+ file it touched. Keep the framework out of dependency bots so they cannot move
569
+ one of the three on its own.
570
+
571
+ ### Task cache toolchain identity
572
+
573
+ `toolchain-identity` keys an app's cached `vp` tasks on the Node and Bun
574
+ binaries and the platform. `vite.config.ts` writes `expectedId()` into each
575
+ cached command, and an uncached first task runs
576
+ `node node_modules/@adea-ai/app-framework/dist/cli/toolchain-identity-cli.js --expect <id>`
577
+ (the `adea-toolchain-identity` bin) with the PATH the tasks get, failing the
578
+ invocation before any cache read when the toolchain differs. The id carries
579
+ versions, byte hashes, platform and libc, never paths, so the same toolchain at
580
+ another path keeps its cache entries. `runtimeExecutable` resolves the binary a
581
+ launcher really runs.
582
+
583
+ ### Reusable release workflows
584
+
585
+ Applications can call the framework's `workflow_call` workflows instead of
586
+ copying the release jobs. Name the caller files in `releaseWorkflows`, keep the
587
+ triggers and run name the CLIs verify, and pin the framework ref to a full
588
+ commit SHA:
589
+
590
+ ```yaml
591
+ # .github/workflows/release-assets.yml (releaseWorkflows.assets)
592
+ name: Desktop release assets
593
+ run-name: framework-release-assets:${{ inputs.tag }}
594
+ on:
595
+ workflow_dispatch:
596
+ inputs:
597
+ tag: { required: true, type: string }
598
+ permissions: {}
599
+ jobs:
600
+ assets:
601
+ uses: adea-ai/app-framework/.github/workflows/desktop-release-assets.yml@<sha>
602
+ permissions: { contents: write, actions: read }
603
+ with:
604
+ tag: ${{ inputs.tag }}
605
+ app-directory: apps/desktop
606
+ platforms: '["macos-arm64","windows-x64","linux-x64"]'
607
+ renderer: native
608
+ secrets:
609
+ ADEA_RELEASE_SIGNING_KEY: ${{ secrets.ADEA_RELEASE_SIGNING_KEY }}
610
+ ```
611
+
612
+ `desktop-release-assets.yml` plans the tag, builds or reuses each platform
613
+ payload, executes and qualifies the installer on its native runner, then signs
614
+ the channel descriptors and publishes the tested bytes. It takes `tag`, an
615
+ optional expected `channel` (`dev` or `daily`), `app-directory`,
616
+ `release-config`, `platforms`, `renderer` (`native` or `cef`, exported as
617
+ `ADEA_APP_RENDERER` for the app's qualification script), `install-command`,
618
+ `bun-version` and `release-signing-key-id`. Apps that compile native sidecars
619
+ set `node-version`, a `prepare-command` that installs their toolchain (for
620
+ example `rustup toolchain install`) and a longer `build-timeout-minutes`; these
621
+ only run when the build job builds a fresh payload rather than reusing a
622
+ retained one.
623
+
624
+ ```yaml
625
+ # .github/workflows/release.yml (releaseWorkflows.control)
626
+ name: Desktop release
627
+ on:
628
+ push: { branches: [main] }
629
+ schedule: [{ cron: '23 12 * * *' }] # daily cadence; '23 */4 * * *' runs every 4 hours
630
+ workflow_dispatch:
631
+ inputs:
632
+ operation: { type: choice, options: [dev, daily, stable], required: true }
633
+ permissions: {}
634
+ concurrency:
635
+ group: desktop-release-control-${{ github.repository }}
636
+ cancel-in-progress: false
637
+ jobs:
638
+ release:
639
+ uses: adea-ai/app-framework/.github/workflows/desktop-release-control.yml@<sha>
640
+ permissions: { contents: write, actions: write }
641
+ with:
642
+ app-directory: apps/desktop
643
+ ```
644
+
645
+ `desktop-release-control.yml` owns the release schedule every framework app
646
+ shares, so callers pass only `app-directory` (and `release-config`,
647
+ `install-command` or `bun-version` when they differ from the defaults). A push
648
+ to `main` cuts a dev release. Each scheduled run builds the newest Release
649
+ Please version as a daily (doing nothing new when it is already built) and then
650
+ promotes the newest qualified daily once `soakHours` (96 by default) have passed
651
+ since the last stable, so stable moves about every four days. The caller's cron
652
+ is the daily cadence: nothing assumes one run per day, so it can run every few
653
+ hours. A manual dispatch runs one `operation`: `dev`, `daily` or `stable`.
654
+ `CI_BILLING_PAUSED=true` skips the push and schedule cuts;
655
+ `STABLE_PROMOTION_HELD=true` holds promotion. Keep the caller's `push`,
656
+ `schedule` and `workflow_dispatch` triggers; only the cron expression is the
657
+ app's choice. Generated apps include a Release Please workflow and config.
658
+ `desktop-release-finalize.yml` runs `release:finalize` from the
659
+ caller's finalize workflow, which the assets run dispatches (see above). The app's `package.json` must define the same
660
+ `build:release` and `release:*` scripts the generated template provides.
661
+
662
+ The `desktop-build-hook` module supplies an Electrobun `postBuild` hook that
663
+ runs on the just-built bundle before release hashing, packaging and signing.
664
+ It applies the pinned runtime patch to Windows bundles, failing closed for
665
+ unknown Windows runtime bytes, and installs the main-frame-only CEF helper in
666
+ CEF bundles on every platform. Hook integration and runtime behavior must pass
667
+ the packaged native probes before adoption.
668
+
669
+ `adea-publish-release STAGING_DIR CONFIG.json` publishes the current trusted
670
+ `releaseWorkflows.assets` workflow attempt. In addition to the shared asset config,
671
+ it requires `appId`, an application-owned `releaseSigningKeys` map of key IDs
672
+ to base64 Ed25519 public keys, and descriptor policies for each channel and
673
+ platform. Each policy names its channel, OS, architecture and allowed payloads.
674
+ The command checks the exact workflow attempt and all staged installer receipts
675
+ and signed descriptors before writing; the caller must supply `GH_TOKEN` and
676
+ keep staging immutable. It does not build or test the installers itself.
677
+
678
+ `release-staging` copies a platform's configured installer and archive into a
679
+ staging directory without replacing existing files. It rejects source links,
680
+ checks that the source remains stable while copying, and returns SHA-256 asset
681
+ identities. Installer execution and qualification remain separate requirements.
682
+
683
+ `update-download` streams a verified release from GitHub into a new private
684
+ staging directory, limits redirects and size, and checks the signed digest.
685
+ The caller owns cleanup and must reverify bytes immediately before installation;
686
+ downloading does not install an update or enforce a version policy.
687
+
688
+ `installer-identity` inspects a platform installer on a matching disposable
689
+ GitHub-hosted runner and verifies that its embedded archive matches the staged
690
+ archive. It does not execute the installer or issue an installation receipt.
691
+
692
+ Run `bun scripts/test-packed.ts --archive PATH` to validate a particular packed
693
+ framework archive in an isolated consumer. The check copies and hashes the
694
+ archive before installation and verifies that both copies remain unchanged;
695
+ without `--archive`, it packs the current checkout first.
696
+
697
+ `update-discovery` resolves the app's dev, daily or stable GitHub release
698
+ descriptor and authenticates it against the app's configured signing policy.
699
+ It skips releases without a descriptor, checks the signed payload against the
700
+ release's asset metadata, bounds responses and restricts redirects. The
701
+ caller still applies its version policy and invokes the verified downloader.
702
+
703
+ The internal `installer-worker-guard` module provides hosted-CI worker interception and a nonce-bound
704
+ permit for an installed app. A qualification runner must install and preflight
705
+ the guard with the packaged runtime, verify the installed bytes before granting
706
+ the permit, and independently collect rendered-app evidence. This helper alone
707
+ does not execute an installer or qualify a release.
708
+
709
+ The internal `installer-fetch-guard` module blocks non-loopback Bun fetches during hosted-CI
710
+ qualification and records unexpected requests. It does not intercept sockets,
711
+ subprocesses, or webview networking, so it is not an OS network sandbox.
712
+
713
+ `installer-renderer-evidence` instruments the expected loopback listener in a
714
+ hosted test and records two real animation-frame observations separated by at
715
+ least three seconds. The observation is not an installer receipt: the runner
716
+ must separately verify installed bytes, guard startup, observe app-specific
717
+ offline behavior and detect unexpected activity before qualification.
718
+
719
+ `adea-plan-release-assets` validates a dispatched asset workflow attempt and the
720
+ release tag, then resolves the immutable main-branch source commit and version.
721
+ The generated workflow must still build and qualify artifacts before publication.
722
+
723
+ `macos-dmg` sizes a disk image using logical staged file bytes and entry
724
+ overhead, builds and verifies it, and refuses to replace an existing artifact.
725
+ This addresses CEF bundles whose logical size exceeds automatic image sizing;
726
+ application signing and notarization remain separate configuration.
727
+
728
+ `retained-release-build` identifies the earliest unexpired platform build
729
+ from a trusted release-assets attempt with a successful build job. If a
730
+ platform payload is already published and its original build is unavailable,
731
+ it refuses to rebuild. The caller must verify downloaded artifact contents and
732
+ re-run installer qualification for the current attempt.
733
+
734
+ `release-steps` (the `adea-release-step` CLI, `dist/cli/release-step-cli.js`) runs
735
+ the per-platform release-assets steps in an app directory, reading
736
+ `release-config.json` and `RELEASE_TAG`: `select-retained <platform>` writes the
737
+ retained-build choice to `GITHUB_OUTPUT`; `stage-build [--artifacts <dir>]
738
+ <platform> <dir>` stages the stable Electrobun installer and archive under their
739
+ asset names; `inspect`, `qualify` and `qualify-upgrade <platform> <dir>` check
740
+ the staged payload, run installer qualification and run the upgrade test with
741
+ the workflow's `ADEA_APP_RENDERER`. Apps point their `release:*` scripts at it;
742
+ one with extra payload checks calls `inspectStagedStep` and adds them.
743
+
744
+ Command artifacts are portable command-line payloads an app publishes beside its
745
+ desktop payloads, through the same staging, qualification, signing and immutable
746
+ publication. Each `commandArtifacts` entry names its own update identity, the
747
+ directory the release build leaves, one `.tar.gz` asset per release platform and
748
+ the commands that qualify it. An app can declare up to four kinds, each with up
749
+ to 16 extra qualification environment variables:
750
+
751
+ ```json
752
+ "commandArtifacts": {
753
+ "cli": {
754
+ "appId": "dev.example.cli",
755
+ "executable": "example",
756
+ "build": "dist-cli/release",
757
+ "platforms": {
758
+ "macos-arm64": "example-cli-{tag}-macos-arm64.tar.gz",
759
+ "windows-x64": "example-cli-{tag}-windows-x64.tar.gz",
760
+ "linux-x64": "example-cli-{tag}-linux-x64.tar.gz"
761
+ },
762
+ "qualification": { "env": {}, "probes": [["status"]], "service": ["serve"] }
763
+ }
764
+ }
765
+ ```
766
+
767
+ `stage-build` packs the build directory into the asset, under one root directory
768
+ named after it (`example-cli-v1.2.3-linux-x64/bin/example`, or `bin/example.cmd`
769
+ on Windows), with portable headers and a fixed timestamp. `inspect` rejects any
770
+ entry that is not a regular file or directory under that root, and a missing
771
+ launcher. `qualify` extracts the staged archive into a new location with its own
772
+ home, temporary and data directories, then requires `--version` to print the
773
+ release version, every probe to exit 0, and the service to stay up for five
774
+ seconds and exit 0 on SIGTERM; on Windows, where no signal reaches a console
775
+ process, its process tree is terminated instead. It stages
776
+ `command-test-<kind>-<platform>.json`, which records only booleans and the exact
777
+ asset digest. Signing, publication, finalization and promotion require one such
778
+ receipt per kind and platform. Each channel's discovery assets must then name one
779
+ descriptor per payload kind and platform, signed with the artifact's `appId`, so a
780
+ desktop updater never accepts a command artifact's descriptor or the reverse. An
781
+ app without `commandArtifacts` publishes exactly as before.
782
+
783
+ `update-manager` coordinates signed discovery, version policy, explicit approval
784
+ of the exact version, and verified download. Its `staged` state reports only
785
+ that an application-supplied platform adapter accepted the download;
786
+ `desktop-updater` applies it.
787
+
788
+ `update-extraction` rechecks a signed archive, bounds Zstandard expansion, and
789
+ extracts into a new private staging directory using strict tar handling. It
790
+ rejects unsafe links, paths, duplicate entries, unexpected renderer layouts and
791
+ version mismatches. For Linux CEF it reconstructs only the five fixed relative
792
+ library links after ordinary extraction. It does not replace an installed
793
+ application; `desktop-updater` stages and applies it.
794
+
795
+ `adea-sign-release-descriptors` checks release provenance, all three exact-attempt
796
+ installer receipts, every command artifact receipt and staged payload digests before signing the configured
797
+ channel descriptors with the app's Ed25519 key. It refuses an untrusted key or
798
+ existing output. Signing and staging do not publish or qualify a release.
799
+
800
+ `adea-release-step qualify-upgrade` (an app's `release:qualify-upgrade`) runs after signing
801
+ on each platform and before publication. It discovers the newest published release
802
+ the way the app's updater does (the same channel, or dev before a channel's first
803
+ release), installs it with its own installer, then stages and swaps in this
804
+ release's signed payload and observes the new version start under the same guard
805
+ and offline policy as the installer receipt. With no earlier published release it
806
+ reports that and passes.
807
+
808
+ An optional release `offlinePolicy` binds qualification to an app-owned visible
809
+ marker. `standalone` is for apps with no startup bootstrap; `local-bootstrap`
810
+ requires the specified local bootstrap route to be denied while the marker is
811
+ observed. The version-two evidence contract also requires a restricted browser
812
+ network and the guarded native renderer. A policy does not itself run these
813
+ checks or issue a receipt; the installer runner must supply measured evidence.
814
+
815
+ The internal `installer-ci-bootstrap` module prepares an external Bun preload inside a disposable
816
+ hosted runner. It installs worker, fetch and renderer probes before the app
817
+ worker starts and records observations and unexpected fetches. The runner must
818
+ verify the installed files before issuing its nonce-bound permit; the preload
819
+ alone cannot prove installer execution, offline acceptance or OS network isolation.
820
+
821
+ `installer-extraction` inspects an installer on the matching disposable hosted
822
+ runner and prepares a separate profile with only the required installer files.
823
+ It does not run the installer or create a qualification receipt.
824
+
825
+ `installed-payload` compares the installed launcher, Bun runtime, worker,
826
+ client and build metadata with the staged archive inside an isolated hosted
827
+ profile. This covers those critical files, not every byte of an installation,
828
+ and does not by itself prove launch, offline behavior or release qualification.
829
+ It can also extract only the candidate Bun runtime for guard preflight before
830
+ installer execution.
831
+
832
+ The framework is published to npm as `@adea-ai/app-framework`. Build and pack
833
+ the exact package (`bun run build`, `bun pm pack --ignore-scripts`, then
834
+ `bun scripts/test-packed.ts --archive <tgz>`), and publish it with
835
+ `bun scripts/publish-framework-package.ts <tgz> [--dry-run]` from a clean
836
+ checkout of a commit on `origin/main`. The tarball must carry this checkout's
837
+ version and name this commit in `dist/framework-source.json`, which the build
838
+ writes. A version npm already has is left alone when its integrity matches and
839
+ refused otherwise, so a rerun is safe. `NODE_AUTH_TOKEN` authenticates through
840
+ a temporary npmrc that refers to the variable; set `NPM_CONFIG_PROVENANCE=false`
841
+ outside CI. `framework-package.yml` runs the same steps from a version tag with
842
+ npm trusted publishing and provenance.
843
+
844
+ `installer-observation` executes an installer only in a disposable, matching
845
+ hosted runner after preflighting its bundled runtime. It verifies selected
846
+ installed files before permitting startup and records the native renderer
847
+ observation. It does not issue a release receipt or prove app-specific offline
848
+ acceptance. It verifies and terminates the guarded Bun process; other
849
+ OS-launched descendants are retired with the disposable runner.
850
+
851
+ `installer-qualification-command` binds a measured installer observation to the current
852
+ trusted release-assets attempt and stages an immutable platform receipt. It
853
+ requires an explicit offline policy and an accessible local foreign-origin
854
+ sentinel; the renderer must observe the configured marker while that request is
855
+ blocked. For local-bootstrap policies, the named route must also be denied.
856
+ This is not a substitute for product-specific or OS network-isolation testing.
857
+
858
+ `native-utilities` registers authorized app information, credential-free HTTP(S)
859
+ external links, a single native folder picker and, when the host supplies
860
+ `pickFiles`, an open-file dialog (`shell.pick-files`, with optional extensions
861
+ and multiple selection) through injected host adapters. Electrobun 2.0.5 has no
862
+ save dialog, so none is offered. A picked path does not grant file access; application services must authorize it
863
+ separately. The host must supply its principal policy and platform operations.
864
+
865
+ `app-bundle` locates the packaged bundle from the host entry's
866
+ `import.meta.dir`: `readPackagedVersion(import.meta.dir)` returns the version
867
+ (and channel, identifier and hash when present) that Electrobun wrote to
868
+ `Resources/version.json`, and `packagedSidecarPath(import.meta.dir, name)`
869
+ resolves a bundled sidecar (see the sidecar host below).
870
+
871
+ `desktop-stream` offers optional authenticated, full-duplex channels for native
872
+ services. Register providers through `startDesktopHost`'s `configureStreams`;
873
+ clients call `openStream` after the window handshake. Attach proofs use a
874
+ separate HMAC context and replay protection. The host screens origins, limits
875
+ connections, frames and queued traffic, serializes incoming messages, and closes
876
+ sessions on channel revocation, provider removal, expiry or host shutdown.
877
+ Providers must validate their input and authorize each app-specific resource;
878
+ they can retain `context.close` to revoke a resource scope and use its abort
879
+ signal to stop work. Providers own the semantics of individual messages and
880
+ must enforce resource grants and any additional protocol limits. This transport
881
+ alone does not implement Adea's Dev Runtime operations or grant model.
882
+
883
+ `update-channel-store` persists the app's stable, pre-release or dev selection
884
+ in its private state directory. A missing selection defaults to stable; invalid
885
+ or unreadable state fails rather than silently changing channels. Use
886
+ `releaseChannelForUpdate` to map the UI's pre-release choice to the daily
887
+ release feed. The host must authorize changes and read the selected channel
888
+ again for each update check; persistence alone does not configure an updater.
889
+
890
+ `native-secret-store` provides an app-namespaced credential port with bounded
891
+ values, serialized operations, verified writes and deletion, and secret-free
892
+ errors. Its default adapter uses Bun's experimental OS credential API and asks
893
+ for device-local persistence on Windows; apps must authorize all use and handle
894
+ an unavailable OS credential service without falling back to plaintext. The
895
+ port also accepts an app-owned backend. It does not migrate existing credentials:
896
+ Adea's current macOS Keychain item class and namespace require its existing
897
+ adapter until a separately verified migration is implemented. The hosted probe
898
+ exercises disposable entries with both standalone and packaged Bun; a passing
899
+ run, locked-store behavior and application-specific migration require separate
900
+ qualification.
901
+
902
+ `exportVerifiedRelease` preserves the signed public release envelope for a
903
+ helper process. The receiving process must authenticate it again against its
904
+ own current trust configuration; a serialized descriptor alone never carries
905
+ the in-process verification capability.
906
+
907
+ `channel-update-manager` reads the selected channel for each signed discovery,
908
+ invalidates older offers when it changes, and checks the channel again before
909
+ and after staging. It serializes its own operations and binds approval to the
910
+ specific offered version. The stage callback must only prepare the update;
911
+ `staged` does not mean the application has been replaced or relaunched. A
912
+ production installer must independently validate the channel and approval at
913
+ its own commit boundary.
914
+
915
+ `desktop-updater` is the whole host side for an app: `createDesktopUpdater`
916
+ wires the channel store, signed discovery, download, staged swap and post-exit
917
+ helper for the app's release identity and renderer, resuming after an earlier
918
+ helper on start, and `registerUpdateServices` serves it as the
919
+ `desktop_update_*` services the web update adapter calls. Apps pass their
920
+ `release-config.json`, repository, renderer and helper path; they keep no
921
+ updater code of their own.
922
+
923
+ `desktop-updater` applies a staged update to the installed app.
924
+ `stageUpdateSwap` extracts the verified archive into a private staging
925
+ directory beside the install. `armUpdateHelper`, used as the `arm` step of
926
+ `scheduleUpdateShutdown`, copies the app's Bun runtime and the bundled helper
927
+ (`@adea-ai/app-framework/update-helper.js`, which the app ships in its
928
+ resources) into staging, starts it, and resolves once the helper has verified
929
+ the app's processes. After they exit, the helper moves the staged tree into
930
+ place with no-replace renames, deletes the old tree and relaunches the app's
931
+ launcher. On the next start, `resumeUpdate` reports the installed version and
932
+ removes the staging directory.
933
+
934
+ ### Preserving an existing desktop origin
935
+
936
+ An app migrating from an existing fixed loopback origin can pass `initialPort`
937
+ to `startDesktopHost`, together with its app-owned `portFile`. The first launch
938
+ binds and persists that port; generated apps expose it as `initialPort` in
939
+ `src/app-config.ts`. Later launches require the saved port to match and
940
+ fail if it is occupied. `startDesktopHostWithRetry` retries only a failed bind
941
+ for a bounded period, which permits a previous process to release the port.
942
+ This preserves the URL origin but does not itself prove
943
+ that a renderer's existing profile or stored data has been migrated.
944
+
945
+ A desktop host exposes `revokeChannels()` for an app to invalidate current
946
+ window channels and close their streams when authorization changes. The
947
+ window's native grant remains valid, so its client can explicitly reconnect.
948
+ The app must update and enforce its own authorization scope before revocation;
949
+ this method does not replace or rebind the principal supplied at host creation
950
+ and cannot cancel a service handler that has already begun.
951
+ The desktop host accepts optional `routes` for app-owned same-origin HTTP
952
+ endpoints, such as a cloud proxy. Each route names a non-overlapping path
953
+ prefix and a handler. The host reserves its own framework endpoints and screens
954
+ Host, Origin and browser fetch metadata before dispatch. These headers are not
955
+ credentials: a local process can forge them. Route handlers must enforce their
956
+ own authorization, input and request-size limits, and safe upstream behavior;
957
+ use the authenticated service gateway for privileged native operations.
958
+
959
+ The internal update tree identity scans a bounded tree and fingerprints file
960
+ contents, names and permissions while rejecting changed files and, by default,
961
+ links. A caller may explicitly permit the five fixed Linux CEF library links;
962
+ other links remain rejected. Its path-based traversal does not defend against
963
+ concurrent directory replacement, so callers must provide private, stable
964
+ directories and independent trust before using a fingerprint in an update decision.
965
+
966
+ Generated apps can declare custom URL schemes in `src/app-config.ts`. On macOS,
967
+ Electrobun places the schemes in the app bundle; platform-specific callback
968
+ delivery still needs qualification. `createOpenUrlChannel` can subscribe to the
969
+ native `open-url` event before asynchronous startup and buffer a bounded number
970
+ of events until the app attaches a receiver. URLs are untrusted input: the app
971
+ must validate the callback target, parameters, state and replay protection.
972
+ Async receivers start in delivery order but can finish concurrently.
973
+
974
+ ### Sidecar host
975
+
976
+ `sidecar` runs a bundled executable, in any language, beside the Bun host and
977
+ calls it over stdio: one `{"id", "command", "args"}` JSON line per request and
978
+ one `{"id", "ok", "value" | "error"}` line per reply, matched by id so calls
979
+ can overlap. The sidecar must exit when its stdin closes.
980
+ `createSidecar({ executable, args, env, requestTimeoutMs, maxRequestBytes,
981
+ maxReplyBytes, restart: { maxRestarts, windowMs } })` starts the process on
982
+ the first `call(command, args, { signal, timeoutMs })`, respawns it on the next
983
+ call after it exits until the restart budget for the window is spent, and kills
984
+ it on `stop()` or host exit. Requests default to 1 MiB, replies to 8 MiB and
985
+ calls to 30 s. `call` never throws: failures resolve as `{ ok: false, reason,
986
+ error }` where `reason` is `command_failed`, `timeout`, `aborted`,
987
+ `request_too_large`, `reply_too_large`, `unavailable`, `exited`,
988
+ `restart_limit` or `stopped`, and `error` is readable. Recent stderr is kept,
989
+ bounded, in `stderr()` and passed line by line to `log`; keep it on the host.
990
+ Pass a `SidecarCommands` map as the type parameter to type each command's
991
+ arguments and value.
992
+
993
+ `registerSidecarServices({ services, sidecar, commands, authorize, prefix })`
994
+ exposes each command as a service named `prefix + command`, so the web side
995
+ calls it through `desktop-client`; a sidecar failure arrives as
996
+ `service_error` with the reason as its code.
997
+
998
+ Ship each sidecar at `Resources/app/sidecars/<name>` (`<name>.exe` on Windows):
999
+ stage the binary built for the target OS, for example in `build/sidecars`, and
1000
+ copy it with Electrobun's `build.copy` (`{ 'build/sidecars': 'sidecars' }`).
1001
+ Resolve it at runtime with `packagedSidecarPath(import.meta.dir, name)` from
1002
+ `app-bundle`. List the names in the release configuration as
1003
+ `"sidecars": ["name"]`: installer qualification then requires each sidecar in
1004
+ the payload and compares the installed copy with the archive, and update
1005
+ staging (`stageUpdateSwap({ sidecars })`) refuses an update whose tree lacks
1006
+ one or ships it without the executable bit. The detached release signature
1007
+ covers the whole archive, so sidecars are signed with it. For macOS code
1008
+ signing, Electrobun documents that its build signs nested Mach-O files when
1009
+ `codesign` is enabled; confirm with `codesign --verify --deep --strict` on the
1010
+ built app.