@adea-ai/app-framework 0.27.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/README.md +177 -15
  2. package/dist/app/create-application.d.ts +2 -0
  3. package/dist/app/create-application.js +6 -0
  4. package/dist/app/service-registry.js +4 -0
  5. package/dist/appearance/custom-theme-import.js +43 -7
  6. package/dist/appearance/custom-theme-library.d.ts +2 -0
  7. package/dist/appearance/custom-theme-library.js +5 -1
  8. package/dist/appearance/theme-record-adapter.js +4 -2
  9. package/dist/appearance/theme-registry.js +7 -1
  10. package/dist/cli/create-application-cli.js +4 -2
  11. package/dist/cli/update-helper-cli.js +28 -6
  12. package/dist/desktop/client-asset-manifest.d.ts +47 -0
  13. package/dist/desktop/client-asset-manifest.js +114 -0
  14. package/dist/desktop/client-asset-stream.d.ts +10 -0
  15. package/dist/desktop/client-asset-stream.js +138 -33
  16. package/dist/desktop/client-assets.d.ts +20 -0
  17. package/dist/desktop/client-assets.js +132 -22
  18. package/dist/desktop/client-response-lifecycle.d.ts +22 -0
  19. package/dist/desktop/client-response-lifecycle.js +233 -0
  20. package/dist/desktop/desktop-host.d.ts +40 -2
  21. package/dist/desktop/desktop-host.js +159 -9
  22. package/dist/framework-source.json +1 -1
  23. package/dist/installer/command-artifact.d.ts +4 -2
  24. package/dist/installer/command-artifact.js +119 -19
  25. package/dist/installer/linux-process-group.d.ts +13 -0
  26. package/dist/installer/linux-process-group.js +58 -0
  27. package/dist/native/darwin-sync.d.ts +7 -0
  28. package/dist/native/darwin-sync.js +43 -0
  29. package/dist/native/desktop-build-hook.js +7 -0
  30. package/dist/native/directory-exchange.d.ts +10 -0
  31. package/dist/native/directory-exchange.js +90 -0
  32. package/dist/native/electrobun-source-patch.d.ts +5 -0
  33. package/dist/native/electrobun-source-patch.js +19 -1
  34. package/dist/native/posix-launcher-build.d.ts +24 -0
  35. package/dist/native/posix-launcher-build.js +232 -0
  36. package/dist/native/posix-tree-removal.d.ts +36 -0
  37. package/dist/native/posix-tree-removal.js +425 -0
  38. package/dist/update-helper.bundle.js +1483 -105
  39. package/dist/updates/channel-update-manager.d.ts +5 -0
  40. package/dist/updates/channel-update-manager.js +13 -1
  41. package/dist/updates/desktop-updater.d.ts +78 -2
  42. package/dist/updates/desktop-updater.js +320 -37
  43. package/dist/updates/launch-environment.d.ts +2 -0
  44. package/dist/updates/launch-environment.js +4 -0
  45. package/dist/updates/native-file-lock.d.ts +15 -0
  46. package/dist/updates/native-file-lock.js +189 -0
  47. package/dist/updates/packaged-launch-admission.d.ts +13 -0
  48. package/dist/updates/packaged-launch-admission.js +45 -0
  49. package/dist/updates/packaged-release-config.d.ts +18 -0
  50. package/dist/updates/packaged-release-config.js +60 -0
  51. package/dist/updates/packaged-update-startup.d.ts +44 -0
  52. package/dist/updates/packaged-update-startup.js +81 -0
  53. package/dist/updates/update-arm.d.ts +9 -8
  54. package/dist/updates/update-arm.js +227 -62
  55. package/dist/updates/update-cleanup-error.d.ts +23 -0
  56. package/dist/updates/update-cleanup-error.js +65 -0
  57. package/dist/updates/update-download-cleanup.d.ts +11 -0
  58. package/dist/updates/update-download-cleanup.js +112 -2
  59. package/dist/updates/update-download-lock.d.ts +20 -0
  60. package/dist/updates/update-download-lock.js +73 -0
  61. package/dist/updates/update-download.d.ts +2 -0
  62. package/dist/updates/update-download.js +7 -3
  63. package/dist/updates/update-generation-lease.d.ts +6 -0
  64. package/dist/updates/update-generation-lease.js +14 -0
  65. package/dist/updates/update-helper.d.ts +11 -2
  66. package/dist/updates/update-helper.js +322 -13
  67. package/dist/updates/update-inherited-launch-lease.d.ts +22 -0
  68. package/dist/updates/update-inherited-launch-lease.js +58 -0
  69. package/dist/updates/update-instance-lease.d.ts +15 -0
  70. package/dist/updates/update-instance-lease.js +25 -0
  71. package/dist/updates/update-launch-gate.d.ts +137 -0
  72. package/dist/updates/update-launch-gate.js +617 -0
  73. package/dist/updates/update-launch.js +3 -1
  74. package/dist/updates/update-lock.d.ts +12 -0
  75. package/dist/updates/update-lock.js +18 -0
  76. package/dist/updates/update-manager.d.ts +2 -0
  77. package/dist/updates/update-manager.js +9 -2
  78. package/dist/updates/update-marker.d.ts +7 -0
  79. package/dist/updates/update-marker.js +62 -0
  80. package/dist/updates/update-preflight-error.d.ts +7 -0
  81. package/dist/updates/update-preflight-error.js +11 -0
  82. package/dist/updates/update-process-fence.d.ts +4 -0
  83. package/dist/updates/update-process-fence.js +85 -73
  84. package/dist/updates/update-process-liveness.d.ts +2 -0
  85. package/dist/updates/update-process-liveness.js +11 -0
  86. package/dist/updates/update-resume.d.ts +37 -3
  87. package/dist/updates/update-resume.js +839 -23
  88. package/dist/updates/update-retention-marker.d.ts +67 -0
  89. package/dist/updates/update-retention-marker.js +165 -0
  90. package/dist/updates/update-retention-plan.d.ts +25 -0
  91. package/dist/updates/update-retention-plan.js +54 -0
  92. package/dist/updates/update-retention-sync.d.ts +34 -0
  93. package/dist/updates/update-retention-sync.js +83 -0
  94. package/dist/updates/update-retirement.d.ts +205 -0
  95. package/dist/updates/update-retirement.js +1485 -0
  96. package/dist/updates/update-shutdown.d.ts +16 -4
  97. package/dist/updates/update-shutdown.js +133 -8
  98. package/dist/updates/update-state-store.d.ts +58 -0
  99. package/dist/updates/update-state-store.js +139 -0
  100. package/dist/updates/update-swap-stage.d.ts +1 -1
  101. package/dist/updates/update-swap-stage.js +85 -14
  102. package/dist/updates/update-swap.d.ts +45 -2
  103. package/dist/updates/update-swap.js +207 -17
  104. package/package.json +31 -1
  105. package/src/appearance/custom-theme-import.ts +96 -14
  106. package/src/appearance/custom-theme-library.ts +5 -0
  107. package/src/appearance/theme-record-adapter.ts +15 -6
  108. package/src/appearance/theme-registry.ts +8 -1
  109. package/src/desktop/client-asset-manifest.ts +207 -0
  110. package/src/desktop/client-asset-stream.ts +193 -32
  111. package/src/desktop/client-assets.ts +210 -19
  112. package/src/desktop/client-response-lifecycle.ts +305 -0
  113. package/src/native/electrobun-posix-launch-lease.patch +398 -0
  114. package/templates/application/README.md +50 -0
  115. package/templates/application/electrobun.config.ts +5 -1
  116. package/templates/application/scripts/build-desktop.ts +4 -0
  117. package/templates/application/src/bun/index.ts +173 -16
  118. package/templates/application/vite.config.ts +112 -6
