@adea-ai/app-framework 0.25.1 → 0.27.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 (128) hide show
  1. package/README.md +163 -21
  2. package/dist/app/application.d.ts +11 -4
  3. package/dist/app/application.js +24 -4
  4. package/dist/app/create-application.d.ts +9 -0
  5. package/dist/app/create-application.js +214 -143
  6. package/dist/app/private-group.d.ts +14 -0
  7. package/dist/app/private-group.js +39 -0
  8. package/dist/app/service-registry.d.ts +8 -4
  9. package/dist/app/service-registry.js +43 -6
  10. package/dist/appearance/custom-theme-import.d.ts +5 -7
  11. package/dist/appearance/custom-theme-import.js +66 -18
  12. package/dist/appearance/custom-theme-library.d.ts +51 -3
  13. package/dist/appearance/custom-theme-library.js +262 -33
  14. package/dist/appearance/editor.d.ts +3 -1
  15. package/dist/appearance/editor.js +37 -2
  16. package/dist/appearance/theme-file-importer.d.ts +7 -3
  17. package/dist/appearance/theme-file-importer.js +27 -7
  18. package/dist/appearance/theme-library-action-fence.d.ts +11 -0
  19. package/dist/appearance/theme-library-action-fence.js +29 -0
  20. package/dist/cli/framework-update-cli.js +16 -3
  21. package/dist/cli/release-step-cli.js +6 -1
  22. package/dist/desktop/application-command-client.d.ts +11 -1
  23. package/dist/desktop/application-command-client.js +66 -3
  24. package/dist/desktop/channel-handshake.d.ts +2 -1
  25. package/dist/desktop/channel-handshake.js +21 -5
  26. package/dist/desktop/client-asset-stream.d.ts +10 -0
  27. package/dist/desktop/client-asset-stream.js +97 -0
  28. package/dist/desktop/client-assets.d.ts +3 -1
  29. package/dist/desktop/client-assets.js +41 -6
  30. package/dist/desktop/desktop-client.d.ts +15 -1
  31. package/dist/desktop/desktop-client.js +235 -109
  32. package/dist/desktop/desktop-gateway.d.ts +2 -0
  33. package/dist/desktop/desktop-gateway.js +134 -22
  34. package/dist/desktop/desktop-host-websocket.d.ts +10 -0
  35. package/dist/desktop/desktop-host-websocket.js +28 -0
  36. package/dist/desktop/desktop-host.d.ts +9 -0
  37. package/dist/desktop/desktop-host.js +70 -61
  38. package/dist/desktop/desktop-port-file.d.ts +2 -0
  39. package/dist/desktop/desktop-port-file.js +23 -0
  40. package/dist/desktop/desktop-stream.d.ts +5 -0
  41. package/dist/desktop/desktop-stream.js +83 -15
  42. package/dist/desktop/gateway-limits.d.ts +2 -0
  43. package/dist/desktop/gateway-limits.js +6 -0
  44. package/dist/desktop/open-url-channel.d.ts +5 -3
  45. package/dist/desktop/open-url-channel.js +18 -5
  46. package/dist/desktop/typed-array-intrinsics.d.ts +6 -0
  47. package/dist/desktop/typed-array-intrinsics.js +19 -0
  48. package/dist/framework-source.json +1 -1
  49. package/dist/installer/installed-payload.js +1 -1
  50. package/dist/installer/installer-ci-bootstrap.js +2 -1
  51. package/dist/installer/installer-command.d.ts +13 -0
  52. package/dist/installer/installer-command.js +47 -0
  53. package/dist/installer/installer-extraction.js +27 -61
  54. package/dist/installer/installer-identity.d.ts +22 -3
  55. package/dist/installer/installer-identity.js +63 -72
  56. package/dist/installer/installer-image-mount.d.ts +48 -0
  57. package/dist/installer/installer-image-mount.js +347 -0
  58. package/dist/installer/installer-layout.d.ts +2 -0
  59. package/dist/installer/installer-layout.js +6 -2
  60. package/dist/installer/installer-process-cleanup.js +1 -1
  61. package/dist/installer/installer-renderer-evidence.js +6 -2
  62. package/dist/installer/upgrade-asset-download.js +30 -8
  63. package/dist/native/app-bundle.d.ts +2 -2
  64. package/dist/native/app-bundle.js +5 -4
  65. package/dist/native/cef-helper-download.d.ts +1 -0
  66. package/dist/native/cef-helper-download.js +35 -0
  67. package/dist/native/cef-helper.js +146 -61
  68. package/dist/native/exclusive-rename.d.ts +2 -0
  69. package/dist/native/exclusive-rename.js +52 -0
  70. package/dist/native/native-secret-store.js +5 -4
  71. package/dist/native/partitioned-window.d.ts +5 -2
  72. package/dist/native/partitioned-window.js +69 -9
  73. package/dist/native/sidecar-services.js +2 -2
  74. package/dist/native/sidecar.js +68 -25
  75. package/dist/native/window-bootstrap.js +2 -2
  76. package/dist/release/feed-state.js +2 -1
  77. package/dist/release/framework-update-lock.d.ts +2 -0
  78. package/dist/release/framework-update-lock.js +42 -0
  79. package/dist/release/framework-update.d.ts +6 -2
  80. package/dist/release/framework-update.js +165 -40
  81. package/dist/release/local-release.js +68 -39
  82. package/dist/release/release-config.js +1 -1
  83. package/dist/release/release-steps.d.ts +5 -0
  84. package/dist/release/release-steps.js +2 -1
  85. package/dist/shared/discard-stream.d.ts +4 -0
  86. package/dist/shared/discard-stream.js +9 -0
  87. package/dist/shell/app-shell.js +59 -7
  88. package/dist/shell/app-utilities.js +2 -2
  89. package/dist/shell/application-menu.d.ts +13 -0
  90. package/dist/shell/application-menu.js +21 -8
  91. package/dist/update-helper.bundle.js +40 -4
  92. package/dist/updates/channel-update-manager.d.ts +2 -0
  93. package/dist/updates/channel-update-manager.js +15 -3
  94. package/dist/updates/desktop-updater.d.ts +2 -0
  95. package/dist/updates/desktop-updater.js +36 -7
  96. package/dist/updates/linux-process-state.d.ts +2 -0
  97. package/dist/updates/linux-process-state.js +13 -0
  98. package/dist/updates/release-location.js +5 -4
  99. package/dist/updates/update-adapter.js +5 -0
  100. package/dist/updates/update-arm.d.ts +2 -0
  101. package/dist/updates/update-arm.js +58 -7
  102. package/dist/updates/update-discovery.js +2 -1
  103. package/dist/updates/update-download-cleanup.d.ts +7 -0
  104. package/dist/updates/update-download-cleanup.js +21 -0
  105. package/dist/updates/update-download.js +41 -20
  106. package/dist/updates/update-exclusive-rename.d.ts +3 -2
  107. package/dist/updates/update-exclusive-rename.js +3 -50
  108. package/dist/updates/update-extraction.js +1 -1
  109. package/dist/updates/update-manager.d.ts +17 -1
  110. package/dist/updates/update-manager.js +27 -8
  111. package/dist/updates/update-process-fence.js +18 -3
  112. package/dist/views/appearance-surface.js +51 -15
  113. package/package.json +8 -3
  114. package/src/app/application.tsx +49 -7
  115. package/src/appearance/custom-theme-import.ts +67 -7
  116. package/src/appearance/custom-theme-library.ts +391 -33
  117. package/src/appearance/editor.ts +49 -10
  118. package/src/appearance/theme-file-importer.ts +43 -12
  119. package/src/appearance/theme-library-action-fence.ts +28 -0
  120. package/src/desktop/client-asset-stream.ts +118 -0
  121. package/src/desktop/client-assets.ts +55 -5
  122. package/src/shell/app-shell.tsx +71 -8
  123. package/src/shell/app-utilities.tsx +2 -2
  124. package/src/updates/update-adapter.ts +5 -0
  125. package/src/views/appearance-surface.tsx +61 -29
  126. package/templates/application/README.md +5 -1
  127. package/templates/application/scripts/app-version.ts +7 -3
  128. package/templates/application/src/bun/index.ts +2 -0
