@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
@@ -1,14 +1,21 @@
1
- import { updateStagingFor } from "./update-swap.js";
1
+ import { verifyReleaseDescriptor } from "./signed-release.js";
2
+ import { acquireUpdateLock, readUpdateStageState, writeUpdateStageState } from "./update-state-store.js";
3
+ import { readUpdateTreeDigest, readUpdateTreeIdentity, sameUpdateTreeDigest, sameUpdateTreeIdentity, updateStagingFor } from "./update-swap.js";
4
+ import { isUpdateHelperReadyMarker, readUpdateMarker } from "./update-marker.js";
2
5
  import { updateLauncherPath } from "./update-launch.js";
3
- import { copyFile, lstat, mkdir, readFile, realpath, rm, unlink, writeFile } from "node:fs/promises";
6
+ import { publishUpdateLaunchGateCancellationRequest, readUpdateLaunchGate } from "./update-launch-gate.js";
7
+ import { hasUpdateHelperArtifacts, parseUpdateHelperRequest } from "./update-helper.js";
8
+ import { UpdateCleanupPendingError, UpdateCleanupTerminalError } from "./update-cleanup-error.js";
9
+ import { copyFile, lstat, mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
4
10
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
5
11
  import { spawn } from "node:child_process";
12
+ import { randomUUID } from "node:crypto";
6
13
  // src/updates/update-arm.ts
7
14
  function exited(child) {
8
- return child.exitCode !== null || child.signalCode !== null;
15
+ return child.pid === void 0 || child.exitCode !== null || child.signalCode !== null;
9
16
  }
10
17
  function waitForExit(child, timeoutMs) {
11
- if (exited(child) || child.pid === void 0) return Promise.resolve(true);
18
+ if (exited(child)) return Promise.resolve(true);
12
19
  return new Promise((resolveExit) => {
13
20
  let timer;
14
21
  let settled = false;
@@ -32,92 +39,199 @@ function updateRuntimePath(platform, target) {
32
39
  }
33
40
  /**
34
41
  * Start the post-exit update helper for a staged update, then resolve once the
35
- * helper has verified this app's processes. The helper runs from copies of the
36
- * app's Bun runtime and bundled helper script inside the private staging
37
- * directory, because the install tree is about to move.
38
- *
39
- * Use it as the `arm` step of `scheduleUpdateShutdown`: quit only after it
40
- * resolves, and call `cancel()` if the quit is vetoed.
42
+ * helper has verified the requested processes and published readiness for
43
+ * this helper owner and generation. The helper runs from copied app files
44
+ * because the install tree is about to move.
41
45
  */
42
46
  async function armUpdateHelper(options) {
43
47
  const staging = updateStagingFor(options.target);
44
48
  if (!isAbsolute(options.helperScript) || resolve(options.helperScript) !== options.helperScript) throw new Error("Invalid update helper script");
45
49
  const info = await lstat(staging);
46
50
  if (!info.isDirectory() || info.isSymbolicLink() || await realpath(staging) !== staging) throw new Error("Invalid update staging directory");
47
- const helper = join(staging, "helper");
48
- const runtime = join(helper, basename(updateRuntimePath(options.platform, options.target)));
49
- const script = join(helper, "update-helper.js");
50
- const request = {
51
- schema: 1,
52
- target: options.target,
53
- platform: options.platform,
54
- version: options.version,
55
- processes: options.processes ?? [{
56
- pid: process.pid,
57
- executable: process.execPath
58
- }, ...process.ppid > 1 ? [{
59
- pid: process.ppid,
60
- executable: updateLauncherPath(options.platform, options.target)
61
- }] : []],
62
- processTimeoutMs: options.processTimeoutMs ?? 3e4
63
- };
64
- const armed = join(staging, "helper-armed");
65
51
  let child;
66
- let helperCreated = false;
67
- let requestCreated = false;
52
+ let generation;
53
+ let helperOwner;
68
54
  let resetCompleted = false;
55
+ let resetOwnershipConfirmed = false;
69
56
  let resetInProgress;
57
+ let processDeadline;
70
58
  async function performReset() {
71
- if (child && !exited(child) && child.pid !== void 0) {
72
- try {
73
- process.kill(child.pid);
74
- } catch (error) {
75
- if (error.code !== "ESRCH") throw new Error("Update helper could not be stopped; recovery state was preserved", { cause: error });
59
+ if (!generation || resetCompleted) return;
60
+ let cancellationRequested = false;
61
+ let helperBoundFromStaged = false;
62
+ if (child?.pid !== void 0 && !exited(child)) {
63
+ if (!helperOwner) throw new Error("Update helper cancellation owner is unavailable");
64
+ if ((await readUpdateStageState(staging))?.phase === "staged") {
65
+ const bindLock = await acquireUpdateLock(options.target);
66
+ try {
67
+ const current = await readUpdateStageState(staging);
68
+ if (!current || current.generation !== generation) throw new Error("Update cancellation no longer owns this staging generation");
69
+ if (current.phase === "staged") {
70
+ const request = parseUpdateHelperRequest(JSON.parse(await readFile(join(staging, "request.json"), "utf8")));
71
+ if (request.generation !== generation || request.helperOwner !== helperOwner || current.helperPid !== void 0 && current.helperPid !== child.pid || current.helperOwner !== void 0 && current.helperOwner !== helperOwner) throw new Error("Another helper owns this staging generation");
72
+ helperBoundFromStaged = true;
73
+ if (!exited(child)) await writeUpdateStageState(staging, {
74
+ ...current,
75
+ phase: "armed",
76
+ helperPid: child.pid,
77
+ helperOwner
78
+ });
79
+ } else if (current.phase !== "armed" || current.helperPid !== child.pid || current.helperOwner !== helperOwner) throw new Error(`Update cancellation cannot clean a ${current.phase} generation`);
80
+ } finally {
81
+ await bindLock.release();
82
+ }
83
+ }
84
+ const existingCancellation = helperBoundFromStaged ? await readUpdateMarker(staging, "cancel.json") : void 0;
85
+ if (!(helperBoundFromStaged && exited(child) && existingCancellation === void 0)) {
86
+ const matchingRequest = await publishUpdateLaunchGateCancellationRequest(options.target, staging, generation, helperOwner);
87
+ if (!await waitForExit(child, options.cancelTimeoutMs ?? 1e4)) throw new Error("Update helper did not exit after cancellation; recovery state was preserved");
88
+ if (!matchingRequest) throw new Error("Update helper exited without a matching cancellation request");
89
+ cancellationRequested = true;
76
90
  }
77
- if (!await waitForExit(child, options.cancelTimeoutMs ?? 1e4)) throw new Error("Update helper did not exit after cancellation; recovery state was preserved");
78
91
  }
79
- let marker;
80
- if (child?.pid !== void 0) {
92
+ const lock = await acquireUpdateLock(options.target);
93
+ try {
94
+ let current = await readUpdateStageState(staging);
95
+ if (!current || current.generation !== generation) throw new Error("Update cancellation no longer owns this staging generation");
96
+ if (current.phase !== "armed" && current.phase !== "staged") throw new UpdateCleanupTerminalError(`Update cancellation cannot clean a ${current.phase} generation; recovery is required`);
97
+ if (current.phase === "armed") {
98
+ if (!child || child.pid === void 0 || current.helperPid !== child.pid || !helperOwner || current.helperOwner !== helperOwner) throw new Error("Another helper owns this staging generation");
99
+ if (child.pid !== void 0 && !exited(child)) throw new Error("Update helper is still running during cancellation cleanup");
100
+ }
101
+ const requestPath = join(staging, "request.json");
102
+ let request;
81
103
  try {
82
- marker = await readFile(armed, "utf8");
104
+ request = parseUpdateHelperRequest(JSON.parse(await readFile(requestPath, "utf8")));
83
105
  } catch (error) {
84
- if (error.code !== "ENOENT") throw new Error("Update helper ownership could not be verified; recovery state was preserved", { cause: error });
106
+ if (error.code !== "ENOENT") throw error;
107
+ }
108
+ if (request && (request.schema !== 2 && request.schema !== 3 || request.generation !== generation || request.helperOwner !== helperOwner)) throw new Error("Another helper owns this staging generation");
109
+ if (child?.pid !== void 0) {
110
+ if (!helperOwner || !exited(child)) throw new Error("Update helper is still running during cancellation cleanup");
111
+ if (current.helperPid !== void 0 && current.helperPid !== child.pid || current.helperOwner !== void 0 && current.helperOwner !== helperOwner) throw new Error("Another helper owns this staging generation");
112
+ if (!resetOwnershipConfirmed && (current.phase === "armed" && !(helperBoundFromStaged && !cancellationRequested) || cancellationRequested)) {
113
+ const schema3 = request?.schema === 3 || current.launchGateOwner !== void 0;
114
+ const proofFailure = (message, cause) => schema3 ? new UpdateCleanupTerminalError(`${message}; recovery is required`, cause === void 0 ? [] : [cause]) : cause === void 0 ? new Error(message) : new Error(message, { cause });
115
+ let acknowledgement;
116
+ try {
117
+ acknowledgement = await readUpdateMarker(staging, "cancel-ack.json");
118
+ } catch (error) {
119
+ throw proofFailure("Update helper cancellation acknowledgement could not be verified", error);
120
+ }
121
+ if (acknowledgement?.schema !== 1 || acknowledgement.generation !== generation || acknowledgement.helperOwner !== helperOwner) throw proofFailure("Update helper exited without acknowledging cancellation");
122
+ if (schema3) {
123
+ if (!current.launchGateOwner || acknowledgement.launchGateOwner !== current.launchGateOwner) throw proofFailure("Update helper cancellation did not acknowledge its exact launch gate");
124
+ let gate;
125
+ try {
126
+ gate = await readUpdateLaunchGate(options.target);
127
+ } catch (error) {
128
+ throw proofFailure("Update helper launch gate removal could not be verified", error);
129
+ }
130
+ if (gate !== void 0) throw proofFailure("Update helper cancellation did not clear its exact launch gate");
131
+ }
132
+ }
133
+ if (current.phase === "staged") {
134
+ current = {
135
+ ...current,
136
+ phase: "armed",
137
+ helperPid: child.pid,
138
+ helperOwner
139
+ };
140
+ await writeUpdateStageState(staging, current);
141
+ }
142
+ resetOwnershipConfirmed = true;
143
+ } else {
144
+ if (current.helperPid !== void 0) throw new Error("Another helper owns this staging generation");
145
+ if (current.helperOwner !== void 0 && current.helperOwner !== helperOwner) throw new Error("Another helper owns this staging generation");
146
+ if (helperOwner && current.helperOwner !== helperOwner) {
147
+ current = {
148
+ ...current,
149
+ helperOwner
150
+ };
151
+ await writeUpdateStageState(staging, current);
152
+ }
153
+ resetOwnershipConfirmed = true;
85
154
  }
86
- if (marker !== void 0 && marker.trim() !== String(child.pid)) throw new Error("Update helper ownership changed; recovery state was preserved");
155
+ const { helperPid: _helperPid, helperOwner: _helperOwner, launchGateOwner: _launchGateOwner, previousTreeIdentity: _previousTreeIdentity, ...recoverable } = current;
156
+ const staged = {
157
+ ...recoverable,
158
+ phase: "staged"
159
+ };
160
+ for (const name of [
161
+ "request.json",
162
+ "helper-armed",
163
+ "helper-ready",
164
+ "cancel.json",
165
+ "cancel-ack.json"
166
+ ]) await rm(join(staging, name), { force: true });
167
+ await rm(join(staging, "helper"), {
168
+ recursive: true,
169
+ force: true
170
+ });
171
+ await writeUpdateStageState(staging, staged);
172
+ resetCompleted = true;
173
+ } finally {
174
+ await lock.release();
87
175
  }
88
- if (requestCreated) await unlink(join(staging, "request.json")).catch(() => void 0);
89
- if (marker !== void 0) await unlink(armed).catch(() => void 0);
90
- if (helperCreated) await rm(helper, {
91
- recursive: true,
92
- force: true
93
- });
94
176
  }
95
177
  function reset() {
96
- if (resetCompleted) return Promise.resolve();
97
178
  if (resetInProgress) return resetInProgress;
98
- const attempt = performReset();
179
+ const attempt = performReset().catch((error) => {
180
+ if (!child || exited(child)) throw error;
181
+ throw new UpdateCleanupPendingError("Update helper cleanup is incomplete; retry through the retained cleanup handle", [error], reset);
182
+ });
99
183
  resetInProgress = attempt;
100
- attempt.then(() => {
101
- resetCompleted = true;
102
- }).finally(() => {
184
+ attempt.finally(() => {
103
185
  if (resetInProgress === attempt) resetInProgress = void 0;
104
186
  }).catch(() => {});
105
187
  return attempt;
106
188
  }
189
+ const lock = await acquireUpdateLock(options.target);
107
190
  try {
191
+ if (await readUpdateLaunchGate(options.target)) throw new Error("An earlier update launch gate requires recovery");
192
+ const state = await readUpdateStageState(staging);
193
+ const verified = state?.signedRelease ? verifyReleaseDescriptor(state.signedRelease, options.trust) : { ok: false };
194
+ if (!state || state.phase !== "staged" || state.helperPid !== void 0 || state.launchGateOwner !== void 0 || state.version !== options.version || state.previousVersion !== options.currentVersion || !state.candidateTreeIdentity || !state.candidateTreeDigest || !sameUpdateTreeIdentity(await readUpdateTreeIdentity(join(staging, "candidate")), state.candidateTreeIdentity) || !sameUpdateTreeDigest(await readUpdateTreeDigest(join(staging, "candidate")), state.candidateTreeDigest) || !verified.ok || verified.descriptor.version !== options.version) throw new Error("Update candidate is not staged for this version");
195
+ if (await hasUpdateHelperArtifacts(staging)) throw new Error("Update helper artifacts need recovery before a new handoff");
196
+ generation = state.generation;
197
+ helperOwner = randomUUID();
198
+ const helper = join(staging, "helper");
199
+ const runtime = join(helper, basename(updateRuntimePath(options.platform, options.target)));
200
+ const script = join(helper, "update-helper.js");
201
+ const request = {
202
+ schema: 3,
203
+ generation,
204
+ helperOwner,
205
+ target: options.target,
206
+ platform: options.platform,
207
+ version: options.version,
208
+ processes: options.processes ?? [{
209
+ pid: process.pid,
210
+ executable: process.execPath
211
+ }, ...process.ppid > 1 ? [{
212
+ pid: process.ppid,
213
+ executable: updateLauncherPath(options.platform, options.target)
214
+ }] : []],
215
+ processTimeoutMs: options.processTimeoutMs ?? 3e4
216
+ };
108
217
  await mkdir(helper, { mode: 448 });
109
- helperCreated = true;
110
218
  await copyFile(updateRuntimePath(options.platform, options.target), runtime);
111
219
  await copyFile(options.helperScript, script);
112
220
  await writeFile(join(staging, "request.json"), JSON.stringify(request) + "\n", {
113
221
  flag: "wx",
114
222
  mode: 384
115
223
  });
116
- requestCreated = true;
224
+ processDeadline = performance.now() + request.processTimeoutMs;
117
225
  const started = spawn(runtime, [
118
226
  script,
227
+ "--target",
228
+ options.target,
119
229
  "--staging",
120
- staging
230
+ staging,
231
+ "--generation",
232
+ generation,
233
+ "--owner",
234
+ helperOwner
121
235
  ], {
122
236
  cwd: helper,
123
237
  detached: true,
@@ -130,17 +244,68 @@ async function armUpdateHelper(options) {
130
244
  started.once("spawn", () => done());
131
245
  started.once("error", reject);
132
246
  });
133
- started.unref();
134
- const deadline = Date.now() + (options.armTimeoutMs ?? 15e3);
135
- while (!await lstat(armed).catch(() => void 0)) {
136
- if (exited(started)) throw new Error("Update helper exited before arming");
137
- if (Date.now() >= deadline) throw new Error("Update helper did not arm in time");
247
+ if (!started.pid) throw new Error("Update helper did not start");
248
+ await writeUpdateStageState(staging, {
249
+ ...state,
250
+ phase: "armed",
251
+ helperPid: started.pid,
252
+ helperOwner
253
+ });
254
+ } catch (error) {
255
+ let releaseError;
256
+ try {
257
+ await lock.release();
258
+ } catch (failedRelease) {
259
+ releaseError = failedRelease;
260
+ }
261
+ try {
262
+ await reset();
263
+ } catch (cleanupError) {
264
+ if (cleanupError instanceof UpdateCleanupPendingError) throw new UpdateCleanupPendingError("Update helper startup failed and cleanup is pending", [
265
+ error,
266
+ ...releaseError === void 0 ? [] : [releaseError],
267
+ cleanupError
268
+ ], () => cleanupError.retryCleanup());
269
+ throw new AggregateError([
270
+ error,
271
+ ...releaseError === void 0 ? [] : [releaseError],
272
+ cleanupError
273
+ ], "Update helper startup failed and could not be fully cleaned up", { cause: cleanupError });
274
+ }
275
+ if (releaseError !== void 0) throw new AggregateError([error, releaseError], "Update helper lock could not be released", { cause: error });
276
+ throw error;
277
+ }
278
+ await lock.release();
279
+ child.unref();
280
+ const deadline = performance.now() + (options.armTimeoutMs ?? 15e3);
281
+ try {
282
+ for (;;) {
283
+ const readiness = await readUpdateMarker(staging, "helper-ready");
284
+ if (readiness !== void 0) {
285
+ if (!isUpdateHelperReadyMarker(readiness, generation, helperOwner)) throw new Error("Update helper readiness marker does not match its owner");
286
+ const launchGateOwner = readiness.launchGateOwner;
287
+ if (typeof launchGateOwner !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(launchGateOwner)) throw new Error("Update helper readiness marker does not acknowledge a launch gate");
288
+ const [mapped, gate] = await Promise.all([readUpdateStageState(staging), readUpdateLaunchGate(options.target)]);
289
+ if (!mapped || mapped.phase !== "armed" || mapped.generation !== generation || mapped.version !== options.version || mapped.helperPid !== child.pid || mapped.helperOwner !== helperOwner || mapped.launchGateOwner !== launchGateOwner || gate?.generation !== generation || gate.version !== options.version || gate.owner !== launchGateOwner) throw new Error("Update helper readiness does not match the exact published launch gate");
290
+ if (exited(child)) throw new Error("Update helper exited before readiness was accepted");
291
+ break;
292
+ }
293
+ if (exited(child)) throw new Error("Update helper exited before confirming ownership");
294
+ if (performance.now() >= deadline) throw new Error("Update helper did not confirm ownership in time");
138
295
  await Bun.sleep(50);
139
296
  }
140
297
  } catch (error) {
141
- await reset();
298
+ try {
299
+ await reset();
300
+ } catch (cleanupError) {
301
+ if (cleanupError instanceof UpdateCleanupPendingError) throw new UpdateCleanupPendingError("Update helper readiness failed and cleanup is pending", [error, cleanupError], () => cleanupError.retryCleanup());
302
+ throw new AggregateError([error, cleanupError], cleanupError instanceof Error ? cleanupError.message : "Update helper readiness cleanup failed", { cause: cleanupError });
303
+ }
142
304
  throw error;
143
305
  }
144
- return { cancel: reset };
306
+ return {
307
+ cancel: reset,
308
+ processDeadline
309
+ };
145
310
  }
146
311
  export { armUpdateHelper };
@@ -0,0 +1,23 @@
1
+ /** An update cleanup step failed and needs a caller-driven retry. */
2
+ export type UpdateCleanupPendingStage = 'helper-cleanup' | 'quit-preparation-resume' | 'quit-approval-release';
3
+ export declare class UpdateCleanupPendingError extends AggregateError {
4
+ private readonly retryOperation;
5
+ private retryInFlight;
6
+ private completed;
7
+ private terminalFailure;
8
+ private currentStage;
9
+ constructor(message: string, errors: readonly unknown[], retryOperation: () => Promise<void>, stage?: UpdateCleanupPendingStage);
10
+ get stage(): UpdateCleanupPendingStage;
11
+ markStage(stage: UpdateCleanupPendingStage): void;
12
+ /** Record a terminal transition only after a retry proved the helper exited. */
13
+ markTerminal(error: UpdateCleanupTerminalError): void;
14
+ get terminalError(): UpdateCleanupTerminalError | undefined;
15
+ /** Retry cleanup while retaining its helper or quit-approval context. */
16
+ retryCleanup(): Promise<void>;
17
+ }
18
+ /** Cleanup cannot cancel or reset a helper transition that has committed or needs recovery. */
19
+ export declare class UpdateCleanupTerminalError extends AggregateError {
20
+ constructor(message: string, errors?: readonly unknown[]);
21
+ }
22
+ /** Find terminal cleanup state carried through startup and service error wrappers. */
23
+ export declare function findUpdateCleanupTerminalError(error: unknown): UpdateCleanupTerminalError | undefined;
@@ -0,0 +1,65 @@
1
+ // src/updates/update-cleanup-error.ts
2
+ var UpdateCleanupPendingError = class extends AggregateError {
3
+ retryOperation;
4
+ retryInFlight;
5
+ completed = false;
6
+ terminalFailure;
7
+ currentStage;
8
+ constructor(message, errors, retryOperation, stage = "helper-cleanup") {
9
+ const detail = errors.map((error) => error instanceof Error ? error.message : String(error)).filter(Boolean).join("; ");
10
+ super(errors, detail ? `${message}: ${detail}` : message, { cause: errors.at(-1) });
11
+ this.retryOperation = retryOperation;
12
+ this.name = "UpdateCleanupPendingError";
13
+ this.currentStage = stage;
14
+ }
15
+ get stage() {
16
+ return this.currentStage;
17
+ }
18
+ markStage(stage) {
19
+ this.currentStage = stage;
20
+ }
21
+ /** Record a terminal transition only after a retry proved the helper exited. */
22
+ markTerminal(error) {
23
+ this.terminalFailure = error;
24
+ }
25
+ get terminalError() {
26
+ return this.terminalFailure;
27
+ }
28
+ /** Retry cleanup while retaining its helper or quit-approval context. */
29
+ retryCleanup() {
30
+ if (this.completed) return Promise.resolve();
31
+ if (this.retryInFlight) return this.retryInFlight;
32
+ const operation = Promise.resolve().then(this.retryOperation).then(() => {
33
+ this.completed = true;
34
+ });
35
+ this.retryInFlight = operation;
36
+ operation.finally(() => {
37
+ if (this.retryInFlight === operation) this.retryInFlight = void 0;
38
+ }).catch(() => {});
39
+ return operation;
40
+ }
41
+ };
42
+ /** Cleanup cannot cancel or reset a helper transition that has committed or needs recovery. */
43
+ var UpdateCleanupTerminalError = class extends AggregateError {
44
+ constructor(message, errors = []) {
45
+ super(errors, message, { cause: errors.at(-1) });
46
+ this.name = "UpdateCleanupTerminalError";
47
+ }
48
+ };
49
+ /** Find terminal cleanup state carried through startup and service error wrappers. */
50
+ function findUpdateCleanupTerminalError(error) {
51
+ const seen = /* @__PURE__ */ new Set();
52
+ const visit = (current) => {
53
+ if (current instanceof UpdateCleanupTerminalError) return current;
54
+ if (typeof current !== "object" || current === null || seen.has(current)) return void 0;
55
+ if (current instanceof UpdateCleanupPendingError) return current.terminalError;
56
+ seen.add(current);
57
+ if (current instanceof AggregateError) for (const nested of current.errors) {
58
+ const found = visit(nested);
59
+ if (found) return found;
60
+ }
61
+ if (current instanceof Error) return visit(current.cause);
62
+ };
63
+ return visit(error);
64
+ }
65
+ export { UpdateCleanupPendingError, UpdateCleanupTerminalError, findUpdateCleanupTerminalError };
@@ -1,3 +1,14 @@
1
+ import { type UpdateDownloadLease } from './update-download-lock';
2
+ export type { UpdateDownloadLease };
3
+ /** Create the versioned root and reclaim only directories without a live lease. */
4
+ export declare function initializeOwnedUpdateDownloadRoot(root: string): Promise<string>;
5
+ /** Create a leased directory after pruning only downloads whose owners have exited. */
6
+ export declare function createOwnedUpdateDownload(root: string): Promise<{
7
+ directory: string;
8
+ lease: UpdateDownloadLease;
9
+ }>;
10
+ /** Remove one owned download and its lease while holding the root gate. */
11
+ export declare function completeOwnedUpdateDownload(root: string, directory: string, lease: UpdateDownloadLease): Promise<void>;
1
12
  /** Discard a framework download under the caller's canonical, app-owned root. */
2
13
  export declare function discardOwnedUpdateDownload(root: string, directory: string): Promise<void>;
3
14
  /** Use an explicit owner for injected downloads; otherwise own the built-in layout. */
@@ -1,6 +1,116 @@
1
- import { rm } from "node:fs/promises";
1
+ import { acquireUpdateDownloadLease, withUpdateDownloadRootLock } from "./update-download-lock.js";
2
+ import { lstat, mkdir, mkdtemp, readdir, realpath, rm } from "node:fs/promises";
2
3
  import { basename, dirname, join, resolve } from "node:path";
3
4
  // src/updates/update-download-cleanup.ts
5
+ /** Create the versioned root and reclaim only directories without a live lease. */
6
+ async function initializeOwnedUpdateDownloadRoot(root) {
7
+ const requestedRoot = resolve(root);
8
+ await mkdir(dirname(requestedRoot), {
9
+ recursive: true,
10
+ mode: 448
11
+ });
12
+ const downloadsRoot = join(await realpath(dirname(requestedRoot)), basename(requestedRoot));
13
+ await withUpdateDownloadRootLock(downloadsRoot, async () => {
14
+ await mkdir(downloadsRoot, {
15
+ recursive: true,
16
+ mode: 448
17
+ });
18
+ await removeAbandonedUpdateDownloads(downloadsRoot);
19
+ });
20
+ return downloadsRoot;
21
+ }
22
+ /** Create a leased directory after pruning only downloads whose owners have exited. */
23
+ async function createOwnedUpdateDownload(root) {
24
+ const downloadsRoot = await initializeOwnedUpdateDownloadRoot(root);
25
+ return withUpdateDownloadRootLock(downloadsRoot, async () => {
26
+ const directory = await mkdtemp(join(downloadsRoot, "framework-update-"));
27
+ let lease;
28
+ try {
29
+ lease = await acquireUpdateDownloadLease(directory);
30
+ } catch (error) {
31
+ await rm(directory, {
32
+ recursive: true,
33
+ force: true
34
+ });
35
+ throw error;
36
+ }
37
+ if (!lease) {
38
+ await rm(directory, {
39
+ recursive: true,
40
+ force: true
41
+ });
42
+ throw new Error("Unable to acquire update download ownership");
43
+ }
44
+ return {
45
+ directory,
46
+ lease
47
+ };
48
+ });
49
+ }
50
+ /** Remove one owned download and its lease while holding the root gate. */
51
+ async function completeOwnedUpdateDownload(root, directory, lease) {
52
+ const downloadsRoot = resolve(root);
53
+ if (dirname(resolve(directory)) !== downloadsRoot || !basename(directory).startsWith("framework-update-") || lease.lockPath !== directory + ".lease") throw new Error("Invalid update download directory");
54
+ try {
55
+ await withUpdateDownloadRootLock(downloadsRoot, async () => {
56
+ try {
57
+ await rm(directory, {
58
+ recursive: true,
59
+ force: true
60
+ });
61
+ } finally {
62
+ await lease.release();
63
+ }
64
+ await rm(lease.lockPath, { force: true });
65
+ });
66
+ } catch (error) {
67
+ await lease.release().catch(() => {});
68
+ throw error;
69
+ }
70
+ }
71
+ /** Startup reclamation runs only while the versioned root gate is held. */
72
+ async function removeAbandonedUpdateDownloads(root) {
73
+ const entries = await readdir(root, { withFileTypes: true });
74
+ const directories = /* @__PURE__ */ new Set();
75
+ for (const entry of entries) {
76
+ if (!entry.name.startsWith("framework-update-")) continue;
77
+ const path = join(root, entry.name);
78
+ if (entry.name.endsWith(".lease")) continue;
79
+ try {
80
+ if (!(await lstat(path)).isDirectory()) continue;
81
+ directories.add(path);
82
+ const lease = await acquireUpdateDownloadLease(path, true);
83
+ if (!lease) continue;
84
+ try {
85
+ await rm(path, {
86
+ recursive: true,
87
+ force: true
88
+ });
89
+ } finally {
90
+ await lease.release();
91
+ }
92
+ await rm(lease.lockPath, { force: true });
93
+ } catch {}
94
+ }
95
+ for (const entry of entries) {
96
+ if (!entry.name.startsWith("framework-update-") || !entry.name.endsWith(".lease")) continue;
97
+ const leasePath = join(root, entry.name);
98
+ const directory = leasePath.slice(0, -6);
99
+ if (directories.has(directory)) continue;
100
+ try {
101
+ await lstat(directory);
102
+ continue;
103
+ } catch (error) {
104
+ if (error.code !== "ENOENT") continue;
105
+ }
106
+ try {
107
+ const lease = await acquireUpdateDownloadLease(directory, true);
108
+ if (!lease) continue;
109
+ await lease.release();
110
+ await rm(leasePath, { force: true });
111
+ } catch {}
112
+ }
113
+ }
4
114
  /** Discard a framework download under the caller's canonical, app-owned root. */
5
115
  async function discardOwnedUpdateDownload(root, directory) {
6
116
  if (dirname(directory) !== root || !basename(directory).startsWith("framework-update-")) throw new Error("Invalid update download directory");
@@ -18,4 +128,4 @@ function selectUpdateDownloadDiscard(root, customDownloader, owner) {
18
128
  await discardOwnedUpdateDownload(downloadsRoot, directory);
19
129
  };
20
130
  }
21
- export { discardOwnedUpdateDownload, selectUpdateDownloadDiscard };
131
+ export { completeOwnedUpdateDownload, createOwnedUpdateDownload, discardOwnedUpdateDownload, initializeOwnedUpdateDownloadRoot, selectUpdateDownloadDiscard };
@@ -0,0 +1,20 @@
1
+ export type UpdateDownloadLease = Readonly<{
2
+ release(): Promise<void>;
3
+ lockPath: string;
4
+ }>;
5
+ /**
6
+ * Serialize creation and reclamation inside one versioned download root,
7
+ * across processes (a persistent native file lock beside the root) and within
8
+ * this JS process (a queue, so overlapping async callers wait instead of
9
+ * polling the OS lock). Every lease file is opened, released for reclamation
10
+ * and removed only while this gate is held, so removing a lease file cannot
11
+ * race another process opening it.
12
+ */
13
+ export declare function withUpdateDownloadRootLock<T>(root: string, operation: () => Promise<T>): Promise<T>;
14
+ /**
15
+ * Hold a process-owned lease for one download until it is staged or
16
+ * discarded. A process crash releases the OS lock, which is how startup
17
+ * distinguishes an abandoned download from a live one. With `tryOnly`, an
18
+ * existing owner returns undefined instead of waiting.
19
+ */
20
+ export declare function acquireUpdateDownloadLease(directory: string, tryOnly?: boolean): Promise<UpdateDownloadLease | undefined>;