package/README.md CHANGED
@@ -49,16 +49,16 @@ TypeScript source alone, and the rest resolve to `dist`. The package ships only
49
49
  the source those entries reach, plus the Electrobun patches in `src/native`; a
50
50
  test checks the file list against the exports.
51
51
 
52
- | Area | Subpaths (`@adea-ai/app-framework/<subpath>`) |
53
- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54
- | 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` |
55
- | Appearance | `appearance-host`, `appearance-preferences`, `appearance-surface`, `custom-theme-library`, `window-surface` (all _solid_) |
56
- | Desktop host | `desktop-host`, `desktop-gateway`, `desktop-client`, `desktop-stream`, `channel-handshake`, `channel-proof`, `loopback-policy`, `open-url-channel`, `client-assets` (source only) |
57
- | 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` |
58
- | 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) |
59
- | 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` |
60
- | Installer qualification | `installer-layout`, `installer-identity`, `installer-extraction`, `installed-payload`, `installer-observation`, `installer-qualification-command`, `installer-renderer-evidence` |
61
- | CI | `toolchain-identity` |
52
+ | Area | Subpaths (`@adea-ai/app-framework/<subpath>`) |
53
+ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54
+ | 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` |
55
+ | Appearance | `appearance-host`, `appearance-preferences`, `appearance-surface`, `custom-theme-library`, `window-surface` (all _solid_) |
56
+ | Desktop host | `desktop-host`, `desktop-gateway`, `desktop-client`, `desktop-stream`, `channel-handshake`, `channel-proof`, `loopback-policy`, `open-url-channel`, `client-asset-manifest`, `client-assets` (source only) |
57
+ | 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` |
58
+ | Updates | `desktop-updater`, `update-manager`, `update-launch-gate`, `update-inherited-launch-lease`, `packaged-launch-admission`, `packaged-release-config`, `packaged-update-startup`, `update-resume`, `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) |
59
+ | 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` |
60
+ | Installer qualification | `installer-layout`, `installer-identity`, `installer-extraction`, `installed-payload`, `installer-observation`, `installer-qualification-command`, `installer-renderer-evidence` |
61
+ | CI | `toolchain-identity` |
62
62
 
63
63
  Commands (package `bin` entries):
64
64
 
@@ -1053,7 +1053,18 @@ helper for the app's release identity and renderer, resuming after an earlier
1053
1053
  helper on start, and `registerUpdateServices` serves it as the
1054
1054
  `desktop_update_*` services the web update adapter calls. Apps pass their
1055
1055
  `release-config.json`, repository, renderer and helper path; they keep no
1056
- updater code of their own.
1056
+ updater code of their own. Desktop downloads live in the versioned
1057
+ `dataDirectory/updates-v2` root. A cross-process root gate protects directory
1058
+ creation and cleanup, and each download keeps a kernel lease until staging or
1059
+ discard finishes. Startup reclaims a download only after acquiring its lease;
1060
+ if ownership cannot be established, it leaves the data in place for a later
1061
+ startup. The legacy `dataDirectory/updates` root is left untouched so older
1062
+ app versions cannot erase downloads created by this protocol. Process-crash
1063
+ recovery is covered. The root gate and download leases use the same persistent
1064
+ native file locks as the update lock (`flock` on macOS and Linux, `LockFileEx`
1065
+ on Windows); lease files are created, reclaimed and removed only while the root
1066
+ gate is held. Native Windows validation remains outstanding. Abrupt power loss is not
1067
+ covered by these process-lifetime leases.
1057
1068
 
1058
1069
  `desktop-updater` applies a staged update to the installed app.
1059
1070
  `stageUpdateSwap` extracts the verified archive into a private staging
@@ -1061,10 +1072,161 @@ directory beside the install. `armUpdateHelper`, used as the `arm` step of
1061
1072
  `scheduleUpdateShutdown`, copies the app's Bun runtime and the bundled helper
1062
1073
  (`@adea-ai/app-framework/update-helper.js`, which the app ships in its
1063
1074
  resources) into staging, starts it, and resolves once the helper has verified
1064
- the app's processes. After they exit, the helper moves the staged tree into
1065
- place with no-replace renames, deletes the old tree and relaunches the app's
1066
- launcher. On the next start, `resumeUpdate` reports the installed version and
1067
- removes the staging directory.
1075
+ the app's processes. After they exit, the helper exchanges the staged tree
1076
+ with the install and relaunches the app's launcher. The prior tree is kept in a
1077
+ generation-specific quarantine; startup reconciliation removes update staging
1078
+ metadata but does not delete that tree.
1079
+
1080
+ The schema-3 helper handoff now publishes a liveness-bound launch gate and
1081
+ persists its owner with the armed journal before acknowledging readiness to the
1082
+ parent. It waits for the writer lease, syncs the candidate and changed parent
1083
+ directories, records the completed transition, and clears the gate only after
1084
+ rechecking the journal, both tree identities, and the candidate content digest. The parent verifies that the
1085
+ readiness marker, journal mapping, and gate record match. During the writer
1086
+ wait, schema-3 cancellation publication and the final writer-grant check share
1087
+ the update coordinator. A marker published first vetoes the grant; a grant
1088
+ linearized first is the cutoff, and later cancellation receives no
1089
+ acknowledgement. The helper checks the marker under the coordinator, so this
1090
+ ordering does not depend on watcher polling. Schema-1 and schema-2 requests
1091
+ keep their prior helper transition behavior and do not participate in this
1092
+ launch-gate protocol.
1093
+
1094
+ This helper integration remains WIP. Generated bootstrap consumes a
1095
+ launcher-supplied launch lease and runs packaged trust validation when that
1096
+ descriptor is present, but stock generated packages do not enable the opt-in
1097
+ native launcher. The opt-in launcher rejects an existing update gate before
1098
+ starting the worker, so a gate left by a crashed helper still blocks a managed
1099
+ launch until it is recovered. Generated startup without a launcher lease (stock
1100
+ packaging) dispatches that recovery before launch admission:
1101
+ `recoverPackagedUpdateLaunchGate` from
1102
+ `@adea-ai/app-framework/packaged-update-startup` returns `absent` without
1103
+ reading release configuration when no gate exists, and otherwise runs
1104
+ `recoverUpdateLaunchGate(target, trust)` (exported from
1105
+ `@adea-ai/app-framework/update-resume`) under the bundled release trust and
1106
+ saved channel. It returns `busy` while any app instance or transition holds a
1107
+ lock and `helper-live` while the helper's liveness lock is held, and leaves the
1108
+ gate blocked for those and for `unreconciled`; unmanaged startup reports the
1109
+ result and continues as before. The managed launcher does not yet hand a gated
1110
+ launch to this dispatcher, so a managed crash-left gate still needs an
1111
+ unmanaged start or explicit caller-driven recovery. Gate recovery
1112
+ accepts only an exact schema-3 gate/journal match and a signed release verified
1113
+ against the caller's trust configuration. An armed or pre-exchange swapping
1114
+ layout returns to staged; a post-exchange swapping or completed layout is
1115
+ recorded completed. Recovery syncs both exchanged path parents, durably records
1116
+ the phase before clearing the exact gate, and removes only validated helper
1117
+ artifacts while helper liveness is held. Unknown paths, owner/identity
1118
+ mismatches, and malformed state are preserved with the gate blocked. A
1119
+ generation-specific state temporary is an uncommitted atomic replacement: the
1120
+ canonical journal and exact tree proof remain authoritative, so a matching
1121
+ regular temporary can be removed under the recovery locks even if its contents
1122
+ are partial. `resumeUpdate` itself still preserves crash-left gates and returns
1123
+ `recovery-required` until that recovery runs. Launch admission covers only the
1124
+ admitted app process: its lease is independent and close-on-exec, so a
1125
+ descendant such as a renderer helper or sidecar that outlives it does not keep
1126
+ the update writer out. Native renderer descendant lifetime remains unqualified. Schema-1/2 handoffs keep their existing behavior and do
1127
+ not gain this schema-3 digest or gate proof. The stock generated package does
1128
+ not establish end-to-end launch protection.
1129
+ Critical file and directory sync has only been exercised on the current local
1130
+ filesystem; it is not power-loss qualification.
1131
+ Unsupported file or directory sync fails closed. Schema-3 handoff is not
1132
+ qualified on Windows and may fail before helper readiness; Windows directory
1133
+ exchange also remains unqualified.
1134
+
1135
+ Newly staged journals record a deterministic SHA-256 digest over candidate
1136
+ relative names, entry types, permission and special mode bits, regular-file
1137
+ sizes and bytes, and symbolic-link target text. Arm, normal resume, schema-3
1138
+ helper transition, gate clearing, and schema-3 recovery compare that digest
1139
+ when it is present, so in-place edits that leave the candidate root inode
1140
+ unchanged are detected. Digestless legacy journals retain their previous
1141
+ root-identity handling. Schema-1/2 helper transitions do not use the gate or
1142
+ recheck the digest around their exchange. The digest is an integrity
1143
+ checkpoint taken after the signed archive was verified; it is not a signature
1144
+ or an independent proof of release authenticity. Reads reject unsupported
1145
+ entries and check stable file and directory metadata before and after traversal.
1146
+ This is not an atomic snapshot against a hostile process running as the same
1147
+ user. Digestless legacy armed, swapping, and completed journals retain their
1148
+ previous recovery behavior. A digestless staged journal returns
1149
+ `recovery-required`, because the new arm only creates schema-3 handoffs and
1150
+ cannot safely bind the current candidate to the earlier verified extraction.
1151
+ For manual re-staging, fully stop the app and updater, verify that the gate is
1152
+ absent and no helper is live or represented by request/helper artifacts, then
1153
+ rename the complete staging directory aside without deleting it and stage a
1154
+ fresh verified archive. Do not synthesize a digest or edit the old journal.
1155
+
1156
+ For an abandoned pre-journal handoff, recovery only advances a recognized
1157
+ two-rename layout after the recorded helper is proven absent and versions match.
1158
+ It restores the old install when needed and moves the legacy staging tree aside
1159
+ for a fresh verified download. The preserved `.legacy-<uuid>` sibling is not
1160
+ automatically deleted; unknown layouts remain recovery-required. A bounded,
1161
+ ownership-aware retention policy remains unfinished.
1162
+
1163
+ The host can query `updater.pendingHealthAcknowledgement()` for the exact
1164
+ installed generation and version, then call `updater.acknowledgeHealthy(token)`
1165
+ only after app-owned readiness checks pass. The query retries helper retirement
1166
+ for up to five seconds so a one-shot startup health check can see an update
1167
+ whose helper is finishing its relaunch handoff. If the helper remains active,
1168
+ the query returns no token; the host should query again after startup. Launch,
1169
+ helper completion, and host or renderer startup do not acknowledge health. The
1170
+ receipt is published with a temporary file and exclusive rename for
1171
+ process-crash recovery; power-loss durability is not claimed. Consumer
1172
+ readiness criteria and quarantine retention/cleanup remain separate work.
1173
+
1174
+ `acquireRetainedUpdateTrees` from `@adea-ai/app-framework/update-resume` can
1175
+ return the validated retained generation paths with shared, generation-scoped
1176
+ leases. Call it after update staging has been reconciled, and keep the returned
1177
+ handle until every host and response using those trees has stopped. `none` means
1178
+ there are no retained generations; `busy` means a generation lease was held
1179
+ exclusively. A pending cleanup intent or invalid inventory requires recovery.
1180
+ Health acknowledgement is not required to read a retained tree. Lock files are
1181
+ persistent and must not be removed or replaced. The updater does not yet delete
1182
+ retained generations: any future deletion must acquire the corresponding
1183
+ exclusive generation lease under the update lock and revalidate ownership before
1184
+ removing data. The generated bootstrap passes retained roots and the lease to
1185
+ the desktop host when launcher admission is present; stock packages leave that
1186
+ launcher opt-in disabled. Platform and process-crash evidence do not establish
1187
+ power-loss safety.
1188
+
1189
+ Call `resumeUpdateWithRetainedTrees` when startup has the app's explicit
1190
+ `ReleaseTrust` (including its selected channel) and installed version. It holds
1191
+ the per-install update lock across trusted resume and retained-generation lease
1192
+ acquisition. A valid signed staged candidate stays staged while retained roots
1193
+ are acquired. Gated, armed, active-helper, or ambiguous states fail closed.
1194
+ `resumeAndAcquireRetainedDesktopClientAssets` combines that operation with
1195
+ manifest loading for callers that serve old lazy assets. The generated
1196
+ bootstrap reads the packaged release identity, repository, feed and public
1197
+ keys, and lets the saved channel select only an embedded channel. Missing or
1198
+ malformed trust, channel, or recovery state stops managed startup while
1199
+ preserving update state.
1200
+
1201
+ `acquireRetainedDesktopClientAssets` from `desktop-updater` maps validated
1202
+ retired packaged trees to their client roots and calls an app-supplied manifest
1203
+ loader while the generation leases are held. Its trusted startup counterpart,
1204
+ `resumeAndAcquireRetainedDesktopClientAssets`, takes explicit trust and current
1205
+ version, reconciles pending update state under the same lock, then maps retained
1206
+ client roots. Both return retained assets with an idempotent `release`; a
1207
+ manifest-loader failure releases acquired leases before it rejects. The
1208
+ generated bootstrap transfers this result to `startDesktopHostWithRetainedLease`
1209
+ after launcher admission. On restart, the host pauses new asset responses and
1210
+ waits up to five seconds for active responses to finish naturally. A timeout
1211
+ causes helper cancellation; asset admission resumes only after cancellation
1212
+ clears the launch gate. A conservative absolute deadline starts before helper
1213
+ spawn, caps quiescence at five seconds, and reserves eleven seconds before the
1214
+ helper's 30-second process fence for cancellation and gate cleanup. Terminal
1215
+ close uses the remaining budget and exits instead of attempting to reopen a
1216
+ native host after shutdown begins. If the budget expires before terminal close
1217
+ begins, shutdown is rejected so helper cancellation can finish before asset
1218
+ admission resumes. The stock launcher opt-in and crash-left gate recovery remain
1219
+ unresolved.
1220
+
1221
+ With the updater and retained-asset resolver integrated,
1222
+ `FRAMEWORK_INTEGRATED_SURVIVOR=1 bun test tests/updates/update-handoff-e2e.test.ts`
1223
+ also keeps a headless browser page alive across a real helper swap, loads the
1224
+ retired manifest through the packaged-client helper under its generation lease, and requests its old lazy chunk
1225
+ from the replacement host. Set `FRAMEWORK_RENDERER_ENGINE=webkit` to select
1226
+ Playwright WebKit instead of Chromium. The test uses mocked native windows and
1227
+ manually stops and restarts the hosts, so it does not qualify packaged native
1228
+ renderer shutdown. The opt-in requires the resolver changes; this draft alone
1229
+ reports that dependency rather than treating the probe as a pass.
1068
1230
 
1069
1231
  ### Preserving an existing desktop origin
1070
1232
 
@@ -7,6 +7,8 @@ export declare function createApplication(options: {
7
7
  name: string;
8
8
  identifier: string;
9
9
  sourceUrl: string;
10
+ /** GitHub `owner/name` for signed desktop releases; inferred only from a canonical GitHub source URL. */
11
+ repository?: string;
10
12
  frameworkSpecifier: string;
11
13
  renderer?: DesktopRenderer;
12
14
  }, dependencies?: {
@@ -59,6 +59,11 @@ async function createApplication(options, dependencies = {}) {
59
59
  throw new Error("Invalid application source URL");
60
60
  }
61
61
  if (source.protocol !== "https:" || source.username || source.password) throw new Error("Invalid application source URL");
62
+ const sourcePath = source.pathname.endsWith("/") ? source.pathname.slice(0, -1) : source.pathname;
63
+ const repositoryPath = sourcePath.endsWith(".git") ? sourcePath.slice(0, -4) : sourcePath;
64
+ const sourceRepository = source.hostname.toLowerCase() === "github.com" && !source.port && !source.search && !source.hash ? /^\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(repositoryPath) : null;
65
+ const repository = options.repository ?? (sourceRepository && sourceRepository[1] !== "." && sourceRepository[1] !== ".." && sourceRepository[2] !== "." && sourceRepository[2] !== ".." ? `${sourceRepository[1]}/${sourceRepository[2]}` : void 0);
66
+ if (options.repository !== void 0 && (typeof options.repository !== "string" || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(options.repository) || options.repository.split("/").some((part) => part === "." || part === ".."))) throw new Error("Invalid application release repository");
62
67
  if (containsAsciiControl(options.frameworkSpecifier, true) || options.frameworkSpecifier.length > 512) throw new Error("Invalid framework dependency");
63
68
  if (/^(?:git\+)?https?:/i.test(options.frameworkSpecifier)) {
64
69
  let dependency;
@@ -211,6 +216,7 @@ async function createApplication(options, dependencies = {}) {
211
216
  control: ".github/workflows/release.yml",
212
217
  assets: ".github/workflows/release-assets.yml"
213
218
  },
219
+ ...repository === void 0 ? {} : { repository },
214
220
  releaseFeed: {
215
221
  base: "https://adea.dev/releases/",
216
222
  app: options.slug
@@ -95,6 +95,10 @@ function createServiceRegistry() {
95
95
  code: "unauthorized"
96
96
  };
97
97
  }
98
+ if (entries.get(name) !== entry) return {
99
+ ok: false,
100
+ code: "unknown_service"
101
+ };
98
102
  if (signal?.aborted) return {
99
103
  ok: false,
100
104
  code: "unauthorized"
@@ -97,15 +97,45 @@ function isHex(value) {
97
97
  return typeof value === "string" && parseColor(value) !== void 0;
98
98
  }
99
99
  /** Repair one foreground/background pair to the readable floor, reporting it. */
100
- function repairToFloor(foreground, background, notes, role) {
100
+ function repairToFloor(foreground, background, notes, role, minimum = 4.5) {
101
101
  const front = parseColor(foreground);
102
102
  const back = parseColor(background);
103
103
  if (!front || !back) return foreground;
104
- if (contrastRatio(front, back) >= 4.5) return foreground;
105
- const repaired = ensureContrast(front, back, 4.5);
104
+ if (contrastRatio(front, back) >= minimum) return foreground;
105
+ const repaired = ensureContrast(front, back, minimum);
106
106
  notes.push(`“${role}” was adjusted for readable contrast.`);
107
107
  return colorToHex(repaired);
108
108
  }
109
+ /** Repair the explicit component pairs after either projection has chosen their surfaces. */
110
+ function repairComponentContrast(variant, notes) {
111
+ const colors = variant.colors;
112
+ return {
113
+ ...variant,
114
+ colors: {
115
+ ...colors,
116
+ cardForeground: repairToFloor(colors.cardForeground, colors.card, notes, "card foreground"),
117
+ popoverForeground: repairToFloor(colors.popoverForeground, colors.popover, notes, "popover foreground"),
118
+ secondaryForeground: repairToFloor(colors.secondaryForeground, colors.secondary, notes, "secondary foreground"),
119
+ accentForeground: repairToFloor(colors.accentForeground, colors.accent, notes, "highlight foreground"),
120
+ muted: repairToFloor(colors.muted, colors.mutedForeground, notes, "muted surface")
121
+ }
122
+ };
123
+ }
124
+ /** Preserve accessible sidebar pairs that the catalogue record would otherwise re-derive. */
125
+ function sidebarTokens(variant, notes) {
126
+ const colors = variant.colors;
127
+ return {
128
+ "--sidebar": colors.card,
129
+ "--sidebar-foreground": repairToFloor(colors.cardForeground, colors.card, notes, "sidebar foreground"),
130
+ "--sidebar-muted-foreground": repairToFloor(colors.mutedForeground, colors.card, notes, "sidebar muted foreground"),
131
+ "--sidebar-accent": colors.accent,
132
+ "--sidebar-accent-foreground": repairToFloor(colors.accentForeground, colors.accent, notes, "sidebar accent foreground"),
133
+ "--sidebar-border": colors.border,
134
+ "--sidebar-primary": colors.primary,
135
+ "--sidebar-primary-foreground": repairToFloor(colors.primaryForeground, colors.primary, notes, "sidebar primary foreground"),
136
+ "--sidebar-ring": colors.ring
137
+ };
138
+ }
109
139
  function hexOf(value) {
110
140
  const parsed = parseOklchColor(value);
111
141
  return parsed ? oklchToHex(parsed) : value;
@@ -237,6 +267,8 @@ function prepareCustomTheme(text, existing) {
237
267
  colors.text = repairToFloor(colors.text, colors.background, notes, "text");
238
268
  colors.textMuted = repairToFloor(colors.textMuted, colors.background, notes, "muted text");
239
269
  colors.textSubtle = repairToFloor(colors.textSubtle, colors.background, notes, "subtle text");
270
+ colors.accent = repairToFloor(colors.accent, colors.background, notes, "accent", 3);
271
+ colors.accentForeground = repairToFloor(colors.accentForeground, colors.accent, notes, "accent foreground");
240
272
  const ansiRecord = record.ansi ?? {};
241
273
  const ansi = ANSI_KEYS.map((key) => {
242
274
  const value = ansiRecord[key];
@@ -256,9 +288,10 @@ function prepareCustomTheme(text, existing) {
256
288
  try {
257
289
  variant = projectCanonical(canonical);
258
290
  } catch {
259
- variant = projectHostFallback(name, appearance, canonical.colors, ansi);
291
+ variant = projectHostFallback(name, appearance, canonical.colors, ansi, notes);
260
292
  notes.push("Syntax roles were approximated from the ANSI ramp.");
261
293
  }
294
+ variant = repairComponentContrast(variant, notes);
262
295
  variant = {
263
296
  ...variant,
264
297
  id: uniqueThemeId(name, existing),
@@ -274,7 +307,10 @@ function prepareCustomTheme(text, existing) {
274
307
  appearance,
275
308
  importedAt: (/* @__PURE__ */ new Date()).toISOString(),
276
309
  variant,
277
- flatTokens: flatVariantTokens(variant),
310
+ flatTokens: {
311
+ ...flatVariantTokens(variant),
312
+ ...sidebarTokens(variant, notes)
313
+ },
278
314
  notes
279
315
  }
280
316
  };
@@ -308,7 +344,7 @@ async function importCustomThemeAtomically(text, storage, options = {}) {
308
344
  };
309
345
  }
310
346
  /** Direct host projection for inputs the canonical adapters reject. */
311
- function projectHostFallback(name, appearance, colors, ansi) {
347
+ function projectHostFallback(name, appearance, colors, ansi, notes) {
312
348
  const ramp = (index) => ansi[index] ?? colors.foreground;
313
349
  const editor = Object.fromEntries(Object.entries(SYNTAX_SOURCES).map(([role, source]) => {
314
350
  return [role, repairToFloor(source === "foreground" ? colors.foreground : ramp(ANSI_KEYS.indexOf(source)), colors.background, [], role)];
@@ -336,7 +372,7 @@ function projectHostFallback(name, appearance, colors, ansi) {
336
372
  accentForeground: colors.text,
337
373
  destructive: colors.error,
338
374
  destructiveAction: colors.error,
339
- destructiveActionForeground: colors.accentForeground,
375
+ destructiveActionForeground: repairToFloor(colors.accentForeground, colors.error, notes, "destructive action foreground"),
340
376
  success: colors.success,
341
377
  border: colors.border,
342
378
  input: colors.border,
@@ -155,6 +155,8 @@ export declare function storedVariantRecord(variant: StoredThemeVariant): AdeaTh
155
155
  export declare function toUiVariant(stored: CustomThemeStored): UiThemeVariant;
156
156
  /** The imported themes' stored variants, in import order. */
157
157
  export declare function customThemeVariants(): readonly StoredThemeVariant[];
158
+ /** Find one stored variant without projecting the rest of the imported library. */
159
+ export declare function customThemeVariantById(id: string): StoredThemeVariant | undefined;
158
160
  /** The imported themes as shared-provider variants: what the provider's `themes` takes. */
159
161
  export declare function customUiVariants(): readonly UiThemeVariant[];
160
162
  export declare function subscribeCustomThemes(listener: () => void): () => void;
@@ -212,6 +212,10 @@ function replaceThemes(themes) {
212
212
  function customThemeVariants() {
213
213
  return library().themes.map((theme) => theme.variant);
214
214
  }
215
+ /** Find one stored variant without projecting the rest of the imported library. */
216
+ function customThemeVariantById(id) {
217
+ return library().themes.find((theme) => theme.variant.id === id)?.variant;
218
+ }
215
219
  /** The imported themes as shared-provider variants: what the provider's `themes` takes. */
216
220
  function customUiVariants() {
217
221
  const state = library();
@@ -604,4 +608,4 @@ function removeCustomTheme(id, storage) {
604
608
  const themes = library().themes;
605
609
  return setCustomThemes(themes.filter((theme) => theme.id !== id), storage);
606
610
  }
607
- export { CUSTOM_THEME_ATOMIC_STORAGE_UNAVAILABLE, CUSTOM_THEME_LIBRARY_LOCK_NAME, CUSTOM_THEME_LIBRARY_MUTATION_FAILED, CUSTOM_THEME_LIBRARY_RECOVERY_KEY, CUSTOM_THEME_LIBRARY_STORAGE_KEY, customThemeVariants, customUiVariants, flatVariantTokens, mutateCustomThemeLibrary, readCustomThemeLibrary, removeCustomTheme, removeCustomThemeAtomically, setCustomThemes, storedVariantRecord, subscribeCustomThemes, toUiVariant, validateThemeRegistry };
611
+ export { CUSTOM_THEME_ATOMIC_STORAGE_UNAVAILABLE, CUSTOM_THEME_LIBRARY_LOCK_NAME, CUSTOM_THEME_LIBRARY_MUTATION_FAILED, CUSTOM_THEME_LIBRARY_RECOVERY_KEY, CUSTOM_THEME_LIBRARY_STORAGE_KEY, customThemeVariantById, customThemeVariants, customUiVariants, flatVariantTokens, mutateCustomThemeLibrary, readCustomThemeLibrary, removeCustomTheme, removeCustomThemeAtomically, setCustomThemes, storedVariantRecord, subscribeCustomThemes, toUiVariant, validateThemeRegistry };
@@ -1,5 +1,5 @@
1
1
  import "./appearance-preferences.js";
2
- import { customThemeVariants, storedVariantRecord } from "./custom-theme-library.js";
2
+ import { customThemeVariantById, customThemeVariants, storedVariantRecord } from "./custom-theme-library.js";
3
3
  import { themeRegistry } from "./theme-registry.js";
4
4
  import { accentRolesForSelection, themeRecordById, themeRecords } from "@adea-ai/ui/lib/themes";
5
5
  import { getAccent } from "@adea-ai/ui/lib/accent-presets";
@@ -49,7 +49,9 @@ function withAccent(theme, accent, pair) {
49
49
  * accent is read from.
50
50
  */
51
51
  function appearanceThemeForPreview(variant, accent, pair) {
52
- return withAccent(themeRecordById(variant.id) ?? customThemeRecords().find((candidate) => candidate.id === variant.id) ?? (variant.appearance === "dark" ? adeaDark : adeaLight), accent, pair);
52
+ const catalogueRecord = themeRecordById(variant.id);
53
+ const importedVariant = catalogueRecord ? void 0 : customThemeVariantById(variant.id);
54
+ return withAccent(catalogueRecord ?? (importedVariant ? storedVariantRecord(importedVariant) : variant.appearance === "dark" ? adeaDark : adeaLight), accent, pair);
53
55
  }
54
56
  /** Preserve the host's invalid-input behavior while feeding the pure editor. */
55
57
  function normalizeCustomAccent(value, background) {
@@ -1,6 +1,7 @@
1
1
  import { customUiVariants } from "./custom-theme-library.js";
2
2
  import { builtinThemes } from "@adea-ai/ui/lib/themes";
3
3
  // src/appearance/theme-registry.ts
4
+ var registriesByCustomVariants = /* @__PURE__ */ new WeakMap();
4
5
  /**
5
6
  * Every selectable theme: the catalogue first, then imported themes.
6
7
  *
@@ -11,6 +12,11 @@ import { builtinThemes } from "@adea-ai/ui/lib/themes";
11
12
  */
12
13
  function themeRegistry() {
13
14
  const custom = customUiVariants();
14
- return custom.length > 0 ? [...builtinThemes, ...custom] : builtinThemes;
15
+ if (custom.length === 0) return builtinThemes;
16
+ const cached = registriesByCustomVariants.get(custom);
17
+ if (cached) return cached;
18
+ const registry = [...builtinThemes, ...custom];
19
+ registriesByCustomVariants.set(custom, registry);
20
+ return registry;
15
21
  }
16
22
  export { themeRegistry };
@@ -2,7 +2,7 @@
2
2
  import { createApplication } from "../app/create-application.js";
3
3
  import { runCli } from "./cli-runner.js";
4
4
  // src/cli/create-application-cli.ts
5
- var usage = "Usage: create-adea-app --directory PATH --slug SLUG --name NAME --identifier REVERSE_DNS --source-url HTTPS_URL --framework SPECIFIER [--renderer native|cef]";
5
+ var usage = "Usage: create-adea-app --directory PATH --slug SLUG --name NAME --identifier REVERSE_DNS --source-url HTTPS_URL --framework SPECIFIER [--repository OWNER/NAME] [--renderer native|cef]";
6
6
  var allowed = /* @__PURE__ */ new Set([
7
7
  "directory",
8
8
  "slug",
@@ -10,6 +10,7 @@ var allowed = /* @__PURE__ */ new Set([
10
10
  "identifier",
11
11
  "source-url",
12
12
  "framework",
13
+ "repository",
13
14
  "renderer"
14
15
  ]);
15
16
  await runCli((error) => error instanceof Error ? error.message : "Could not create application", async () => {
@@ -25,7 +26,7 @@ await runCli((error) => error instanceof Error ? error.message : "Could not crea
25
26
  if (!allowed.has(key) || values[key] !== void 0 || !value || value.startsWith("--")) throw new Error(usage);
26
27
  values[key] = value;
27
28
  }
28
- const { directory, slug, name, identifier, "source-url": sourceUrl, framework, renderer } = values;
29
+ const { directory, slug, name, identifier, "source-url": sourceUrl, framework, repository, renderer } = values;
29
30
  if (!directory || !slug || !name || !identifier || !sourceUrl || !framework || renderer && renderer !== "native" && renderer !== "cef") throw new Error(usage);
30
31
  const result = await createApplication({
31
32
  directory,
@@ -33,6 +34,7 @@ await runCli((error) => error instanceof Error ? error.message : "Could not crea
33
34
  name,
34
35
  identifier,
35
36
  sourceUrl,
37
+ repository,
36
38
  frameworkSpecifier: framework,
37
39
  renderer
38
40
  });
@@ -1,10 +1,32 @@
1
1
  import { runUpdateHelper } from "../updates/update-helper.js";
2
2
  // src/cli/update-helper-cli.ts
3
- var index = process.argv.indexOf("--staging");
4
- var staging = index > 0 ? process.argv[index + 1] : void 0;
5
- if (!staging) {
6
- console.error("Usage: update-helper --staging <directory>");
3
+ var values = /* @__PURE__ */ new Map();
4
+ var argv = process.argv.slice(2);
5
+ var invalid = argv.length % 2 !== 0;
6
+ for (let index = 0; index < argv.length; index += 2) {
7
+ const key = argv[index];
8
+ const value = argv[index + 1];
9
+ if (key !== "--staging" && key !== "--target" && key !== "--generation" && key !== "--owner" || !value || value.startsWith("--") || values.has(key)) {
10
+ invalid = true;
11
+ break;
12
+ }
13
+ values.set(key, value);
14
+ }
15
+ var staging = values.get("--staging");
16
+ var target = values.get("--target");
17
+ var generation = values.get("--generation");
18
+ var helperOwner = values.get("--owner");
19
+ var hasBinding = target !== void 0 || generation !== void 0 || helperOwner !== void 0;
20
+ if (invalid || !staging || hasBinding && (!target || !generation || !helperOwner) || !hasBinding && values.size !== 1) {
21
+ console.error("Usage: update-helper --staging <directory> [--target <path> --generation <uuid> --owner <uuid>]");
7
22
  process.exit(2);
8
23
  }
9
- var outcome = await runUpdateHelper({ staging }).catch(() => "failed");
10
- process.exit(outcome === "updated" ? 0 : 1);
24
+ var outcome = await runUpdateHelper({
25
+ staging,
26
+ ...hasBinding ? {
27
+ target,
28
+ generation,
29
+ helperOwner
30
+ } : {}
31
+ }).catch(() => "failed");
32
+ process.exit(outcome === "updated" || outcome === "cancelled" ? 0 : 1);
@@ -0,0 +1,47 @@
1
+ export declare const CLIENT_ASSET_MANIFEST_FILE = "client-assets-manifest.json";
2
+ export declare const CLIENT_ASSET_ASSET_PATTERN = "assets/[name]-[hash][extname]";
3
+ export declare const CLIENT_ASSET_CHUNK_PATTERN = "assets/[name]-[hash].js";
4
+ declare const FORMAT = "adea-client-assets-v1";
5
+ export type ClientAssetManifest = {
6
+ format: typeof FORMAT;
7
+ assets: readonly {
8
+ path: string;
9
+ sha256: string;
10
+ }[];
11
+ };
12
+ type ViteOutput = {
13
+ type: 'chunk';
14
+ fileName: string;
15
+ name: string;
16
+ isEntry: boolean;
17
+ facadeModuleId?: string | null;
18
+ moduleIds?: readonly string[];
19
+ code: string;
20
+ } | {
21
+ type: 'asset';
22
+ fileName: string;
23
+ name?: string;
24
+ source: string | Uint8Array;
25
+ };
26
+ type ViteOutputBundle = Readonly<Record<string, ViteOutput>>;
27
+ /** Build a cache allowlist from Vite's actual output bundle and explicit Rollup names. */
28
+ export declare function createClientAssetManifest(bundle: ViteOutputBundle, output: {
29
+ assetFileNames?: unknown;
30
+ chunkFileNames?: unknown;
31
+ entryFileNames?: unknown;
32
+ }, namingEvidence: ReadonlyMap<string, number>): ClientAssetManifest;
33
+ /** Evidence keys for Rollup naming callbacks; explicit `fileName` outputs never call them. */
34
+ export declare function clientAssetChunkEvidenceKey(chunk: {
35
+ name: string;
36
+ isEntry: boolean;
37
+ facadeModuleId?: string | null;
38
+ moduleIds?: readonly string[];
39
+ }): string;
40
+ export declare function clientAssetAssetEvidenceKey(asset: {
41
+ name?: string | null;
42
+ }): string;
43
+ /** Parse a complete manifest. Any malformed or duplicate entry disables the whole allowlist. */
44
+ export declare function parseClientAssetManifest(input: unknown): ReadonlyMap<string, string>;
45
+ /** Snapshot a caller-provided allowlist and reject it as a whole if any entry is invalid. */
46
+ export declare function snapshotClientAssetAllowlist(value: ReadonlyMap<string, string> | undefined): ReadonlyMap<string, string>;
47
+ export {};