@@ -1,41 +1,18 @@
1
1
  import { assertInstallerContext, assertInstallerLayout, assertPortableAppName } from "./installer-layout.js";
2
2
  import { assertNativeExecutable } from "./native-executable.js";
3
+ import { cleanupInstallerDirectoryAfterFailure, defaultInstallerImageMountIo, withInstallerImageRetries } from "./installer-image-mount.js";
4
+ import { runInstallerCommand } from "./installer-command.js";
3
5
  import { verifyInstallerPayload } from "./installer-identity.js";
4
- import { chmod, lstat, mkdir, mkdtemp, open, readdir, realpath, rm } from "node:fs/promises";
6
+ import { chmod, lstat, mkdir, mkdtemp, open, readdir, realpath } from "node:fs/promises";
5
7
  import { isAbsolute, join, relative, resolve, sep, win32 } from "node:path";
6
8
  import { createHash } from "node:crypto";
7
9
  // src/installer/installer-extraction.ts
8
10
  async function run(cmd, env) {
9
- const child = Bun.spawn({
10
- cmd,
11
- env,
12
- stdout: "pipe",
13
- stderr: "pipe",
14
- signal: AbortSignal.timeout(12e4)
11
+ return runInstallerCommand(cmd, env, {
12
+ outputLimit: 8388608,
13
+ overflowMessage: "Installer command output exceeds bound",
14
+ failureMessage: "Installer preparation command failed"
15
15
  });
16
- const output = (async () => {
17
- const chunks = [];
18
- let size = 0;
19
- for await (const chunk of child.stdout) {
20
- size += chunk.length;
21
- if (size > 8388608) {
22
- child.kill();
23
- throw new Error("Installer command output exceeds bound");
24
- }
25
- chunks.push(chunk);
26
- }
27
- return Buffer.concat(chunks).toString("utf8");
28
- })();
29
- const errors = (async () => {
30
- for await (const _chunk of child.stderr);
31
- })();
32
- const [text, , status] = await Promise.all([
33
- output,
34
- errors,
35
- child.exited
36
- ]);
37
- if (status !== 0) throw new Error("Installer preparation command failed");
38
- return text;
39
16
  }
40
17
  async function extract(tar, archive, member, destination, maximum, env) {
41
18
  const output = await open(destination, "wx", 384);
@@ -172,27 +149,20 @@ async function prepareInstallerExecution(options) {
172
149
  env
173
150
  });
174
151
  const directory = await mkdtemp(join(parent, "framework-installer-"));
175
- let mounted = false;
152
+ const imageIo = defaultInstallerImageMountIo(run);
176
153
  try {
177
154
  const profile = join(directory, "profile"), incoming = join(directory, "incoming");
178
155
  await mkdir(profile, { mode: 448 });
179
156
  await mkdir(incoming, { mode: 448 });
180
157
  const clean = cleanEnv(env);
181
158
  let executable;
182
- if (options.platform === "macos-arm64") {
183
- const mount = join(directory, "mount");
184
- await mkdir(mount);
185
- await run([
186
- "/usr/bin/hdiutil",
187
- "attach",
188
- "-readonly",
189
- "-nobrowse",
190
- "-mountpoint",
191
- mount,
192
- sourceInstaller
193
- ], clean);
194
- mounted = true;
195
- try {
159
+ if (options.platform === "macos-arm64") executable = await withInstallerImageRetries({
160
+ parent,
161
+ prefix: "framework-installer-mount-attempt-",
162
+ image: sourceInstaller,
163
+ env: clean,
164
+ run,
165
+ work: async (mount) => {
196
166
  const appName = `${options.appName}.app`, apps = (await readdir(mount)).filter((name) => name.endsWith(".app"));
197
167
  if (apps.length !== 1 || apps[0] !== appName) throw new Error("Unexpected installer application");
198
168
  const sourceApp = await realpath(join(mount, appName));
@@ -214,24 +184,19 @@ async function prepareInstallerExecution(options) {
214
184
  plist
215
185
  ], clean)).trim();
216
186
  if (!name || name === "." || name === ".." || /[\\/]/.test(name)) throw new Error("Invalid installer executable");
217
- executable = join(actualApp, "Contents", "MacOS", name);
187
+ const appExecutable = join(actualApp, "Contents", "MacOS", name);
218
188
  const sourceExecutable = join(sourceApp, "Contents", "MacOS", name);
219
- if (!within(actualApp, await realpath(executable)) || !within(sourceApp, await realpath(sourceExecutable))) throw new Error("Installer executable escapes application");
220
- await assertExecutable(executable, options.platform);
221
- if (JSON.stringify(await digest(sourceExecutable)) !== JSON.stringify(await digest(executable))) throw new Error("Copied installer executable differs");
189
+ if (!within(actualApp, await realpath(appExecutable)) || !within(sourceApp, await realpath(sourceExecutable))) throw new Error("Installer executable escapes application");
190
+ await assertExecutable(appExecutable, options.platform);
191
+ if (JSON.stringify(await digest(sourceExecutable)) !== JSON.stringify(await digest(appExecutable))) throw new Error("Copied installer executable differs");
222
192
  const archives = (await readdir(resources)).filter((value) => value.endsWith(".tar.zst"));
223
193
  if (archives.length !== 1) throw new Error("Missing installer archive");
224
194
  const embedded = await digest(join(resources, archives[0]));
225
195
  if (embedded.size !== verified.archive.size || embedded.digest !== verified.archive.digest) throw new Error("Copied installer archive differs");
226
- } finally {
227
- await run([
228
- "/usr/bin/hdiutil",
229
- "detach",
230
- mount
231
- ], clean);
232
- mounted = false;
196
+ return executable;
233
197
  }
234
- } else {
198
+ });
199
+ else {
235
200
  const root = env.SystemRoot;
236
201
  if (options.platform === "windows-x64" && (!root || !/^[A-Za-z]:[\\/]/.test(root))) throw new Error("Missing Windows system directory");
237
202
  const tar = options.platform === "windows-x64" ? win32.join(root, "System32", "tar.exe") : "tar";
@@ -279,10 +244,11 @@ async function prepareInstallerExecution(options) {
279
244
  executable
280
245
  };
281
246
  } catch (error) {
282
- if (!mounted) await rm(directory, {
283
- recursive: true,
284
- force: true
285
- });
247
+ try {
248
+ await cleanupInstallerDirectoryAfterFailure(directory, error, imageIo);
249
+ } catch (cleanupError) {
250
+ throw new AggregateError([error, cleanupError], "Installer preparation and cleanup failed", { cause: cleanupError });
251
+ }
286
252
  throw error;
287
253
  }
288
254
  }
@@ -1,22 +1,41 @@
1
1
  import { type InstallerPlatform } from './installer-layout';
2
+ import { type InstallerImageMountState } from './installer-image-mount';
2
3
  import type { Artifact } from '../release/release-qualification';
3
4
  export type ImageAttachIo = {
4
5
  run(args: string[], env: Record<string, string>): Promise<unknown>;
5
6
  mounted(mount: string): Promise<boolean>;
7
+ /** Optional tri-state probe; unknown is never treated as ownership proof. */
8
+ state?(mount: string): Promise<InstallerImageMountState>;
9
+ /** Kept for adapter compatibility; retries are unsafe after an indeterminate attach. */
6
10
  wait(ms: number): Promise<unknown>;
7
11
  };
8
12
  /**
9
- * Attach a disk image read-only, up to three times. A failed or timed-out attach can still
10
- * have mounted the image, so each failure detaches whatever is mounted before the retry.
13
+ * Attach once at a caller-provided mountpoint. The caller must create and reserve a fresh,
14
+ * empty mountpoint exclusively for this image operation, and keep it exclusive until this
15
+ * call finishes. The state probe rejects paths that are already mounted or whose state is
16
+ * unknown, but a mounted-state probe does not identify which image owns a volume; this API
17
+ * trusts the caller's exclusivity precondition and does not claim to verify image identity.
18
+ *
19
+ * A failed attach is indeterminate, so this function never retries or detaches by path and
20
+ * the caller must retain its temporary directory for recovery. This changes the former
21
+ * three-attempt, five-second retry behavior; internal verification and extraction preserve
22
+ * three attempts by using fresh private mountpoints and retaining failed-attempt directories.
11
23
  */
12
24
  export declare function attachImage(mount: string, image: string, env: Record<string, string>, io?: ImageAttachIo): Promise<void>;
13
- /** Inspect a shipped installer without executing it, on a matching disposable runner. */
25
+ /**
26
+ * Inspect a shipped installer without executing it, on a matching disposable runner, or with
27
+ * `local` on the maintainer's own matching machine for a local release (read-only inspection of
28
+ * an installer that machine just built; installer execution stays hosted-runner only).
29
+ * macOS attach gets up to three attempts at fresh private mountpoints. Failed-attempt
30
+ * directories remain available for recovery because Disk Arbitration may mount them later.
31
+ */
14
32
  export declare function verifyInstallerPayload(options: {
15
33
  platform: InstallerPlatform;
16
34
  appName: string;
17
35
  installer: string;
18
36
  archive: string;
19
37
  env?: Record<string, string | undefined>;
38
+ local?: boolean;
20
39
  }): Promise<{
21
40
  installer: Artifact;
22
41
  archive: Artifact;
@@ -1,6 +1,8 @@
1
- import { assertInstallerContext, assertInstallerLayout, assertPortableAppName } from "./installer-layout.js";
1
+ import { assertInstallerContext, assertInstallerHost, assertInstallerLayout, assertPortableAppName } from "./installer-layout.js";
2
2
  import { assertNativeExecutable } from "./native-executable.js";
3
- import { lstat, mkdir, mkdtemp, open, readdir, realpath, rm, stat } from "node:fs/promises";
3
+ import { InstallerImageLifecycleError, cleanupInstallerDirectoryAfterFailure, defaultInstallerImageMountIo, installerImageMountState, withInstallerImageRetries } from "./installer-image-mount.js";
4
+ import { runInstallerCommand } from "./installer-command.js";
5
+ import { lstat, mkdtemp, open, readdir, realpath } from "node:fs/promises";
4
6
  import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32 } from "node:path";
5
7
  import { createHash } from "node:crypto";
6
8
  import { tmpdir } from "node:os";
@@ -44,26 +46,36 @@ function environment(parent) {
44
46
  ]) if (parent[name]) env[name] = parent[name];
45
47
  return env;
46
48
  }
