@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.
- package/LICENSE +201 -0
- package/NOTICE +30 -0
- package/README.md +1009 -2
- package/dist/app/application.d.ts +47 -0
- package/dist/app/application.js +115 -0
- package/dist/app/create-application.d.ts +13 -0
- package/dist/app/create-application.js +178 -0
- package/dist/app/service-registry.d.ts +44 -0
- package/dist/app/service-registry.js +116 -0
- package/dist/appearance/appearance-host.d.ts +62 -0
- package/dist/appearance/appearance-host.js +115 -0
- package/dist/appearance/appearance-preferences.d.ts +106 -0
- package/dist/appearance/appearance-preferences.js +175 -0
- package/dist/appearance/composition.d.ts +11 -0
- package/dist/appearance/composition.js +16 -0
- package/dist/appearance/custom-theme-import.d.ts +14 -0
- package/dist/appearance/custom-theme-import.js +315 -0
- package/dist/appearance/custom-theme-library.d.ts +146 -0
- package/dist/appearance/custom-theme-library.js +378 -0
- package/dist/appearance/editor.d.ts +20 -0
- package/dist/appearance/editor.js +47 -0
- package/dist/appearance/theme-file-importer.d.ts +23 -0
- package/dist/appearance/theme-file-importer.js +66 -0
- package/dist/appearance/theme-record-adapter.d.ts +26 -0
- package/dist/appearance/theme-record-adapter.js +64 -0
- package/dist/appearance/theme-registry.d.ts +10 -0
- package/dist/appearance/theme-registry.js +16 -0
- package/dist/appearance/window-surface.d.ts +5 -0
- package/dist/appearance/window-surface.js +9 -0
- package/dist/ci/toolchain-identity.d.ts +39 -0
- package/dist/ci/toolchain-identity.js +196 -0
- package/dist/cli/cef-helper-cli.d.ts +2 -0
- package/dist/cli/cef-helper-cli.js +18 -0
- package/dist/cli/cli-runner.d.ts +8 -0
- package/dist/cli/cli-runner.js +23 -0
- package/dist/cli/create-application-cli.d.ts +2 -0
- package/dist/cli/create-application-cli.js +40 -0
- package/dist/cli/electrobun-shortcut-patch-cli.d.ts +2 -0
- package/dist/cli/electrobun-shortcut-patch-cli.js +17 -0
- package/dist/cli/framework-update-cli.d.ts +2 -0
- package/dist/cli/framework-update-cli.js +40 -0
- package/dist/cli/release-assets-plan-cli.d.ts +2 -0
- package/dist/cli/release-assets-plan-cli.js +14 -0
- package/dist/cli/release-cut-cli.d.ts +2 -0
- package/dist/cli/release-cut-cli.js +27 -0
- package/dist/cli/release-descriptor-staging-cli.d.ts +2 -0
- package/dist/cli/release-descriptor-staging-cli.js +45 -0
- package/dist/cli/release-finalize-cli.d.ts +1 -0
- package/dist/cli/release-finalize-cli.js +30 -0
- package/dist/cli/release-promote-cli.d.ts +2 -0
- package/dist/cli/release-promote-cli.js +32 -0
- package/dist/cli/release-publish-cli.d.ts +2 -0
- package/dist/cli/release-publish-cli.js +48 -0
- package/dist/cli/release-sign-cli.d.ts +2 -0
- package/dist/cli/release-sign-cli.js +13 -0
- package/dist/cli/release-step-cli.d.ts +2 -0
- package/dist/cli/release-step-cli.js +44 -0
- package/dist/cli/toolchain-identity-cli.d.ts +2 -0
- package/dist/cli/toolchain-identity-cli.js +10 -0
- package/dist/cli/update-helper-cli.d.ts +1 -0
- package/dist/cli/update-helper-cli.js +10 -0
- package/dist/cli/windows-runtime-patch-cli.d.ts +2 -0
- package/dist/cli/windows-runtime-patch-cli.js +17 -0
- package/dist/desktop/application-command-client.d.ts +15 -0
- package/dist/desktop/application-command-client.js +21 -0
- package/dist/desktop/channel-handshake.d.ts +32 -0
- package/dist/desktop/channel-handshake.js +111 -0
- package/dist/desktop/channel-proof.d.ts +43 -0
- package/dist/desktop/channel-proof.js +85 -0
- package/dist/desktop/client-assets.d.ts +7 -0
- package/dist/desktop/client-assets.js +59 -0
- package/dist/desktop/desktop-client.d.ts +23 -0
- package/dist/desktop/desktop-client.js +231 -0
- package/dist/desktop/desktop-gateway.d.ts +18 -0
- package/dist/desktop/desktop-gateway.js +146 -0
- package/dist/desktop/desktop-host.d.ts +48 -0
- package/dist/desktop/desktop-host.js +208 -0
- package/dist/desktop/desktop-stream.d.ts +36 -0
- package/dist/desktop/desktop-stream.js +231 -0
- package/dist/desktop/loopback-policy.d.ts +19 -0
- package/dist/desktop/loopback-policy.js +23 -0
- package/dist/desktop/open-url-channel.d.ts +15 -0
- package/dist/desktop/open-url-channel.js +55 -0
- package/dist/desktop/string-policy.d.ts +2 -0
- package/dist/desktop/string-policy.js +11 -0
- package/dist/framework-source.json +1 -0
- package/dist/installer/archive-entry.d.ts +6 -0
- package/dist/installer/archive-entry.js +14 -0
- package/dist/installer/command-artifact.d.ts +47 -0
- package/dist/installer/command-artifact.js +261 -0
- package/dist/installer/command-qualification-command.d.ts +12 -0
- package/dist/installer/command-qualification-command.js +71 -0
- package/dist/installer/hosted-runner.d.ts +4 -0
- package/dist/installer/hosted-runner.js +10 -0
- package/dist/installer/installed-payload.d.ts +29 -0
- package/dist/installer/installed-payload.js +312 -0
- package/dist/installer/installer-ci-bootstrap.d.ts +26 -0
- package/dist/installer/installer-ci-bootstrap.js +160 -0
- package/dist/installer/installer-ci-preflight.d.ts +1 -0
- package/dist/installer/installer-ci-preflight.js +49 -0
- package/dist/installer/installer-ci-worker.d.ts +1 -0
- package/dist/installer/installer-ci-worker.js +105 -0
- package/dist/installer/installer-extraction.d.ts +14 -0
- package/dist/installer/installer-extraction.js +289 -0
- package/dist/installer/installer-fetch-guard.d.ts +15 -0
- package/dist/installer/installer-fetch-guard.js +50 -0
- package/dist/installer/installer-identity.d.ts +23 -0
- package/dist/installer/installer-identity.js +286 -0
- package/dist/installer/installer-layout.d.ts +21 -0
- package/dist/installer/installer-layout.js +89 -0
- package/dist/installer/installer-observation.d.ts +64 -0
- package/dist/installer/installer-observation.js +473 -0
- package/dist/installer/installer-process-cleanup.d.ts +18 -0
- package/dist/installer/installer-process-cleanup.js +158 -0
- package/dist/installer/installer-qualification-command.d.ts +11 -0
- package/dist/installer/installer-qualification-command.js +71 -0
- package/dist/installer/installer-renderer-evidence.d.ts +43 -0
- package/dist/installer/installer-renderer-evidence.js +136 -0
- package/dist/installer/installer-upgrade-command.d.ts +37 -0
- package/dist/installer/installer-upgrade-command.js +172 -0
- package/dist/installer/installer-worker-guard.d.ts +21 -0
- package/dist/installer/installer-worker-guard.js +72 -0
- package/dist/installer/native-executable.d.ts +5 -0
- package/dist/installer/native-executable.js +21 -0
- package/dist/installer/upgrade-asset-download.d.ts +13 -0
- package/dist/installer/upgrade-asset-download.js +41 -0
- package/dist/installer/write-all.d.ts +6 -0
- package/dist/installer/write-all.js +11 -0
- package/dist/native/app-bundle.d.ts +28 -0
- package/dist/native/app-bundle.js +60 -0
- package/dist/native/cef-helper.d.ts +28 -0
- package/dist/native/cef-helper.js +402 -0
- package/dist/native/desktop-build-hook.d.ts +7 -0
- package/dist/native/desktop-build-hook.js +20 -0
- package/dist/native/electrobun-source-patch.d.ts +25 -0
- package/dist/native/electrobun-source-patch.js +93 -0
- package/dist/native/linux-cef-links.d.ts +2 -0
- package/dist/native/linux-cef-links.js +15 -0
- package/dist/native/native-secret-store.d.ts +27 -0
- package/dist/native/native-secret-store.js +70 -0
- package/dist/native/native-utilities.d.ts +24 -0
- package/dist/native/native-utilities.js +85 -0
- package/dist/native/partitioned-window.d.ts +34 -0
- package/dist/native/partitioned-window.js +44 -0
- package/dist/native/renderer-profile.d.ts +53 -0
- package/dist/native/renderer-profile.js +30 -0
- package/dist/native/secure-window.d.ts +38 -0
- package/dist/native/secure-window.js +77 -0
- package/dist/native/sidecar-services.d.ts +23 -0
- package/dist/native/sidecar-services.js +46 -0
- package/dist/native/sidecar.d.ts +81 -0
- package/dist/native/sidecar.js +250 -0
- package/dist/native/window-bootstrap.d.ts +24 -0
- package/dist/native/window-bootstrap.js +63 -0
- package/dist/native/window-options.d.ts +32 -0
- package/dist/native/window-options.js +23 -0
- package/dist/native/windows-build-hook-internal.d.ts +2 -0
- package/dist/native/windows-build-hook-internal.js +32 -0
- package/dist/native/windows-build-hook.d.ts +2 -0
- package/dist/native/windows-build-hook.js +12 -0
- package/dist/native/windows-runtime-patch-internal.d.ts +3 -0
- package/dist/native/windows-runtime-patch-internal.js +20 -0
- package/dist/native/windows-runtime-patch.d.ts +4 -0
- package/dist/native/windows-runtime-patch.js +12 -0
- package/dist/release/feed-release-cut.d.ts +23 -0
- package/dist/release/feed-release-cut.js +93 -0
- package/dist/release/feed-state.d.ts +25 -0
- package/dist/release/feed-state.js +81 -0
- package/dist/release/framework-package-publish.d.ts +21 -0
- package/dist/release/framework-package-publish.js +127 -0
- package/dist/release/framework-update.d.ts +30 -0
- package/dist/release/framework-update.js +139 -0
- package/dist/release/github-cli.d.ts +6 -0
- package/dist/release/github-cli.js +16 -0
- package/dist/release/github-release-assets.d.ts +3 -0
- package/dist/release/github-release-assets.js +24 -0
- package/dist/release/github-release-cut.d.ts +14 -0
- package/dist/release/github-release-cut.js +174 -0
- package/dist/release/github-release-lookup.d.ts +7 -0
- package/dist/release/github-release-lookup.js +29 -0
- package/dist/release/github-release-promotion.d.ts +10 -0
- package/dist/release/github-release-promotion.js +78 -0
- package/dist/release/github-release-provenance.d.ts +9 -0
- package/dist/release/github-release-provenance.js +27 -0
- package/dist/release/github-release-publisher.d.ts +9 -0
- package/dist/release/github-release-publisher.js +63 -0
- package/dist/release/github-release-qualification.d.ts +12 -0
- package/dist/release/github-release-qualification.js +80 -0
- package/dist/release/local-provenance.d.ts +24 -0
- package/dist/release/local-provenance.js +72 -0
- package/dist/release/local-release.d.ts +133 -0
- package/dist/release/local-release.js +387 -0
- package/dist/release/macos-dmg.d.ts +22 -0
- package/dist/release/macos-dmg.js +91 -0
- package/dist/release/release-artifact.d.ts +6 -0
- package/dist/release/release-artifact.js +38 -0
- package/dist/release/release-assets-plan.d.ts +14 -0
- package/dist/release/release-assets-plan.js +65 -0
- package/dist/release/release-config.d.ts +76 -0
- package/dist/release/release-config.js +180 -0
- package/dist/release/release-cut-command.d.ts +13 -0
- package/dist/release/release-cut-command.js +39 -0
- package/dist/release/release-cut.d.ts +54 -0
- package/dist/release/release-cut.js +76 -0
- package/dist/release/release-descriptor-staging.d.ts +34 -0
- package/dist/release/release-descriptor-staging.js +147 -0
- package/dist/release/release-finalize.d.ts +16 -0
- package/dist/release/release-finalize.js +104 -0
- package/dist/release/release-promotion-command.d.ts +12 -0
- package/dist/release/release-promotion-command.js +28 -0
- package/dist/release/release-promotion.d.ts +29 -0
- package/dist/release/release-promotion.js +57 -0
- package/dist/release/release-publication.d.ts +33 -0
- package/dist/release/release-publication.js +138 -0
- package/dist/release/release-publish-command.d.ts +7 -0
- package/dist/release/release-publish-command.js +91 -0
- package/dist/release/release-qualification.d.ts +106 -0
- package/dist/release/release-qualification.js +135 -0
- package/dist/release/release-staging.d.ts +9 -0
- package/dist/release/release-staging.js +61 -0
- package/dist/release/release-steps.d.ts +38 -0
- package/dist/release/release-steps.js +147 -0
- package/dist/release/retained-release-build.d.ts +19 -0
- package/dist/release/retained-release-build.js +122 -0
- package/dist/shell/app-shell.d.ts +61 -0
- package/dist/shell/app-shell.js +306 -0
- package/dist/shell/app-utilities.d.ts +122 -0
- package/dist/shell/app-utilities.js +334 -0
- package/dist/shell/application-menu-commands.d.ts +5 -0
- package/dist/shell/application-menu-commands.js +11 -0
- package/dist/shell/application-menu.d.ts +61 -0
- package/dist/shell/application-menu.js +208 -0
- package/dist/shell/help-shortcuts.d.ts +12 -0
- package/dist/shell/help-shortcuts.js +22 -0
- package/dist/shell/navigation-drawer.d.ts +12 -0
- package/dist/shell/navigation-drawer.js +42 -0
- package/dist/shell/settings-sections.d.ts +31 -0
- package/dist/shell/settings-sections.js +50 -0
- package/dist/shell/shortcut-platform.d.ts +17 -0
- package/dist/shell/shortcut-platform.js +25 -0
- package/dist/update-helper.bundle.js +260 -0
- package/dist/updates/channel-update-manager.d.ts +46 -0
- package/dist/updates/channel-update-manager.js +114 -0
- package/dist/updates/desktop-updater.d.ts +104 -0
- package/dist/updates/desktop-updater.js +345 -0
- package/dist/updates/release-feed.d.ts +61 -0
- package/dist/updates/release-feed.js +111 -0
- package/dist/updates/release-location.d.ts +9 -0
- package/dist/updates/release-location.js +80 -0
- package/dist/updates/release-version.d.ts +12 -0
- package/dist/updates/release-version.js +43 -0
- package/dist/updates/signed-release.d.ts +63 -0
- package/dist/updates/signed-release.js +162 -0
- package/dist/updates/stable-file.d.ts +10 -0
- package/dist/updates/stable-file.js +22 -0
- package/dist/updates/update-adapter.d.ts +57 -0
- package/dist/updates/update-adapter.js +72 -0
- package/dist/updates/update-arm.d.ts +24 -0
- package/dist/updates/update-arm.js +95 -0
- package/dist/updates/update-channel-store.d.ts +8 -0
- package/dist/updates/update-channel-store.js +72 -0
- package/dist/updates/update-discovery.d.ts +13 -0
- package/dist/updates/update-discovery.js +56 -0
- package/dist/updates/update-download.d.ts +14 -0
- package/dist/updates/update-download.js +67 -0
- package/dist/updates/update-exclusive-rename.d.ts +2 -0
- package/dist/updates/update-exclusive-rename.js +52 -0
- package/dist/updates/update-extraction.d.ts +18 -0
- package/dist/updates/update-extraction.js +183 -0
- package/dist/updates/update-handoff-plan.d.ts +22 -0
- package/dist/updates/update-handoff-plan.js +28 -0
- package/dist/updates/update-helper.d.ts +24 -0
- package/dist/updates/update-helper.js +56 -0
- package/dist/updates/update-launch.d.ts +5 -0
- package/dist/updates/update-launch.js +27 -0
- package/dist/updates/update-manager.d.ts +40 -0
- package/dist/updates/update-manager.js +83 -0
- package/dist/updates/update-process-fence.d.ts +10 -0
- package/dist/updates/update-process-fence.js +114 -0
- package/dist/updates/update-resume.d.ts +13 -0
- package/dist/updates/update-resume.js +34 -0
- package/dist/updates/update-shutdown.d.ts +15 -0
- package/dist/updates/update-shutdown.js +29 -0
- package/dist/updates/update-state.d.ts +30 -0
- package/dist/updates/update-state.js +18 -0
- package/dist/updates/update-swap-stage.d.ts +27 -0
- package/dist/updates/update-swap-stage.js +58 -0
- package/dist/updates/update-swap.d.ts +10 -0
- package/dist/updates/update-swap.js +30 -0
- package/dist/views/app-about.d.ts +22 -0
- package/dist/views/app-about.js +43 -0
- package/dist/views/app-appearance.d.ts +11 -0
- package/dist/views/app-appearance.js +42 -0
- package/dist/views/app-help.d.ts +17 -0
- package/dist/views/app-help.js +42 -0
- package/dist/views/app-settings.d.ts +26 -0
- package/dist/views/app-settings.js +97 -0
- package/dist/views/appearance-surface.d.ts +9 -0
- package/dist/views/appearance-surface.js +334 -0
- package/dist/views/update-surface.d.ts +34 -0
- package/dist/views/update-surface.js +64 -0
- package/package.json +374 -4
- package/src/app/application.tsx +138 -0
- package/src/appearance/appearance-host.tsx +205 -0
- package/src/appearance/appearance-preferences.ts +287 -0
- package/src/appearance/composition.ts +29 -0
- package/src/appearance/custom-theme-import.ts +424 -0
- package/src/appearance/custom-theme-library.ts +600 -0
- package/src/appearance/editor.ts +94 -0
- package/src/appearance/theme-file-importer.ts +103 -0
- package/src/appearance/theme-record-adapter.ts +106 -0
- package/src/appearance/theme-registry.ts +20 -0
- package/src/appearance/window-surface.ts +18 -0
- package/src/desktop/client-assets.ts +75 -0
- package/src/native/electrobun-cef-main-frame-bridges.patch +63 -0
- package/src/native/electrobun-windows-shortcut-com.patch +923 -0
- package/src/native/renderer-profile.ts +27 -0
- package/src/native/window-options.ts +24 -0
- package/src/shell/app-shell.tsx +294 -0
- package/src/shell/app-utilities.tsx +437 -0
- package/src/shell/help-shortcuts.ts +24 -0
- package/src/shell/navigation-drawer.tsx +36 -0
- package/src/shell/settings-sections.ts +74 -0
- package/src/shell/shortcut-platform.ts +35 -0
- package/src/updates/release-version.ts +57 -0
- package/src/updates/update-adapter.ts +129 -0
- package/src/updates/update-state.ts +34 -0
- package/src/views/app-about.tsx +44 -0
- package/src/views/app-appearance.tsx +32 -0
- package/src/views/app-help.tsx +43 -0
- package/src/views/app-settings.tsx +88 -0
- package/src/views/appearance-surface.tsx +427 -0
- package/src/views/update-surface.tsx +85 -0
- package/templates/application/.gitattributes +1 -0
- package/templates/application/.github/workflows/release-assets.yml +29 -0
- package/templates/application/.github/workflows/release-finalize.yml +29 -0
- package/templates/application/.github/workflows/release-please.yml +19 -0
- package/templates/application/.github/workflows/release.yml +29 -0
- package/templates/application/.github/workflows/validation.yml +28 -0
- package/templates/application/.oxfmtrc.json +6 -0
- package/templates/application/.oxlintrc.json +48 -0
- package/templates/application/.release-please-manifest.json +3 -0
- package/templates/application/README.md +47 -0
- package/templates/application/electrobun.config.ts +22 -0
- package/templates/application/release-please-config.json +12 -0
- package/templates/application/scripts/app-version.ts +9 -0
- package/templates/application/scripts/build-desktop.ts +34 -0
- package/templates/application/scripts/secure-build.ts +1 -0
- package/templates/application/scripts/stage-release.ts +21 -0
- package/templates/application/src/bun/index.ts +80 -0
- package/templates/application/src/electrobun.d.ts +27 -0
- package/templates/application/src/web/index.html +12 -0
- package/templates/application/src/web/main.tsx +97 -0
- package/templates/application/src/web/public/icon.svg +1 -0
- package/templates/application/src/web/style.css +3 -0
- package/templates/application/tests/app-config.test.ts +9 -0
- package/templates/application/tsconfig.json +15 -0
- package/templates/application/vite.config.ts +10 -0
package/README.md
CHANGED
|
@@ -1,3 +1,1010 @@
|
|
|
1
|
-
#
|
|
1
|
+
# App framework
|
|
2
2
|
|
|
3
|
-
|
|
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.
|