@adea-ai/app-framework 0.32.0 → 0.33.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.
package/README.md CHANGED
@@ -1147,10 +1147,13 @@ ordering does not depend on watcher polling. Schema-1 and schema-2 requests
1147
1147
  keep their prior helper transition behavior and do not participate in this
1148
1148
  launch-gate protocol.
1149
1149
 
1150
- This helper integration remains WIP. Generated bootstrap consumes a
1151
- launcher-supplied launch lease and runs packaged trust validation when that
1152
- descriptor is present, but stock generated packages do not enable the opt-in
1153
- native launcher. The opt-in launcher rejects an existing update gate before
1150
+ This helper integration remains WIP. Generated bootstrap creates the updater
1151
+ on every packaged launch. With a launcher-supplied launch lease it also leases
1152
+ retained asset generations and pauses startup if recovery fails; without one
1153
+ (stock packaging and Windows) `preparePackagedUpdateStartup({ admission:
1154
+ 'unmanaged' })` reconciles under the install lock alone and returns
1155
+ `unavailable`, which the app reports and starts without updates, instead of
1156
+ throwing. Stock generated packages do not enable the opt-in native launcher. The opt-in launcher rejects an existing update gate before
1154
1157
  starting the worker, so a gate left by a crashed helper still blocks a managed
1155
1158
  launch until it is recovered. Generated startup without a launcher lease (stock
1156
1159
  packaging) dispatches that recovery before launch admission:
@@ -1 +1 @@
1
- {"version":"0.32.0","commit":"9ba046d80699c484a994ff177b2a72b52e4db438"}
1
+ {"version":"0.33.0","commit":"c0d47a5bed1a1d47838e66063839560804f3374d"}
@@ -18,7 +18,7 @@ function errorCode(error) {
18
18
 
19
19
  // src/updates/update-helper.ts
20
20
  import { constants as constants7 } from "fs";
21
- import { lstat as lstat2, open as open7, realpath as realpath2 } from "fs/promises";
21
+ import { lstat as lstat3, open as open7, realpath as realpath2 } from "fs/promises";
22
22
  import { join as join9 } from "path";
23
23
 
24
24
  // src/updates/update-marker.ts
@@ -309,7 +309,7 @@ async function waitForUpdateProcesses(options) {
309
309
  // src/updates/update-swap.ts
310
310
  import { createHash } from "crypto";
311
311
  import { constants as constants5 } from "fs";
312
- import { lstat, open as open5, readdir, readFile as readFile3, readlink } from "fs/promises";
312
+ import { lstat as lstat2, open as open5, readdir, readFile as readFile3, readlink } from "fs/promises";
313
313
  import { basename as basename2, dirname as dirname3, join as join6 } from "path";
314
314
 
315
315
  // src/native/native-rename.ts
@@ -586,8 +586,20 @@ async function tryAcquireUpdateLock(target) {
586
586
 
587
587
  // src/updates/stable-file.ts
588
588
  import { constants as constants3 } from "fs";
589
- import { open as open3 } from "fs/promises";
589
+ import { lstat, open as open3 } from "fs/promises";
590
590
  async function readSmallStateFile(path, maximum, message) {
591
+ let linkFree;
592
+ if (constants3.O_NOFOLLOW === undefined) {
593
+ try {
594
+ linkFree = await lstat(path);
595
+ } catch (error) {
596
+ if (errorCode(error) === "ENOENT")
597
+ return;
598
+ throw error;
599
+ }
600
+ if (linkFree.isSymbolicLink())
601
+ throw new Error(message);
602
+ }
591
603
  let file;
592
604
  try {
593
605
  file = await open3(path, constants3.O_RDONLY | (constants3.O_NOFOLLOW ?? 0) | (constants3.O_NONBLOCK ?? 0));
@@ -601,7 +613,7 @@ async function readSmallStateFile(path, maximum, message) {
601
613
  }
602
614
  try {
603
615
  const info = await file.stat();
604
- if (!info.isFile() || info.size < 1 || info.size > maximum)
616
+ if (!info.isFile() || info.size < 1 || info.size > maximum || linkFree && (linkFree.dev !== info.dev || linkFree.ino !== info.ino))
605
617
  throw new Error(message);
606
618
  const text = await file.readFile("utf8");
607
619
  if (Buffer.byteLength(text) !== info.size)
@@ -729,7 +741,7 @@ function updateTreeIdentityFromStat(info) {
729
741
  return { device: info.dev.toString(10), inode: info.ino.toString(10) };
730
742
  }
731
743
  async function readUpdateTreeIdentity(tree) {
732
- const info = await lstat(tree, { bigint: true });
744
+ const info = await lstat2(tree, { bigint: true });
733
745
  return updateTreeIdentityFromStat(info);
734
746
  }
735
747
  function sameUpdateTreeIdentity(left, right) {
@@ -741,7 +753,7 @@ function sameTreeEntrySnapshot(left, right) {
741
753
  async function readUpdateTreeDigest(tree) {
742
754
  const hash = createHash("sha256");
743
755
  hash.update("adea-framework-update-tree\x00v1\x00", "utf8");
744
- const root = await lstat(tree, { bigint: true });
756
+ const root = await lstat2(tree, { bigint: true });
745
757
  if (!root.isDirectory() || root.isSymbolicLink())
746
758
  throw new Error("Update tree is not a real directory");
747
759
  const rootDevice = root.dev;
@@ -765,14 +777,14 @@ async function readUpdateTreeDigest(tree) {
765
777
  entryCount++;
766
778
  };
767
779
  const visit = async (path, relative) => {
768
- const before = await lstat(path, { bigint: true });
780
+ const before = await lstat2(path, { bigint: true });
769
781
  if (relative === "" && !sameTreeEntrySnapshot(root, before))
770
782
  throw new Error("Update tree root changed before its digest was computed");
771
783
  if (before.dev !== rootDevice)
772
784
  throw new Error("Update tree crosses a filesystem device");
773
785
  if (before.isSymbolicLink()) {
774
786
  const target = Buffer.from(await readlink(path), "utf8");
775
- const after = await lstat(path, { bigint: true });
787
+ const after = await lstat2(path, { bigint: true });
776
788
  if (!sameTreeEntrySnapshot(before, after))
777
789
  throw new Error("Update tree changed while reading a symbolic link");
778
790
  writeRecord("symlink", relative, before.mode, BigInt(target.length), target);
@@ -785,7 +797,7 @@ async function readUpdateTreeDigest(tree) {
785
797
  const child = relative ? `${relative}/${name}` : name;
786
798
  await visit(join6(path, name), child);
787
799
  }
788
- const after = await lstat(path, { bigint: true });
800
+ const after = await lstat2(path, { bigint: true });
789
801
  if (!sameTreeEntrySnapshot(before, after))
790
802
  throw new Error("Update tree changed while reading a directory");
791
803
  return;
@@ -809,7 +821,7 @@ async function readUpdateTreeDigest(tree) {
809
821
  hash.update(buffer.subarray(0, result.bytesRead));
810
822
  }
811
823
  const afterOpen = await file.stat({ bigint: true });
812
- const afterPath = await lstat(path, { bigint: true });
824
+ const afterPath = await lstat2(path, { bigint: true });
813
825
  if (bytesRead !== before.size || !sameTreeEntrySnapshot(opened, afterOpen) || !sameTreeEntrySnapshot(before, afterPath))
814
826
  throw new Error("Update tree changed while reading a file");
815
827
  } finally {
@@ -817,7 +829,7 @@ async function readUpdateTreeDigest(tree) {
817
829
  }
818
830
  };
819
831
  await visit(tree, "");
820
- const finalRoot = await lstat(tree, { bigint: true });
832
+ const finalRoot = await lstat2(tree, { bigint: true });
821
833
  if (!sameTreeEntrySnapshot(root, finalRoot))
822
834
  throw new Error("Update tree changed while its digest was computed");
823
835
  const count = Buffer.allocUnsafe(8);
@@ -837,12 +849,12 @@ async function syncDirectoryPath(path) {
837
849
  }
838
850
  }
839
851
  async function syncUpdateTree(tree) {
840
- const root = await lstat(tree);
852
+ const root = await lstat2(tree);
841
853
  if (!root.isDirectory())
842
854
  throw new Error("Update tree changed while syncing");
843
855
  const rootDevice = root.dev;
844
856
  const syncEntry = async (path) => {
845
- const info = await lstat(path);
857
+ const info = await lstat2(path);
846
858
  if (info.isSymbolicLink())
847
859
  return;
848
860
  if (info.dev !== rootDevice)
@@ -866,7 +878,7 @@ async function syncUpdateTree(tree) {
866
878
  }
867
879
  };
868
880
  await syncEntry(tree);
869
- const final = await lstat(tree);
881
+ const final = await lstat2(tree);
870
882
  if (!final.isDirectory() || final.dev !== rootDevice)
871
883
  throw new Error("Update tree changed while syncing");
872
884
  }
@@ -879,14 +891,14 @@ async function syncUpdateTreeParent(target) {
879
891
  }
880
892
  }
881
893
  async function exists(path) {
882
- return lstat(path).then(() => true, (error) => {
894
+ return lstat2(path).then(() => true, (error) => {
883
895
  if (errorCode(error) === "ENOENT")
884
896
  return false;
885
897
  throw error;
886
898
  });
887
899
  }
888
900
  async function assertDirectory(path) {
889
- const info = await lstat(path);
901
+ const info = await lstat2(path);
890
902
  if (!info.isDirectory() || info.isSymbolicLink())
891
903
  throw new Error("Update exchange requires real directories");
892
904
  }
@@ -1349,7 +1361,7 @@ function parseUpdateHelperRequest(value) {
1349
1361
  return Object.freeze(data);
1350
1362
  }
1351
1363
  async function readRequest(staging) {
1352
- const path = join9(staging, "request.json"), info = await lstat2(path);
1364
+ const path = join9(staging, "request.json"), info = await lstat3(path);
1353
1365
  if (!info.isFile() || info.size < 1 || info.size > 65536)
1354
1366
  throw new Error("Invalid update helper request");
1355
1367
  const file = await open7(path, constants7.O_RDONLY | (constants7.O_NOFOLLOW ?? 0));
@@ -1382,7 +1394,7 @@ async function acknowledgeUpdateCancellation(staging, request) {
1382
1394
  }
1383
1395
  async function updatePathExists(path) {
1384
1396
  try {
1385
- await lstat2(path);
1397
+ await lstat3(path);
1386
1398
  return true;
1387
1399
  } catch (error) {
1388
1400
  if (errorCode(error) === "ENOENT")
@@ -1399,7 +1411,7 @@ async function runUpdateHelper(options) {
1399
1411
  if (!liveness)
1400
1412
  throw new Error("Update helper liveness is already owned");
1401
1413
  try {
1402
- const stagingInfo = await lstat2(options.staging);
1414
+ const stagingInfo = await lstat3(options.staging);
1403
1415
  if (!stagingInfo.isDirectory() || stagingInfo.isSymbolicLink() || await realpath2(options.staging) !== options.staging)
1404
1416
  throw new Error("Invalid update staging directory");
1405
1417
  const request = await readRequest(options.staging);
@@ -16,16 +16,35 @@ export type PreparedPackagedUpdateStartup = Readonly<{
16
16
  release(): Promise<void>;
17
17
  };
18
18
  }>;
19
- /**
20
- * Validate bundled release trust, select only its channel from private app state,
21
- * then reconcile and lease retained assets before a managed packaged host starts.
22
- */
23
- export declare function preparePackagedUpdateStartup(options: {
19
+ /** Why an unmanaged launch runs without an updater. */
20
+ export type UnavailablePackagedUpdateStartup = Readonly<{
21
+ status: 'unavailable';
22
+ reason: string;
23
+ }>;
24
+ type PackagedUpdateStartupOptions = {
24
25
  entryDirectory: string;
25
26
  dataDirectory: string;
26
27
  identity: PackagedReleaseIdentity;
27
28
  loadManifest(root: string): Promise<ReadonlyMap<string, string>>;
29
+ };
30
+ /**
31
+ * Validate bundled release trust, select only its channel from private app
32
+ * state, and reconcile any earlier update before the packaged host starts.
33
+ *
34
+ * `acquired` (the default) is a launch admitted under an inherited instance
35
+ * lease: it also leases retained asset generations for the host, and any
36
+ * failure pauses startup. `unmanaged` is a launch without that lease (stock
37
+ * packaging, Windows): it reconciles under the install lock alone, retains no
38
+ * generations, and reports `unavailable` instead of throwing so the app still
39
+ * starts. The update helper waits for this process to exit before it swaps
40
+ * either way.
41
+ */
42
+ export declare function preparePackagedUpdateStartup(options: PackagedUpdateStartupOptions & {
43
+ admission?: 'acquired';
28
44
  }): Promise<PreparedPackagedUpdateStartup>;
45
+ export declare function preparePackagedUpdateStartup(options: PackagedUpdateStartupOptions & {
46
+ admission: 'acquired' | 'unmanaged';
47
+ }): Promise<PreparedPackagedUpdateStartup | UnavailablePackagedUpdateStartup>;
29
48
  /**
30
49
  * Pre-launch dispatcher for an update launch gate left behind by a helper
31
50
  * that crashed mid-transition. Call it before launch admission, while this
@@ -42,3 +61,4 @@ export declare function recoverPackagedUpdateLaunchGate(options: {
42
61
  dataDirectory: string;
43
62
  identity: PackagedReleaseIdentity;
44
63
  }): Promise<UpdateLaunchGateRecoveryResult>;
64
+ export {};
@@ -2,16 +2,13 @@ import { readPackagedVersion } from "../native/app-bundle.js";
2
2
  import { feedUrl } from "./release-feed.js";
3
3
  import { readUpdateLaunchGate } from "./update-launch-gate.js";
4
4
  import { createUpdateChannelStore, releaseChannelForUpdate } from "./update-channel-store.js";
5
- import { recoverUpdateLaunchGate } from "./update-resume.js";
5
+ import { recoverUpdateLaunchGate, resumeUpdate } from "./update-resume.js";
6
6
  import { installTarget, resumeAndAcquireRetainedDesktopClientAssets, updatePlatform, updateTrust } from "./desktop-updater.js";
7
7
  import { readPackagedReleaseConfig } from "./packaged-release-config.js";
8
8
  import { realpath } from "node:fs/promises";
9
9
  // src/updates/packaged-update-startup.ts
10
- /**
11
- * Validate bundled release trust, select only its channel from private app state,
12
- * then reconcile and lease retained assets before a managed packaged host starts.
13
- */
14
10
  async function preparePackagedUpdateStartup(options) {
11
+ if (options.admission === "unmanaged") return prepareUnmanagedUpdateStartup(options);
15
12
  const { release, trust, savedChannel, channel } = await packagedReleaseTrust(options);
16
13
  const { version: currentVersion } = readPackagedVersion(options.entryDirectory);
17
14
  const resumed = await resumeAndAcquireRetainedDesktopClientAssets({
@@ -34,6 +31,34 @@ async function preparePackagedUpdateStartup(options) {
34
31
  releaseLease: { release: resumed.release }
35
32
  };
36
33
  }
34
+ var releaseNothing = { release: async () => {} };
35
+ async function prepareUnmanagedUpdateStartup(options) {
36
+ try {
37
+ const { release, platform, trust, savedChannel, channel } = await packagedReleaseTrust(options);
38
+ const { version: currentVersion } = readPackagedVersion(options.entryDirectory);
39
+ return {
40
+ status: "ready",
41
+ release,
42
+ currentVersion,
43
+ savedChannel,
44
+ resume: await resumeUpdate({
45
+ target: await realpath(installTarget(options.entryDirectory, platform)),
46
+ trust: {
47
+ ...trust,
48
+ channel
49
+ },
50
+ currentVersion
51
+ }),
52
+ retainedClientAssets: [],
53
+ releaseLease: releaseNothing
54
+ };
55
+ } catch (error) {
56
+ return {
57
+ status: "unavailable",
58
+ reason: error instanceof Error ? error.message : String(error)
59
+ };
60
+ }
61
+ }
37
62
  /** Bundled release trust narrowed to the channel saved in private app state. */
38
63
  async function packagedReleaseTrust(options) {
39
64
  const release = await readPackagedReleaseConfig(options.entryDirectory, options.identity);
@@ -1,5 +1,5 @@
1
1
  import { errorCode } from "../app/value-guards.js";
2
- import { open } from "node:fs/promises";
2
+ import { lstat, open } from "node:fs/promises";
3
3
  import { createHash } from "node:crypto";
4
4
  import { constants as constants$1 } from "node:fs";
5
5
  // src/updates/stable-file.ts
@@ -53,6 +53,16 @@ async function hashFileAt(path, info, message) {
53
53
  /** Read a small regular state file without following a link. Missing reads as undefined; a
54
54
  * link, non-file, empty or oversized file fails with `message`. */
55
55
  async function readSmallStateFile(path, maximum, message) {
56
+ let linkFree;
57
+ if (constants$1.O_NOFOLLOW === void 0) {
58
+ try {
59
+ linkFree = await lstat(path);
60
+ } catch (error) {
61
+ if (errorCode(error) === "ENOENT") return void 0;
62
+ throw error;
63
+ }
64
+ if (linkFree.isSymbolicLink()) throw new Error(message);
65
+ }
56
66
  let file;
57
67
  try {
58
68
  file = await open(path, constants$1.O_RDONLY | (constants$1.O_NOFOLLOW ?? 0) | (constants$1.O_NONBLOCK ?? 0));
@@ -64,7 +74,7 @@ async function readSmallStateFile(path, maximum, message) {
64
74
  }
65
75
  try {
66
76
  const info = await file.stat();
67
- if (!info.isFile() || info.size < 1 || info.size > maximum) throw new Error(message);
77
+ if (!info.isFile() || info.size < 1 || info.size > maximum || linkFree && (linkFree.dev !== info.dev || linkFree.ino !== info.ino)) throw new Error(message);
68
78
  const text = await file.readFile("utf8");
69
79
  if (Buffer.byteLength(text) !== info.size) throw new Error(message);
70
80
  return text;
@@ -1,14 +1,14 @@
1
- import { errorCode, isUuid } from "../app/value-guards.js";
1
+ import { isUuid } from "../app/value-guards.js";
2
2
  import { isCanonicalPath } from "../native/canonical-path.js";
3
3
  import { verifyReleaseDescriptor } from "./signed-release.js";
4
- import { acquireUpdateLock, readUpdateStageState, writeUpdateStageState } from "./update-state-store.js";
4
+ import { acquireUpdateLock, readUpdateHelperRequestFile, readUpdateStageState, writeUpdateStageState } from "./update-state-store.js";
5
5
  import { readUpdateTreeDigest, readUpdateTreeIdentity, sameUpdateTreeDigest, sameUpdateTreeIdentity, updateStagingFor } from "./update-swap.js";
6
6
  import { isUpdateHelperReadyMarker, readUpdateMarker } from "./update-marker.js";
7
7
  import { updateLauncherPath } from "./update-launch.js";
8
8
  import { publishUpdateLaunchGateCancellationRequest, readUpdateLaunchGate } from "./update-launch-gate.js";
9
9
  import { hasUpdateHelperArtifacts, parseUpdateHelperRequest } from "./update-helper.js";
10
10
  import { UpdateCleanupPendingError, UpdateCleanupTerminalError } from "./update-cleanup-error.js";
11
- import { copyFile, lstat, mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
11
+ import { copyFile, lstat, mkdir, realpath, rm, writeFile } from "node:fs/promises";
12
12
  import { basename, dirname, join } from "node:path";
13
13
  import { randomUUID } from "node:crypto";
14
14
  import { spawn } from "node:child_process";
@@ -69,7 +69,9 @@ async function armUpdateHelper(options) {
69
69
  const current = await readUpdateStageState(staging);
70
70
  if (!current || current.generation !== generation) throw new Error("Update cancellation no longer owns this staging generation");
71
71
  if (current.phase === "staged") {
72
- const request = parseUpdateHelperRequest(JSON.parse(await readFile(join(staging, "request.json"), "utf8")));
72
+ const text = await readUpdateHelperRequestFile(staging);
73
+ if (text === void 0) throw new Error("Update helper request is missing");
74
+ const request = parseUpdateHelperRequest(JSON.parse(text));
73
75
  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");
74
76
  helperBoundFromStaged = true;
75
77
  if (!exited(child)) await writeUpdateStageState(staging, {
@@ -100,13 +102,9 @@ async function armUpdateHelper(options) {
100
102
  if (!child || child.pid === void 0 || current.helperPid !== child.pid || !helperOwner || current.helperOwner !== helperOwner) throw new Error("Another helper owns this staging generation");
101
103
  if (child.pid !== void 0 && !exited(child)) throw new Error("Update helper is still running during cancellation cleanup");
102
104
  }
103
- const requestPath = join(staging, "request.json");
104
105
  let request;
105
- try {
106
- request = parseUpdateHelperRequest(JSON.parse(await readFile(requestPath, "utf8")));
107
- } catch (error) {
108
- if (errorCode(error) !== "ENOENT") throw error;
109
- }
106
+ const requestText = await readUpdateHelperRequestFile(staging);
107
+ if (requestText !== void 0) request = parseUpdateHelperRequest(JSON.parse(requestText));
110
108
  if (request && (request.schema !== 2 && request.schema !== 3 || request.generation !== generation || request.helperOwner !== helperOwner)) throw new Error("Another helper owns this staging generation");
111
109
  if (child?.pid !== void 0) {
112
110
  if (!helperOwner || !exited(child)) throw new Error("Update helper is still running during cancellation cleanup");
@@ -2,7 +2,7 @@ import { UUID_SOURCE, errorCode, isUuid } from "../app/value-guards.js";
2
2
  import { renameExclusive } from "../native/native-rename.js";
3
3
  import { verifyReleaseDescriptor } from "./signed-release.js";
4
4
  import { tryAcquireUpdateLock } from "./update-lock.js";
5
- import { UpdateLockBusyError, acquireUpdateLock, readUpdateStageState, syncUpdateStageDirectory, writeUpdateStageState, writeUpdateStageStateDurably } from "./update-state-store.js";
5
+ import { UpdateLockBusyError, acquireUpdateLock, readUpdateHelperRequestFile, readUpdateStageState, syncUpdateStageDirectory, writeUpdateStageState, writeUpdateStageStateDurably } from "./update-state-store.js";
6
6
  import { readUpdateTreeDigest, readUpdateTreeIdentity, readUpdateTreeVersion, sameUpdateTreeDigest, sameUpdateTreeIdentity, syncUpdateTreeParent, updateStagingFor } from "./update-swap.js";
7
7
  import { readUpdateMarker } from "./update-marker.js";
8
8
  import { tryAcquireUpdateInstanceLease } from "./update-instance-lease.js";
@@ -44,10 +44,9 @@ async function recoverLegacyHandoff(options) {
44
44
  if (!Number.isSafeInteger(helperPid) || helperPid < 2 || updateProcessMayBeAlive(helperPid)) return { status: "recovery-required" };
45
45
  let request;
46
46
  try {
47
- const path = join(staging, "request.json");
48
- const info = await lstat(path);
49
- if (!info.isFile() || info.isSymbolicLink() || info.size < 1 || info.size > 65536) return { status: "recovery-required" };
50
- request = parseUpdateHelperRequest(JSON.parse(await readFile(path, "utf8")));
47
+ const text = await readUpdateHelperRequestFile(staging);
48
+ if (text === void 0) return { status: "recovery-required" };
49
+ request = parseUpdateHelperRequest(JSON.parse(text));
51
50
  } catch {
52
51
  return { status: "recovery-required" };
53
52
  }
@@ -2,6 +2,7 @@ import { errorCode, isUuid } from "../app/value-guards.js";
2
2
  import { isCanonicalPath } from "../native/canonical-path.js";
3
3
  import { renameExclusive } from "../native/native-rename.js";
4
4
  import { verifyReleaseDescriptor } from "./signed-release.js";
5
+ import { readSmallStateFile } from "./stable-file.js";
5
6
  import { readUpdateStageState, withUpdateLock, writeUpdateStageState } from "./update-state-store.js";
6
7
  import { readUpdateTreeDigest, readUpdateTreeIdentity, readUpdateTreeVersion, sameUpdateTreeDigest, sameUpdateTreeIdentity, updateStagingFor } from "./update-swap.js";
7
8
  import { readUpdateLaunchGate, tryAcquireUpdateHelperLiveness } from "./update-launch-gate.js";
@@ -13,7 +14,7 @@ import { updateProcessMayBeAlive } from "./update-process-liveness.js";
13
14
  import { planUpdateRetention, retentionIdentityKey } from "./update-retention-plan.js";
14
15
  import { publishUpdateRetentionIntent, readUpdateRetentionIntent, readUpdateRetentionIntentFile, sameRetentionIntent, updateRetentionIntentPath } from "./update-retention-marker.js";
15
16
  import { syncUpdateRetentionIntent } from "./update-retention-sync.js";
16
- import { link, lstat, mkdir, open, readFile, readdir, rename, rm, rmdir, unlink, writeFile } from "node:fs/promises";
17
+ import { link, lstat, mkdir, open, readdir, rename, rm, rmdir, unlink, writeFile } from "node:fs/promises";
17
18
  import { basename, dirname, join } from "node:path";
18
19
  import { randomUUID } from "node:crypto";
19
20
  import { constants as constants$1 } from "node:fs";
@@ -96,9 +97,10 @@ async function readPruneProgressFile(path, target, generation, expectedIntent, e
96
97
  const pathName = basename(path);
97
98
  const temporaryId = pathName.startsWith(`${canonicalName}.`) && pathName.endsWith(".tmp") ? pathName.slice(canonicalName.length + 1, -4) : "";
98
99
  const canonicalTemporary = dirname(path) === dirname(canonicalPath) && isUuid(temporaryId);
99
- const info = await lstat(path);
100
- if (path !== canonicalPath && !canonicalTemporary || !info.isFile() || info.isSymbolicLink() || info.size < 1 || info.size > 8192) return void 0;
101
- const value = JSON.parse(await readFile(path, "utf8"));
100
+ if (path !== canonicalPath && !canonicalTemporary) return void 0;
101
+ const text = await readSmallStateFile(path, 8192, "Invalid retention prune progress");
102
+ if (text === void 0) return void 0;
103
+ const value = JSON.parse(text);
102
104
  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
103
105
  const record = value;
104
106
  if (!hasExactOwnKeys(record, [
@@ -322,9 +324,8 @@ function parseCleanupMarker(value) {
322
324
  }
323
325
  async function readOwner(path) {
324
326
  try {
325
- const info = await lstat(path);
326
- if (!info.isFile() || info.isSymbolicLink() || info.size < 1 || info.size > 4096) return void 0;
327
- return parseOwner(JSON.parse(await readFile(path, "utf8")));
327
+ const text = await readSmallStateFile(path, 4096, "Invalid update retirement record");
328
+ return text === void 0 ? void 0 : parseOwner(JSON.parse(text));
328
329
  } catch {
329
330
  return;
330
331
  }
@@ -344,9 +345,8 @@ function parseHealthReceipt(value) {
344
345
  }
345
346
  async function readHealthReceipt(path) {
346
347
  try {
347
- const info = await lstat(path);
348
- if (!info.isFile() || info.isSymbolicLink() || info.size < 1 || info.size > 4096) return void 0;
349
- return parseHealthReceipt(JSON.parse(await readFile(path, "utf8")));
348
+ const text = await readSmallStateFile(path, 4096, "Invalid update retirement record");
349
+ return text === void 0 ? void 0 : parseHealthReceipt(JSON.parse(text));
350
350
  } catch {
351
351
  return;
352
352
  }
@@ -365,9 +365,8 @@ function healthReceiptMatches(actual, expected) {
365
365
  }
366
366
  async function readCleanupMarker(path) {
367
367
  try {
368
- const info = await lstat(path);
369
- if (!info.isFile() || info.isSymbolicLink() || info.size < 1 || info.size > 4096) return void 0;
370
- return parseCleanupMarker(JSON.parse(await readFile(path, "utf8")));
368
+ const text = await readSmallStateFile(path, 4096, "Invalid update retirement record");
369
+ return text === void 0 ? void 0 : parseCleanupMarker(JSON.parse(text));
371
370
  } catch {
372
371
  return;
373
372
  }
@@ -30,6 +30,8 @@ export type UpdateStageState = Readonly<{
30
30
  export declare class UpdateLockBusyError extends Error {
31
31
  constructor();
32
32
  }
33
+ /** The staged helper request, bounded and read without following a link. */
34
+ export declare function readUpdateHelperRequestFile(staging: string): Promise<string | undefined>;
33
35
  /** Acquire the stable per-install lock, waiting briefly for short transitions. */
34
36
  export declare function acquireUpdateLock(target: string, timeoutMs?: number): Promise<UpdateLock>;
35
37
  export declare function newUpdateStageState(input: {
@@ -12,6 +12,10 @@ var UpdateLockBusyError = class extends Error {
12
12
  this.name = "UpdateLockBusyError";
13
13
  }
14
14
  };
15
+ /** The staged helper request, bounded and read without following a link. */
16
+ function readUpdateHelperRequestFile(staging) {
17
+ return readSmallStateFile(join(staging, "request.json"), 65536, "Invalid update helper request");
18
+ }
15
19
  /** Acquire the stable per-install lock, waiting briefly for short transitions. */
16
20
  async function acquireUpdateLock(target, timeoutMs = 5e3) {
17
21
  const deadline = Date.now() + timeoutMs;
@@ -128,4 +132,4 @@ async function withUpdateLock(target, operation) {
128
132
  await lock.release();
129
133
  }
130
134
  }
131
- export { UpdateLockBusyError, acquireUpdateLock, newUpdateStageState, readUpdateStageState, syncUpdateStageDirectory, withUpdateLock, writeUpdateStageState, writeUpdateStageStateDurably };
135
+ export { UpdateLockBusyError, acquireUpdateLock, newUpdateStageState, readUpdateHelperRequestFile, readUpdateStageState, syncUpdateStageDirectory, withUpdateLock, writeUpdateStageState, writeUpdateStageStateDurably };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adea-ai/app-framework",
3
- "version": "0.32.0",
3
+ "version": "0.33.0",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -66,15 +66,19 @@ const immutableClientAssets = await loadClientAssetManifest(
66
66
  join(clientRoot, CLIENT_ASSET_MANIFEST_FILE)
67
67
  )
68
68
  const { version } = readPackagedVersion(import.meta.dir)
69
- let preparedUpdateStartup =
70
- launchAdmission === 'acquired'
71
- ? await preparePackagedUpdateStartup({
72
- entryDirectory: import.meta.dir,
73
- dataDirectory,
74
- identity: packagedIdentity,
75
- loadManifest: (root) => loadClientAssetManifest(join(root, CLIENT_ASSET_MANIFEST_FILE)),
76
- })
77
- : undefined
69
+ // Every packaged launch gets the updater. Admission only decides whether
70
+ // startup also leases retained asset generations (and must pause on failure)
71
+ // or runs unmanaged, where unavailable updates are reported and skipped.
72
+ const updateStartup = await preparePackagedUpdateStartup({
73
+ entryDirectory: import.meta.dir,
74
+ dataDirectory,
75
+ identity: packagedIdentity,
76
+ loadManifest: (root) => loadClientAssetManifest(join(root, CLIENT_ASSET_MANIFEST_FILE)),
77
+ admission: launchAdmission,
78
+ })
79
+ if (updateStartup.status === 'unavailable')
80
+ console.error(`updates unavailable: ${updateStartup.reason}`)
81
+ let preparedUpdateStartup = updateStartup.status === 'ready' ? updateStartup : undefined
78
82
  const services = createServiceRegistry<string>()
79
83
  registerNativeUtilities({
80
84
  services,