47
- /** Hosted macOS runners intermittently refuse an attach while disk arbitration is busy. */
48
49
  /** Whether a volume is mounted at a directory; unknown counts as mounted. */
49
50
  async function volumeAt(mount) {
50
- try {
51
- const [own, parent] = await Promise.all([stat(mount), stat(dirname(mount))]);
52
- return own.dev !== parent.dev;
53
- } catch {
54
- return true;
55
- }
51
+ return await installerImageMountState(mount) !== "unmounted";
56
52
  }
57
53
  /**
58
- * Attach a disk image read-only, up to three times. A failed or timed-out attach can still
59
- * have mounted the image, so each failure detaches whatever is mounted before the retry.
54
+ * Attach once at a caller-provided mountpoint. The caller must create and reserve a fresh,
55
+ * empty mountpoint exclusively for this image operation, and keep it exclusive until this
56
+ * call finishes. The state probe rejects paths that are already mounted or whose state is
57
+ * unknown, but a mounted-state probe does not identify which image owns a volume; this API
58
+ * trusts the caller's exclusivity precondition and does not claim to verify image identity.
59
+ *
60
+ * A failed attach is indeterminate, so this function never retries or detaches by path and
61
+ * the caller must retain its temporary directory for recovery. This changes the former
62
+ * three-attempt, five-second retry behavior; internal verification and extraction preserve
63
+ * three attempts by using fresh private mountpoints and retaining failed-attempt directories.
60
64
  */
