@adea-ai/app-framework 0.26.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 (138) hide show
  1. package/README.md +183 -17
  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/cef-helper-cli.js +0 -0
  11. package/dist/cli/create-application-cli.js +4 -2
  12. package/dist/cli/electrobun-shortcut-patch-cli.js +0 -0
  13. package/dist/cli/framework-update-cli.js +0 -0
  14. package/dist/cli/macos-signing-cli.js +0 -0
  15. package/dist/cli/release-assets-plan-cli.js +0 -0
  16. package/dist/cli/release-cut-cli.js +0 -0
  17. package/dist/cli/release-descriptor-staging-cli.js +0 -0
  18. package/dist/cli/release-finalize-cli.js +0 -0
  19. package/dist/cli/release-promote-cli.js +0 -0
  20. package/dist/cli/release-publish-cli.js +0 -0
  21. package/dist/cli/release-sign-cli.js +0 -0
  22. package/dist/cli/release-step-cli.js +6 -1
  23. package/dist/cli/toolchain-identity-cli.js +0 -0
  24. package/dist/cli/update-helper-cli.js +28 -6
  25. package/dist/cli/windows-runtime-patch-cli.js +0 -0
  26. package/dist/desktop/client-asset-manifest.d.ts +47 -0
  27. package/dist/desktop/client-asset-manifest.js +114 -0
  28. package/dist/desktop/client-asset-stream.d.ts +10 -0
  29. package/dist/desktop/client-asset-stream.js +138 -33
  30. package/dist/desktop/client-assets.d.ts +20 -0
  31. package/dist/desktop/client-assets.js +132 -22
  32. package/dist/desktop/client-response-lifecycle.d.ts +22 -0
  33. package/dist/desktop/client-response-lifecycle.js +233 -0
  34. package/dist/desktop/desktop-host.d.ts +40 -2
  35. package/dist/desktop/desktop-host.js +159 -9
  36. package/dist/framework-source.json +1 -1
  37. package/dist/installer/command-artifact.d.ts +4 -2
  38. package/dist/installer/command-artifact.js +119 -19
  39. package/dist/installer/installer-identity.d.ts +4 -1
  40. package/dist/installer/installer-identity.js +6 -3
  41. package/dist/installer/installer-layout.d.ts +2 -0
  42. package/dist/installer/installer-layout.js +5 -1
  43. package/dist/installer/linux-process-group.d.ts +13 -0
  44. package/dist/installer/linux-process-group.js +58 -0
  45. package/dist/native/darwin-sync.d.ts +7 -0
  46. package/dist/native/darwin-sync.js +43 -0
  47. package/dist/native/desktop-build-hook.js +7 -0
  48. package/dist/native/directory-exchange.d.ts +10 -0
  49. package/dist/native/directory-exchange.js +90 -0
  50. package/dist/native/electrobun-source-patch.d.ts +5 -0
  51. package/dist/native/electrobun-source-patch.js +19 -1
  52. package/dist/native/posix-launcher-build.d.ts +24 -0
  53. package/dist/native/posix-launcher-build.js +232 -0
  54. package/dist/native/posix-tree-removal.d.ts +36 -0
  55. package/dist/native/posix-tree-removal.js +425 -0
  56. package/dist/release/release-steps.d.ts +5 -0
  57. package/dist/release/release-steps.js +2 -1
  58. package/dist/update-helper.bundle.js +1483 -105
  59. package/dist/updates/channel-update-manager.d.ts +5 -0
  60. package/dist/updates/channel-update-manager.js +13 -1
  61. package/dist/updates/desktop-updater.d.ts +78 -2
  62. package/dist/updates/desktop-updater.js +320 -37
  63. package/dist/updates/launch-environment.d.ts +2 -0
  64. package/dist/updates/launch-environment.js +4 -0
  65. package/dist/updates/native-file-lock.d.ts +15 -0
  66. package/dist/updates/native-file-lock.js +189 -0
  67. package/dist/updates/packaged-launch-admission.d.ts +13 -0
  68. package/dist/updates/packaged-launch-admission.js +45 -0
  69. package/dist/updates/packaged-release-config.d.ts +18 -0
  70. package/dist/updates/packaged-release-config.js +60 -0
  71. package/dist/updates/packaged-update-startup.d.ts +44 -0
  72. package/dist/updates/packaged-update-startup.js +81 -0
  73. package/dist/updates/update-arm.d.ts +9 -8
  74. package/dist/updates/update-arm.js +227 -62
  75. package/dist/updates/update-cleanup-error.d.ts +23 -0
  76. package/dist/updates/update-cleanup-error.js +65 -0
  77. package/dist/updates/update-download-cleanup.d.ts +11 -0
  78. package/dist/updates/update-download-cleanup.js +112 -2
  79. package/dist/updates/update-download-lock.d.ts +20 -0
  80. package/dist/updates/update-download-lock.js +73 -0
  81. package/dist/updates/update-download.d.ts +2 -0
  82. package/dist/updates/update-download.js +7 -3
  83. package/dist/updates/update-generation-lease.d.ts +6 -0
  84. package/dist/updates/update-generation-lease.js +14 -0
  85. package/dist/updates/update-helper.d.ts +11 -2
  86. package/dist/updates/update-helper.js +322 -13
  87. package/dist/updates/update-inherited-launch-lease.d.ts +22 -0
  88. package/dist/updates/update-inherited-launch-lease.js +58 -0
  89. package/dist/updates/update-instance-lease.d.ts +15 -0
  90. package/dist/updates/update-instance-lease.js +25 -0
  91. package/dist/updates/update-launch-gate.d.ts +137 -0
  92. package/dist/updates/update-launch-gate.js +617 -0
  93. package/dist/updates/update-launch.js +3 -1
  94. package/dist/updates/update-lock.d.ts +12 -0
  95. package/dist/updates/update-lock.js +18 -0
  96. package/dist/updates/update-manager.d.ts +2 -0
  97. package/dist/updates/update-manager.js +9 -2
  98. package/dist/updates/update-marker.d.ts +7 -0
  99. package/dist/updates/update-marker.js +62 -0
  100. package/dist/updates/update-preflight-error.d.ts +7 -0
  101. package/dist/updates/update-preflight-error.js +11 -0
  102. package/dist/updates/update-process-fence.d.ts +4 -0
  103. package/dist/updates/update-process-fence.js +85 -73
  104. package/dist/updates/update-process-liveness.d.ts +2 -0
  105. package/dist/updates/update-process-liveness.js +11 -0
  106. package/dist/updates/update-resume.d.ts +37 -3
  107. package/dist/updates/update-resume.js +839 -23
  108. package/dist/updates/update-retention-marker.d.ts +67 -0
  109. package/dist/updates/update-retention-marker.js +165 -0
  110. package/dist/updates/update-retention-plan.d.ts +25 -0
  111. package/dist/updates/update-retention-plan.js +54 -0
  112. package/dist/updates/update-retention-sync.d.ts +34 -0
  113. package/dist/updates/update-retention-sync.js +83 -0
  114. package/dist/updates/update-retirement.d.ts +205 -0
  115. package/dist/updates/update-retirement.js +1485 -0
  116. package/dist/updates/update-shutdown.d.ts +16 -4
  117. package/dist/updates/update-shutdown.js +133 -8
  118. package/dist/updates/update-state-store.d.ts +58 -0
  119. package/dist/updates/update-state-store.js +139 -0
  120. package/dist/updates/update-swap-stage.d.ts +1 -1
  121. package/dist/updates/update-swap-stage.js +85 -14
  122. package/dist/updates/update-swap.d.ts +45 -2
  123. package/dist/updates/update-swap.js +207 -17
  124. package/package.json +31 -1
  125. package/src/appearance/custom-theme-import.ts +96 -14
  126. package/src/appearance/custom-theme-library.ts +5 -0
  127. package/src/appearance/theme-record-adapter.ts +15 -6
  128. package/src/appearance/theme-registry.ts +8 -1
  129. package/src/desktop/client-asset-manifest.ts +207 -0
  130. package/src/desktop/client-asset-stream.ts +193 -32
  131. package/src/desktop/client-assets.ts +210 -19
  132. package/src/desktop/client-response-lifecycle.ts +305 -0
  133. package/src/native/electrobun-posix-launch-lease.patch +398 -0
  134. package/templates/application/README.md +50 -0
  135. package/templates/application/electrobun.config.ts +5 -1
  136. package/templates/application/scripts/build-desktop.ts +4 -0
  137. package/templates/application/src/bun/index.ts +173 -16
  138. package/templates/application/vite.config.ts +112 -6
