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

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