61
65
  async function attachImage(mount, image, env, io = {
62
66
  run: command,
63
67
  mounted: volumeAt,
68
+ state: installerImageMountState,
64
69
  wait: Bun.sleep
65
70
  }) {
66
- for (let attempt = 1;; attempt++) try {
71
+ let initialState;
72
+ try {
73
+ initialState = io.state ? await io.state(mount) : await io.mounted(mount) ? "mounted" : "unmounted";
74
+ } catch (error) {
75
+ throw new InstallerImageLifecycleError([error, /* @__PURE__ */ new Error("Attach was not attempted because the caller-provided mount state is unknown")], true, dirname(mount), "attach", `Installer image attach refused because mountpoint state is unknown at ${mount}`);
76
+ }
77
+ if (initialState !== "unmounted") throw new InstallerImageLifecycleError([/* @__PURE__ */ new Error(`Attach was not attempted because the caller-provided mount path is ${initialState}`)], true, dirname(mount), "attach", `Installer image attach refused because mountpoint is ${initialState} at ${mount}`);
78
+ try {
67
79
  await io.run([
68
80
  "/usr/bin/hdiutil",
69
81
  "attach",
@@ -73,49 +85,23 @@ async function attachImage(mount, image, env, io = {
73
85
  mount,
74
86
  image
75
87
  ], env);
76
- return;
77
88
  } catch (error) {
78
- if (await io.mounted(mount)) await io.run([
79
- "/usr/bin/hdiutil",
80
- "detach",
81
- "-force",
82
- mount
83
- ], env);
84
- if (attempt === 3) throw error;
85
- await io.wait(5e3);
89
+ throw new InstallerImageLifecycleError([error, /* @__PURE__ */ new Error("Attach completion is indeterminate; do not retry or detach the caller-provided mount path")], true, dirname(mount), "attach", `Installer image attach failed; caller-provided mount path state is indeterminate at ${mount}`);
86
90
  }
91
+ let state;
92
+ try {
93
+ state = io.state ? await io.state(mount) : await io.mounted(mount) ? "mounted" : "unmounted";
94
+ } catch (error) {
95
+ throw new InstallerImageLifecycleError([error, /* @__PURE__ */ new Error("Attach returned success but the mount state is unknown")], true, dirname(mount), "attach", `Installer image attach returned success without a confirmed mount at ${mount}`);
96
+ }
97
+ if (state !== "mounted") throw new InstallerImageLifecycleError([/* @__PURE__ */ new Error(`Attach returned success but the requested mountpoint is ${state}`)], true, dirname(mount), "attach", `Installer image attach returned success without a confirmed mount at ${mount}`);
87
98
  }
88
99
  async function command(args, env) {
89
- const child = Bun.spawn({
90
- cmd: args,
91
- env,
92
- stdout: "pipe",
93
- stderr: "pipe",
94
- signal: AbortSignal.timeout(12e4)
100
+ return runInstallerCommand(args, env, {
101
+ outputLimit: 8388608,
102
+ overflowMessage: "Installer listing exceeds bound",
103
+ failureMessage: "Installer inspection command failed"
95
104
  });
96
- const stdout = (async () => {
97
- let size = 0;
98
- const chunks = [];
99
- for await (const chunk of child.stdout) {
100
- size += chunk.length;
101
- if (size > 8388608) {
102
- child.kill();
103
- throw new Error("Installer listing exceeds bound");
104
- }
105
- chunks.push(Buffer.from(chunk));
106
- }
107
- return Buffer.concat(chunks).toString("utf8");
108
- })();
109
- const stderr = (async () => {
110
- for await (const _chunk of child.stderr);
111
- })();
112
- const [text, , status] = await Promise.all([
113
- stdout,
114
- stderr,
115
- child.exited
116
- ]);
117
- if (status !== 0) throw new Error("Installer inspection command failed");
118
- return text;
119
105
  }
120
106
  async function extractMember(tar, installer, member, output, maximum, env) {
121
107
  const file = await open(output, "wx", 384);
@@ -179,10 +165,17 @@ function within(root, path) {
179
165
  const rel = relative(root, path);
180
166
  return rel !== "" && rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute(rel);
181
167
  }
182
- /** Inspect a shipped installer without executing it, on a matching disposable runner. */
168
+ /**
169
+ * Inspect a shipped installer without executing it, on a matching disposable runner, or with
170
+ * `local` on the maintainer's own matching machine for a local release (read-only inspection of
171
+ * an installer that machine just built; installer execution stays hosted-runner only).
172
+ * macOS attach gets up to three attempts at fresh private mountpoints. Failed-attempt
173
+ * directories remain available for recovery because Disk Arbitration may mount them later.
174
+ */
183
175
  async function verifyInstallerPayload(options) {
184
176
  const parent = options.env ?? process.env;
185
- assertInstallerContext(parent, options.platform, process.platform, process.arch);
177
+ if (options.local === true) assertInstallerHost(options.platform, process.platform, process.arch);
178
+ else assertInstallerContext(parent, options.platform, process.platform, process.arch);
186
179
  assertPortableAppName(options.appName);
187
180
  const installerPath = resolve(options.installer), archivePath = resolve(options.archive);
188
181
  const before = {
@@ -192,14 +185,15 @@ async function verifyInstallerPayload(options) {
192
185
  if (!Number.isSafeInteger(before.archive.size + 268435456)) throw new Error("Installer archive exceeds bound");
193
186
  const env = environment(parent);
194
187
  const temporary = await mkdtemp(join(tmpdir(), "framework-installer-inspect-"));
195
- const mount = join(temporary, "mount");
196
- let mounted = false;
188
+ const cleanupIo = defaultInstallerImageMountIo(command);
197
189
  try {
198
- if (options.platform === "macos-arm64") {
199
- await mkdir(mount);
200
- mounted = true;
201
- await attachImage(mount, installerPath, env);
202
- try {
190
+ if (options.platform === "macos-arm64") await withInstallerImageRetries({
191
+ parent: tmpdir(),
192
+ prefix: "framework-installer-inspect-attempt-",
193
+ image: installerPath,
194
+ env,
195
+ run: command,
196
+ work: async (mount) => {
203
197
  const apps = (await readdir(mount)).filter((name) => name.endsWith(".app"));
204
198
  if (apps.length !== 1) throw new Error("Installer application is missing or ambiguous");
205
199
  const resources = join(mount, apps[0], "Contents", "Resources");
@@ -219,15 +213,9 @@ async function verifyInstallerPayload(options) {
219
213
  if (archives.length !== 1) throw new Error("Installer archive is missing or ambiguous");
220
214
  const embedded = await identity(join(actualResources, archives[0]));
221
215
  if (embedded.size !== before.archive.size || embedded.digest !== before.archive.digest) throw new Error("Installer archive differs from release archive");
222
- } finally {
223
- await command([
224
- "/usr/bin/hdiutil",
225
- "detach",
226
- mount
227
- ], env);
228
- mounted = false;
229
216
  }
230
- } else {
217
+ });
218
+ else {
231
219
  const systemRoot = parent.SystemRoot;
232
220
  if (options.platform === "windows-x64" && (!systemRoot || !/^[A-Za-z]:[\\/]/.test(systemRoot))) throw new Error("Missing Windows system directory");
233
221
  const tar = options.platform === "windows-x64" ? win32.join(systemRoot, "System32", "tar.exe") : "tar";
@@ -275,12 +263,15 @@ async function verifyInstallerPayload(options) {
275
263
  archive: await identity(archivePath)
276
264
  };
277
265
  if (JSON.stringify(before) !== JSON.stringify(after)) throw new Error("Installer artifacts changed during inspection");
266
+ await cleanupInstallerDirectoryAfterFailure(temporary, void 0, cleanupIo);
278
267
  return before;
279
- } finally {
280
- if (!mounted || !await volumeAt(mount)) await rm(temporary, {
281
- recursive: true,
282
- force: true
283
- });
268
+ } catch (error) {
269
+ try {
270
+ await cleanupInstallerDirectoryAfterFailure(temporary, error, cleanupIo);
271
+ } catch (cleanupError) {
272
+ throw new AggregateError([error, cleanupError], "Installer inspection and cleanup failed", { cause: cleanupError });
273
+ }
274
+ throw error;
284
275
  }
285
276
  }
286
277
  export { attachImage, verifyInstallerPayload };
@@ -0,0 +1,48 @@
1
+ export type InstallerImageMountState = 'mounted' | 'unmounted' | 'unknown';
2
+ export type InstallerImageMountIo = {
3
+ run(args: string[], env: Record<string, string>): Promise<unknown>;
4
+ state(mount: string): Promise<InstallerImageMountState>;
5
+ containsNestedMount(directory: string): Promise<boolean>;
6
+ wait(ms: number): Promise<unknown>;
7
+ remove(directory: string): Promise<void>;
8
+ };
9
+ export declare function installerImageMountState(mount: string): Promise<InstallerImageMountState>;
10
+ export declare function defaultInstallerImageMountIo(run: InstallerImageMountIo['run']): InstallerImageMountIo;
11
+ /** Skip only cleanup already owned by this exact lifecycle attempt. */
12
+ export declare function cleanupInstallerDirectoryAfterFailure(directory: string, error: unknown, io: InstallerImageMountIo): Promise<void>;
13
+ export declare class InstallerImageLifecycleError extends AggregateError {
14
+ readonly directoryRetained: boolean;
15
+ readonly directory: string;
16
+ readonly phase: 'attach' | 'lifecycle';
17
+ constructor(errors: unknown[], directoryRetained: boolean, directory: string, phase?: 'attach' | 'lifecycle', message?: string);
18
+ }
19
+ /**
20
+ * Attach an installer image, inspect/copy its contents, and reconcile the mount before
21
+ * allowing recursive cleanup. A failed attach is always treated as indeterminate because
22
+ * disk arbitration can finish mounting after the attach command has exited.
23
+ */
24
+ export declare function withInstallerImage<T>(options: {
25
+ directory: string;
26
+ mount: string;
27
+ image: string;
28
+ env: Record<string, string>;
29
+ io: InstallerImageMountIo;
30
+ work(): Promise<T>;
31
+ }): Promise<T>;
32
+ /**
33
+ * Retry a transient attach only with fresh mountpoints. Failed paths are retained and
34
+ * rechecked during backoff and after a later success; finite checks cannot rule out a
35
+ * mount that appears later, so callers must not treat retries as proof those paths are gone.
36
+ */
37
+ export declare function withInstallerImageRetries<T>(options: {
38
+ parent: string;
39
+ prefix: string;
40
+ image: string;
41
+ env: Record<string, string>;
42
+ run: InstallerImageMountIo['run'];
43
+ attempts?: number;
44
+ retryDelayMs?: number;
45
+ createIo?: (directory: string, mount: string) => InstallerImageMountIo;
46
+ onRecovered?: (failures: InstallerImageLifecycleError[]) => void;
47
+ work(mount: string): Promise<T>;
48
+ }): Promise<T>;