@@ -15,11 +15,16 @@ export declare function createChannelUpdateManager(options: {
15
15
  directory: string;
16
16
  maxBytes: number;
17
17
  stage: ManagerOptions['stage'];
18
+ beforeDownload?: ManagerOptions['beforeDownload'];
18
19
  /** Discard a downloaded result that is rejected before stage takes ownership. */
19
20
  discardDownload?: ManagerOptions['stage'];
20
21
  discover?: ManagerOptions['discover'];
21
22
  download?: ManagerOptions['download'];
22
23
  fetch?: FetchFunction;
24
+ /** A signed staged candidate recovered on startup, available for explicit re-approval. */
25
+ stagedVersion?: string;
26
+ /** A preserved candidate that could not be verified for safe resumption. */
27
+ recoveryError?: string;
23
28
  }): {
24
29
  status: () => Readonly<{
25
30
  phase: "available" | "checking" | "current" | "downloading" | "failed" | "idle" | "staged" | "staging";
@@ -9,7 +9,18 @@ function createChannelUpdateManager(options) {
9
9
  const download = options.download;
10
10
  const discardDownload = selectUpdateDownloadDiscard(directory, download !== void 0, options.discardDownload);
11
11
  let busy = false, active;
12
- let state = Object.freeze({
12
+ if (options.stagedVersion !== void 0 && options.recoveryError !== void 0) throw new Error("Update recovery cannot be both staged and blocked");
13
+ let state = Object.freeze(options.stagedVersion !== void 0 ? {
14
+ phase: "staged",
15
+ currentVersion: options.currentVersion,
16
+ availableVersion: options.stagedVersion,
17
+ error: null
18
+ } : options.recoveryError !== void 0 ? {
19
+ phase: "failed",
20
+ currentVersion: options.currentVersion,
21
+ availableVersion: null,
22
+ error: options.recoveryError
23
+ } : {
13
24
  phase: "idle",
14
25
  currentVersion: options.currentVersion,
15
26
  availableVersion: null,
@@ -76,6 +87,7 @@ function createChannelUpdateManager(options) {
76
87
  download,
77
88
  discardDownload,
78
89
  fetch: options.fetch,
90
+ beforeDownload: options.beforeDownload,
79
91
  stage: async (input) => {
80
92
  try {
81
93
  if (await options.store.read() !== channel) throw new Error("Update channel changed");
@@ -4,6 +4,9 @@ import { createChannelUpdateManager } from './channel-update-manager';
4
4
  import { type UpdateChannel } from './release-version';
5
5
  import type { ReleaseTrust } from './signed-release';
6
6
  import type { UpdateState } from './update-adapter';
7
+ import type { UpdateResumeResult } from './update-resume';
8
+ import { type UpdateHealthAcknowledgement } from './update-retirement';
9
+ import { type UpdateShutdownTiming } from './update-shutdown';
7
10
  import type { NativeUpdateState } from './update-state';
8
11
  export type DesktopUpdatePhase = UpdateState['phase'];
9
12
  /** The snapshot every update service returns. */
@@ -28,6 +31,63 @@ export declare function updatePlatform(platform?: string, arch?: string): Instal
28
31
  * app directory elsewhere. The host entry runs from `Resources/app/bun`.
29
32
  */
30
33
  export declare function installTarget(entryDirectory: string, platform: InstallerPlatform): string;
34
+ /**
35
+ * Acquire the updater's retained generations and map their packaged client
36
+ * directories to manifests. The caller must already hold any required native
37
+ * launch admission lease and must retain the returned generation leases until
38
+ * the host and all response bodies are drained. This does not gate startup.
39
+ * `loadManifest` receives a retained client root while its lease is held.
40
+ */
41
+ export declare function acquireRetainedDesktopClientAssets(options: {
42
+ entryDirectory: string;
43
+ currentVersion: string;
44
+ loadManifest(root: string): Promise<ReadonlyMap<string, string>>;
45
+ }): Promise<Readonly<{
46
+ status: 'none' | 'busy';
47
+ }> | {
48
+ status: 'unsupported';
49
+ retainedClientAssets?: undefined;
50
+ release?: undefined;
51
+ } | {
52
+ status: 'acquired';
53
+ retainedClientAssets: {
54
+ root: string;
55
+ immutableAssets: ReadonlyMap<string, string>;
56
+ }[];
57
+ release: () => Promise<void>;
58
+ }>;
59
+ /**
60
+ * Trusted startup variant for callers that must preserve normal pending staged
61
+ * updates while pinning retained generations. Resume and lease acquisition are
62
+ * serialized under the install lock; callers keep the returned lease through
63
+ * host shutdown and response draining.
64
+ */
65
+ export declare function resumeAndAcquireRetainedDesktopClientAssets(options: {
66
+ entryDirectory: string;
67
+ currentVersion: string;
68
+ trust: ReleaseTrust;
69
+ loadManifest(root: string): Promise<ReadonlyMap<string, string>>;
70
+ }): Promise<Readonly<{
71
+ status: 'busy' | 'in-progress' | 'recovery-required';
72
+ }> | {
73
+ retainedClientAssets?: undefined;
74
+ release?: undefined;
75
+ status: 'unsupported';
76
+ resume?: undefined;
77
+ } | {
78
+ status: 'ready';
79
+ resume: UpdateResumeResult;
80
+ retainedClientAssets: readonly [];
81
+ release: () => Promise<void>;
82
+ } | {
83
+ status: 'ready';
84
+ resume: UpdateResumeResult;
85
+ retainedClientAssets: {
86
+ root: string;
87
+ immutableAssets: ReadonlyMap<string, string>;
88
+ }[];
89
+ release: () => Promise<void>;
90
+ }>;
31
91
  /** Each channel's signed descriptor for `platform`, as the release workflows publish them. */
32
92
  export declare function discoveryNames(platform: InstallerPlatform): Record<UpdateChannel, string>;
33
93
  /**
@@ -46,6 +106,8 @@ export type UpdateInstallRequest = {
46
106
  approved: boolean;
47
107
  restart?: boolean;
48
108
  };
109
+ export type { UpdateHealthAcknowledgement } from './update-retirement';
110
+ export type { UpdateShutdownTiming } from './update-shutdown';
49
111
  export type UpdaterOptions = {
50
112
  appName: string;
51
113
  repository: string;
@@ -61,6 +123,10 @@ export type UpdaterOptions = {
61
123
  abortDownload?(): void;
62
124
  /** Whether staging is still waiting before the desktop stage callback starts. */
63
125
  canCancelStaging?(): boolean;
126
+ /** Host-only query for an exact installed generation awaiting app-owned health checks. */
127
+ pendingHealthAcknowledgement?(): Promise<UpdateHealthAcknowledgement | null>;
128
+ /** Explicit host call after the application has completed its own readiness checks. */
129
+ acknowledgeHealthy?(acknowledgement: UpdateHealthAcknowledgement): Promise<void>;
64
130
  };
65
131
  /** The update commands over a framework channel update manager. */
66
132
  export declare function createUpdater(options: UpdaterOptions): {
@@ -70,6 +136,8 @@ export declare function createUpdater(options: UpdaterOptions): {
70
136
  saveChannel(channel: UpdateChannel): Promise<UpdateChannel>;
71
137
  install(request: UpdateInstallRequest): Promise<DesktopUpdateStatus>;
72
138
  cancel(): Promise<DesktopUpdateStatus>;
139
+ pendingHealthAcknowledgement(): Promise<UpdateHealthAcknowledgement | null>;
140
+ acknowledgeHealthy(acknowledgement: UpdateHealthAcknowledgement): Promise<void>;
73
141
  };
74
142
  export type DesktopUpdater = ReturnType<typeof createUpdater>;
75
143
  /**
@@ -89,7 +157,16 @@ export declare function createDesktopUpdater(options: {
89
157
  /** The shipped update helper, relative to `Resources/app`. */
90
158
  helperScript: string;
91
159
  checkWhenIdle?: boolean;
92
- quit(): void;
160
+ /** A startup result already reconciled under trusted retained-generation leases. */
161
+ startup?: Readonly<{
162
+ savedChannel: UpdateChannel;
163
+ resume: UpdateResumeResult;
164
+ }>;
165
+ /** Pause asset admission and await in-flight responses after arming the helper. */
166
+ prepareQuit?(timing: UpdateShutdownTiming): void | Promise<void>;
167
+ /** Reopen asset admission after helper cancellation has cleared its launch gate. */
168
+ abortPreparedQuit?(): void | Promise<void>;
169
+ quit(timing?: UpdateShutdownTiming): void | Promise<void>;
93
170
  log(line: string): void;
94
171
  }): Promise<DesktopUpdater>;
95
172
  type Services<Principal> = ReturnType<typeof createServiceRegistry<Principal>>;
@@ -103,4 +180,3 @@ export declare function registerUpdateServices<Principal>(options: {
103
180
  updater: DesktopUpdater;
104
181
  authorize(principal: Principal): boolean;
105
182
  }): () => void;
106
- export {};
@@ -1,16 +1,19 @@
1
1
  import { ServiceError } from "../app/service-registry.js";
2
2
  import { feedUrl, parseReleaseFeed } from "./release-feed.js";
3
3
  import { isUpdateChannel } from "./release-version.js";
4
+ import { acknowledgeRetiredUpdateHealthy, acquireRetainedUpdateTrees, findPendingUpdateHealthAcknowledgement } from "./update-retirement.js";
4
5
  import { stageUpdateSwap } from "./update-swap-stage.js";
5
6
  import { downloadVerifiedRelease } from "./update-download.js";
6
- import { discardOwnedUpdateDownload } from "./update-download-cleanup.js";
7
- import { createUpdateChannelStore } from "./update-channel-store.js";
7
+ import { completeOwnedUpdateDownload, createOwnedUpdateDownload, initializeOwnedUpdateDownloadRoot } from "./update-download-cleanup.js";
8
+ import { UpdatePreflightError } from "./update-preflight-error.js";
9
+ import { createUpdateChannelStore, releaseChannelForUpdate } from "./update-channel-store.js";
8
10
  import { createChannelUpdateManager } from "./channel-update-manager.js";
11
+ import { UpdateCleanupPendingError, findUpdateCleanupTerminalError } from "./update-cleanup-error.js";
9
12
  import { armUpdateHelper } from "./update-arm.js";
10
- import { resumeUpdate } from "./update-resume.js";
13
+ import { resumeUpdate, resumeUpdateWithRetainedTrees } from "./update-resume.js";
11
14
  import { scheduleUpdateShutdown } from "./update-shutdown.js";
12
- import { mkdir, realpath, rm } from "node:fs/promises";
13
- import { join, resolve } from "node:path";
15
+ import { lstat, mkdir, readlink, realpath } from "node:fs/promises";
16
+ import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
14
17
  // src/updates/desktop-updater.ts
15
18
  /**
16
19
  * The desktop host's signed updater, the same for every framework app: the
@@ -28,6 +31,8 @@ var MAX_DOWNLOAD_BYTES = 1073741824;
28
31
  var MAX_EXPANDED_BYTES = 4294967296;
29
32
  /** Lets the install reply reach the window before the app quits. */
30
33
  var QUIT_DELAY_MS = 250;
34
+ /** Allows a just-relaunched app to wait briefly for its detached updater helper to exit. */
35
+ var HEALTH_ACK_HELPER_WAIT_MS = 5e3;
31
36
  /** The release platform this host runs on, or null where framework apps ship no build. */
32
37
  function updatePlatform(platform = process.platform, arch = process.arch) {
33
38
  if (platform === "darwin" && arch === "arm64") return "macos-arm64";
@@ -51,6 +56,119 @@ function installTarget(entryDirectory, platform) {
51
56
  ".."
52
57
  ]);
53
58
  }
59
+ /** Preserve interrupted-swap recovery when the installed target is temporarily absent. */
60
+ async function canonicalTargetForRecovery(target, seen = /* @__PURE__ */ new Set()) {
61
+ if (seen.has(target) || seen.size >= 16) throw new Error("Invalid install target symlink chain");
62
+ seen.add(target);
63
+ try {
64
+ return await realpath(target);
65
+ } catch (error) {
66
+ if (error.code !== "ENOENT") throw error;
67
+ const info = await lstat(target).then((value) => value, (statError) => {
68
+ if (statError.code === "ENOENT") return void 0;
69
+ throw statError;
70
+ });
71
+ if (info?.isSymbolicLink()) return canonicalTargetForRecovery(resolve(dirname(target), await readlink(target)), seen);
72
+ if (info) throw error;
73
+ return join(await realpath(dirname(target)), basename(target));
74
+ }
75
+ }
76
+ /**
77
+ * Acquire the updater's retained generations and map their packaged client
78
+ * directories to manifests. The caller must already hold any required native
79
+ * launch admission lease and must retain the returned generation leases until
80
+ * the host and all response bodies are drained. This does not gate startup.
81
+ * `loadManifest` receives a retained client root while its lease is held.
82
+ */
83
+ async function acquireRetainedDesktopClientAssets(options) {
84
+ const platform = updatePlatform();
85
+ if (!platform) return { status: "unsupported" };
86
+ if (typeof options.entryDirectory !== "string" || !isAbsolute(options.entryDirectory) || resolve(options.entryDirectory) !== options.entryDirectory || typeof options.loadManifest !== "function") throw new Error("Invalid packaged client asset lookup");
87
+ const lexicalTarget = installTarget(options.entryDirectory, platform);
88
+ const clientRelative = relative(lexicalTarget, resolve(options.entryDirectory, "..", "client"));
89
+ if (clientRelative !== join(...platform === "macos-arm64" ? ["Contents"] : [], "Resources", "app", "client")) throw new Error("Invalid packaged client asset layout");
90
+ const target = await realpath(lexicalTarget);
91
+ const retained = await acquireRetainedUpdateTrees({
92
+ target,
93
+ currentVersion: options.currentVersion
94
+ });
95
+ if (retained.status !== "acquired") return retained;
96
+ try {
97
+ const retainedClientAssets = [];
98
+ for (const tree of retained.trees) {
99
+ const root = join(tree.tree, clientRelative);
100
+ retainedClientAssets.push({
101
+ root,
102
+ immutableAssets: await options.loadManifest(root)
103
+ });
104
+ }
105
+ return {
106
+ status: "acquired",
107
+ retainedClientAssets,
108
+ release: retained.release
109
+ };
110
+ } catch (error) {
111
+ try {
112
+ await retained.release();
113
+ } catch (releaseError) {
114
+ throw new AggregateError([error, releaseError], "Retained client asset preparation failed", { cause: releaseError });
115
+ }
116
+ throw error;
117
+ }
118
+ }
119
+ /**
120
+ * Trusted startup variant for callers that must preserve normal pending staged
121
+ * updates while pinning retained generations. Resume and lease acquisition are
122
+ * serialized under the install lock; callers keep the returned lease through
123
+ * host shutdown and response draining.
124
+ */
125
+ async function resumeAndAcquireRetainedDesktopClientAssets(options) {
126
+ const platform = updatePlatform();
127
+ if (!platform) return { status: "unsupported" };
128
+ if (typeof options.entryDirectory !== "string" || !isAbsolute(options.entryDirectory) || resolve(options.entryDirectory) !== options.entryDirectory || typeof options.loadManifest !== "function") throw new Error("Invalid packaged client asset lookup");
129
+ const lexicalTarget = installTarget(options.entryDirectory, platform);
130
+ const clientRelative = relative(lexicalTarget, resolve(options.entryDirectory, "..", "client"));
131
+ if (clientRelative !== join(...platform === "macos-arm64" ? ["Contents"] : [], "Resources", "app", "client")) throw new Error("Invalid packaged client asset layout");
132
+ const target = await realpath(lexicalTarget);
133
+ const result = await resumeUpdateWithRetainedTrees({
134
+ target,
135
+ trust: options.trust,
136
+ currentVersion: options.currentVersion
137
+ });
138
+ if (result.status !== "ready") return result;
139
+ if (result.retained.status !== "acquired") {
140
+ if (result.retained.status === "busy") return { status: "busy" };
141
+ return {
142
+ status: "ready",
143
+ resume: result.resume,
144
+ retainedClientAssets: [],
145
+ release: async () => {}
146
+ };
147
+ }
148
+ try {
149
+ const retainedClientAssets = [];
150
+ for (const tree of result.retained.trees) {
151
+ const root = join(tree.tree, clientRelative);
152
+ retainedClientAssets.push({
153
+ root,
154
+ immutableAssets: await options.loadManifest(root)
155
+ });
156
+ }
157
+ return {
158
+ status: "ready",
159
+ resume: result.resume,
160
+ retainedClientAssets,
161
+ release: result.retained.release
162
+ };
163
+ } catch (error) {
164
+ try {
165
+ await result.retained.release();
166
+ } catch (releaseError) {
167
+ throw new AggregateError([error, releaseError], "Retained client asset preparation failed", { cause: releaseError });
168
+ }
169
+ throw error;
170
+ }
171
+ }
54
172
  /** Each channel's signed descriptor for `platform`, as the release workflows publish them. */
55
173
  function discoveryNames(platform) {
56
174
  return {
@@ -97,6 +215,48 @@ function createUpdater(options) {
97
215
  const releases = `https://github.com/${options.repository}/releases`;
98
216
  let cancelRequested = false;
99
217
  let lastTag = null;
218
+ let pendingRestartCleanup;
219
+ let lastRestartFailure;
220
+ let restartInFlight;
221
+ const retryPendingRestartCleanup = async () => {
222
+ if (restartInFlight) try {
223
+ await restartInFlight;
224
+ } catch (error) {
225
+ if (!(error instanceof UpdateCleanupPendingError)) throw error;
226
+ }
227
+ const retry = pendingRestartCleanup;
228
+ if (!retry) return;
229
+ try {
230
+ await retry.retryCleanup();
231
+ } catch (error) {
232
+ const terminal = findUpdateCleanupTerminalError(error);
233
+ if (!terminal) throw error;
234
+ lastRestartFailure = terminal.message;
235
+ if (pendingRestartCleanup === retry) pendingRestartCleanup = void 0;
236
+ return;
237
+ }
238
+ if (pendingRestartCleanup === retry) pendingRestartCleanup = void 0;
239
+ if (retry.terminalError) lastRestartFailure = retry.terminalError.message;
240
+ };
241
+ const restart = async (version) => {
242
+ if (restartInFlight) return restartInFlight;
243
+ const operation = (async () => {
244
+ try {
245
+ await options.restart(version);
246
+ lastRestartFailure = void 0;
247
+ } catch (error) {
248
+ if (error instanceof UpdateCleanupPendingError) pendingRestartCleanup = error;
249
+ const terminal = findUpdateCleanupTerminalError(error);
250
+ if (terminal) lastRestartFailure = terminal.message;
251
+ throw error;
252
+ }
253
+ })();
254
+ restartInFlight = operation;
255
+ operation.finally(() => {
256
+ if (restartInFlight === operation) restartInFlight = void 0;
257
+ }).catch(() => {});
258
+ return operation;
259
+ };
100
260
  let inFlight = null;
101
261
  const snapshot = () => {
102
262
  const state = manager?.status();
@@ -113,7 +273,7 @@ function createUpdater(options) {
113
273
  phase,
114
274
  downloaded_bytes: 0,
115
275
  total_bytes: null,
116
- error: phase === "cancelled" ? null : state?.error ?? null,
276
+ error: pendingRestartCleanup ? pendingRestartCleanup.stage === "quit-approval-release" ? "Update quit approval release is pending; use cancel to retry it safely." : pendingRestartCleanup.stage === "quit-preparation-resume" ? "Update shutdown recovery is pending; use cancel to retry it safely." : "Update helper cleanup is pending; use cancel to retry it safely." : lastRestartFailure ? `Update restart failed: ${lastRestartFailure}` : phase === "cancelled" ? null : state?.error ?? null,
117
277
  restart_required: state?.phase === "staged"
118
278
  };
119
279
  };
@@ -142,23 +302,42 @@ function createUpdater(options) {
142
302
  return active().saveChannel(channel);
143
303
  },
144
304
  async install(request) {
145
- const updates = active();
146
305
  if (!request.approved) throw new ServiceError("command_failed", "update installation requires explicit approval");
306
+ await retryPendingRestartCleanup();
307
+ const updates = active();
147
308
  cancelRequested = false;
309
+ const staged = updates.status();
310
+ if (staged.phase === "staged") {
311
+ if (!staged.availableVersion || request.expectedVersion !== staged.availableVersion) throw new ServiceError("command_failed", "Update approval does not match the staged version");
312
+ if (request.restart !== false) await restart(staged.availableVersion);
313
+ return snapshot();
314
+ }
148
315
  const state = await updates.install({
149
316
  approved: true,
150
317
  expectedVersion: request.expectedVersion
151
318
  });
152
- if (state.phase === "staged" && request.restart !== false && state.availableVersion) await options.restart(state.availableVersion);
319
+ if (state.phase === "staged" && request.restart !== false && state.availableVersion) await restart(state.availableVersion);
153
320
  return snapshot();
154
321
  },
155
322
  async cancel() {
323
+ if (pendingRestartCleanup) {
324
+ await retryPendingRestartCleanup();
325
+ return snapshot();
326
+ }
156
327
  const phase = manager?.status().phase;
157
328
  if (!cancelRequested && options.abortDownload && (phase === "downloading" || phase === "staging" && options.canCancelStaging?.() === true)) {
158
329
  cancelRequested = true;
159
330
  options.abortDownload();
160
331
  }
161
332
  return snapshot();
333
+ },
334
+ async pendingHealthAcknowledgement() {
335
+ if (!options.pendingHealthAcknowledgement) throw new ServiceError("unsupported", "Update health acknowledgement is unavailable");
336
+ return options.pendingHealthAcknowledgement();
337
+ },
338
+ async acknowledgeHealthy(acknowledgement) {
339
+ if (!options.acknowledgeHealthy) throw new ServiceError("unsupported", "Update health acknowledgement is unavailable");
340
+ return options.acknowledgeHealthy(acknowledgement);
162
341
  }
163
342
  };
164
343
  }
@@ -167,6 +346,7 @@ function createUpdater(options) {
167
346
  * by an earlier run and reports what an earlier helper did.
168
347
  */
169
348
  async function createDesktopUpdater(options) {
349
+ if (Boolean(options.prepareQuit) !== Boolean(options.abortPreparedQuit)) throw new Error("Packaged update quit preparation requires a recovery callback");
170
350
  const { release } = options;
171
351
  const platform = updatePlatform();
172
352
  const trust = platform && updateTrust(platform, {
@@ -197,50 +377,101 @@ async function createDesktopUpdater(options) {
197
377
  manager: null,
198
378
  restart: async () => {}
199
379
  });
200
- const target = installTarget(options.entryDirectory, platform);
201
- const resumed = await resumeUpdate({ target }).catch((error) => {
202
- options.log(`update resume failed: ${String(error)}`);
203
- return null;
204
- });
205
- if (resumed?.status === "updated") options.log(`updated to ${release.appName} ${resumed.version}`);
206
- const state = options.stateDirectory ?? options.dataDirectory;
207
- await mkdir(state, {
380
+ const target = await canonicalTargetForRecovery(installTarget(options.entryDirectory, platform));
381
+ const stateDirectory = options.stateDirectory ?? options.dataDirectory;
382
+ await mkdir(stateDirectory, {
208
383
  recursive: true,
209
384
  mode: 448
210
385
  });
211
- const downloads = join(options.dataDirectory, "updates");
212
- await rm(downloads, {
213
- recursive: true,
214
- force: true
386
+ const channelStore = createUpdateChannelStore(await realpath(stateDirectory));
387
+ const storedChannel = options.startup ? options.startup.savedChannel : await channelStore.read().catch((error) => {
388
+ options.log(`update channel read failed: ${String(error)}`);
389
+ return null;
215
390
  });
216
- await mkdir(downloads, {
391
+ const selectedChannel = storedChannel ? releaseChannelForUpdate(storedChannel) : null;
392
+ const resumed = options.startup ? options.startup.resume : selectedChannel ? await resumeUpdate({
393
+ target,
394
+ trust: {
395
+ ...trust,
396
+ channel: selectedChannel
397
+ },
398
+ currentVersion: options.currentVersion
399
+ }).catch((error) => {
400
+ options.log(`update resume failed: ${String(error)}`);
401
+ return null;
402
+ }) : null;
403
+ if (resumed?.status === "updated") options.log(`updated to ${release.appName} ${resumed.version}`);
404
+ if (resumed?.status === "staged") options.log(`a staged ${release.appName} update ${resumed.version} is waiting to be installed`);
405
+ if (resumed?.status === "recovery-required") options.log("an older update staging directory needs manual recovery; it was preserved");
406
+ let recoveryPending = resumed === null || resumed.status === "in-progress" || resumed.status === "recovery-required";
407
+ await mkdir(options.dataDirectory, {
217
408
  recursive: true,
218
409
  mode: 448
219
410
  });
220
- const downloadsRoot = await realpath(downloads);
411
+ const dataDirectory = await realpath(options.dataDirectory);
412
+ const downloadsRoot = await initializeOwnedUpdateDownloadRoot(join(dataDirectory, "updates-v2"));
413
+ const downloadLeases = /* @__PURE__ */ new Map();
221
414
  const manager = createChannelUpdateManager({
222
- store: createUpdateChannelStore(await realpath(state)),
415
+ store: channelStore,
223
416
  trust,
224
417
  discoveryNames: discoveryNames(platform),
225
418
  currentVersion: options.currentVersion,
226
419
  directory: downloadsRoot,
227
420
  maxBytes: MAX_DOWNLOAD_BYTES,
228
- download(input) {
421
+ ...resumed?.status === "staged" ? { stagedVersion: resumed.version } : storedChannel === null || resumed === null || resumed.status === "in-progress" || resumed.status === "recovery-required" ? { recoveryError: storedChannel === null ? "The saved update channel could not be read. Update recovery is paused." : "A previous update could not be safely resumed. Its staging data was preserved." } : {},
422
+ async beforeDownload() {
423
+ if (!recoveryPending) return;
424
+ const channel = releaseChannelForUpdate(await channelStore.read());
425
+ const recovered = await resumeUpdate({
426
+ target,
427
+ trust: {
428
+ ...trust,
429
+ channel
430
+ },
431
+ currentVersion: options.currentVersion
432
+ });
433
+ if (recovered.status === "in-progress") throw new UpdatePreflightError("previous-update-in-progress");
434
+ if (recovered.status === "staged") throw new UpdatePreflightError("previous-update-staged");
435
+ if (recovered.status === "recovery-required") throw new UpdatePreflightError("recovery-required");
436
+ recoveryPending = false;
437
+ },
438
+ async download(input) {
229
439
  const cancellation = controller.signal;
230
440
  const signal = input.signal ? AbortSignal.any([input.signal, cancellation]) : cancellation;
231
441
  downloadSignal = signal;
232
442
  stageStarted = false;
233
- return downloadVerifiedRelease({
234
- ...input,
235
- signal
236
- });
443
+ let ownedDirectory;
444
+ try {
445
+ return await downloadVerifiedRelease({
446
+ ...input,
447
+ signal,
448
+ async createTemporaryDirectory(root) {
449
+ const owned = await createOwnedUpdateDownload(root);
450
+ ownedDirectory = owned.directory;
451
+ downloadLeases.set(owned.directory, owned.lease);
452
+ return owned.directory;
453
+ }
454
+ });
455
+ } catch (error) {
456
+ if (ownedDirectory) {
457
+ const lease = downloadLeases.get(ownedDirectory);
458
+ if (lease) {
459
+ downloadLeases.delete(ownedDirectory);
460
+ await completeOwnedUpdateDownload(downloadsRoot, ownedDirectory, lease).catch(() => {});
461
+ }
462
+ }
463
+ throw error;
464
+ }
237
465
  },
238
466
  fetch: (input, init) => fetch(input, {
239
467
  ...init,
240
468
  signal: init?.signal ? AbortSignal.any([init.signal, controller.signal]) : controller.signal
241
469
  }),
242
470
  async discardDownload({ directory }) {
243
- await discardOwnedUpdateDownload(downloadsRoot, directory);
471
+ const lease = downloadLeases.get(directory);
472
+ if (!lease) throw new Error("Update download ownership is unavailable");
473
+ downloadLeases.delete(directory);
474
+ await completeOwnedUpdateDownload(downloadsRoot, directory, lease);
244
475
  },
245
476
  async stage({ descriptor, path, directory }) {
246
477
  try {
@@ -266,10 +497,11 @@ async function createDesktopUpdater(options) {
266
497
  });
267
498
  } finally {
268
499
  try {
269
- await rm(directory, {
270
- recursive: true,
271
- force: true
272
- });
500
+ const lease = downloadLeases.get(directory);
501
+ if (lease) {
502
+ downloadLeases.delete(directory);
503
+ await completeOwnedUpdateDownload(downloadsRoot, directory, lease);
504
+ }
273
505
  } finally {
274
506
  downloadSignal = void 0;
275
507
  stageStarted = false;
@@ -280,18 +512,69 @@ async function createDesktopUpdater(options) {
280
512
  return createUpdater({
281
513
  ...updater,
282
514
  manager,
515
+ async pendingHealthAcknowledgement() {
516
+ let channel = selectedChannel;
517
+ try {
518
+ channel = releaseChannelForUpdate(await channelStore.read());
519
+ } catch (error) {
520
+ options.log(`update channel read failed during health recovery: ${String(error)}`);
521
+ }
522
+ if (channel) {
523
+ const deadline = Date.now() + HEALTH_ACK_HELPER_WAIT_MS;
524
+ for (;;) {
525
+ if ((await resumeUpdate({
526
+ target,
527
+ trust: {
528
+ ...trust,
529
+ channel
530
+ },
531
+ currentVersion: options.currentVersion
532
+ }).catch((error) => {
533
+ options.log(`update resume failed during health recovery: ${String(error)}`);
534
+ return null;
535
+ }))?.status !== "in-progress") break;
536
+ const remaining = deadline - Date.now();
537
+ if (remaining <= 0) {
538
+ options.log("update helper remains active; health acknowledgement is deferred");
539
+ break;
540
+ }
541
+ await Bun.sleep(Math.min(50, remaining));
542
+ }
543
+ }
544
+ return findPendingUpdateHealthAcknowledgement({
545
+ target,
546
+ currentVersion: options.currentVersion
547
+ });
548
+ },
549
+ acknowledgeHealthy: (acknowledgement) => acknowledgeRetiredUpdateHealthy({
550
+ target,
551
+ acknowledgement
552
+ }),
283
553
  async restart(version) {
284
554
  await scheduleUpdateShutdown({
285
555
  reserve: () => ({}),
286
556
  cancelReservation: () => {},
287
- arm: () => armUpdateHelper({
557
+ arm: async () => armUpdateHelper({
288
558
  target,
289
559
  platform,
290
560
  version,
561
+ currentVersion: options.currentVersion,
562
+ trust: {
563
+ ...trust,
564
+ channel: releaseChannelForUpdate(await channelStore.read())
565
+ },
291
566
  helperScript: join(options.entryDirectory, "..", options.helperScript)
292
567
  }),
293
- quit: () => {
294
- setTimeout(options.quit, QUIT_DELAY_MS);
568
+ ...options.prepareQuit ? {
569
+ prepareQuit: (_token, timing) => {
570
+ if (!timing) throw new Error("Armed helper did not provide its process deadline");
571
+ return options.prepareQuit(timing);
572
+ },
573
+ abortPreparedQuit: () => options.abortPreparedQuit()
574
+ } : {},
575
+ quit: async (_token, timing) => {
576
+ await new Promise((done) => setTimeout(done, QUIT_DELAY_MS));
577
+ await options.quit(timing);
295
578
  return true;
296
579
  }
297
580
  });
@@ -371,4 +654,4 @@ function registerUpdateServices(options) {
371
654
  for (const remove of unregister) remove();
372
655
  };
373
656
  }
374
- export { createDesktopUpdater, createUpdater, discoveryNames, installTarget, parseUpdateChannel, parseUpdateInstall, registerUpdateServices, updatePlatform, updateTrust };
657
+ export { acquireRetainedDesktopClientAssets, createDesktopUpdater, createUpdater, discoveryNames, installTarget, parseUpdateChannel, parseUpdateInstall, registerUpdateServices, resumeAndAcquireRetainedDesktopClientAssets, updatePlatform, updateTrust };
@@ -0,0 +1,2 @@
1
+ /** Set only by a launcher that passes its locked POSIX descriptor to the app. */
2
+ export declare const INHERITED_LAUNCH_LEASE_ENV = "ADEA_INHERITED_LAUNCH_LEASE_FD";
@@ -0,0 +1,4 @@
1
+ // src/updates/launch-environment.ts
2
+ /** Set only by a launcher that passes its locked POSIX descriptor to the app. */
3
+ var INHERITED_LAUNCH_LEASE_ENV = "ADEA_INHERITED_LAUNCH_LEASE_FD";
4
+ export { INHERITED_LAUNCH_LEASE_ENV };
@@ -0,0 +1,15 @@
1
+ type LockMode = 'shared' | 'exclusive';
2
+ export type NativeFileLock = Readonly<{
3
+ release(): Promise<void>;
4
+ }>;
5
+ /**
6
+ * Try to lock a persistent file without waiting. undefined means another
7
+ * process owns an incompatible lock; unsupported platforms and native errors
8
+ * reject so callers cannot mistake a failed lock for a successful one.
9
+ *
10
+ * The path must remain stable and the file must not be removed or replaced.
11
+ */
12
+ export declare function tryAcquireNativeFileLock(path: string, mode: LockMode): Promise<NativeFileLock | undefined>;
13
+ /** Ensure an inherited descriptor currently holds a nonblocking shared lock. */
14
+ export declare function tryLockInheritedSharedFileDescriptor(fd: number): boolean;
15
+ export {};