Skip to content

Commit 8751020

Browse files
radroidclaude
andcommitted
feat(t3x): add the update-delivery decision and install-target logic
The rules that decide whether an announced build applies to this machine, and what it is safe to replace. Pure, isolated and heavily tested, because every rule here guards a failure that otherwise reports success. decision.ts refuses four things that "is this manifest different from mine?" would happily accept: - A commit hash of "unknown". resolveGitCommitHash emits that literal when git fails during a build; treated as a hash it matches nothing, so the app would offer an update on every payload forever, including right after installing one. - The build already running. Reinstalling it succeeds and changes nothing, which is exactly the indistinguishable-from-success case issue #47 describes. - An older buildNumber. The release matrix has two legs, so a slow Windows leg from run 19 can be announced after run 25; accepting it moves the app backwards while every indicator says the update worked. - Unsupported platforms, which stay silent rather than erroring. installTarget.ts refuses three more: - App translocation. macOS runs a quarantined app from a randomised read-only copy, and DesktopLifecycle.relaunch re-execs process.execPath — so installing to /Applications and relaunching would come back on the OLD build with verification passing against the wrong process. The first launch after a manual dmg drag is exactly this case. - An install location that is not /Applications. The path comes from the running executable; hardcoding /Applications would create a second app and leave the running one untouched, which the existing shell installer's dry-run warns about precisely because there is normally a human there to read it. - A bundle name mismatch. productName is "T3 Code (Alpha)" here, and the name is read from the mounted dmg rather than computed, because computing it has already gone wrong once in this repo. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 7bc0da5 commit 8751020

5 files changed

Lines changed: 565 additions & 0 deletions

File tree

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
import { describe, expect, it } from "vite-plus/test";
2+
3+
import { decideUpdateAction, type InstalledBuild } from "./decision.ts";
4+
import type { UpdateManifest } from "./manifest.ts";
5+
6+
const MANIFEST: UpdateManifest = {
7+
shortSha: "ffffffffffff",
8+
buildNumber: 20,
9+
sha: "f".repeat(40),
10+
version: "0.0.31-t3x.ffffffffffff",
11+
releaseTag: "t3x-build-ffffffffffff",
12+
builtAt: "2026-08-03T12:00:00.000Z",
13+
assets: [
14+
{
15+
platform: "darwin-arm64",
16+
file: "T3Code-ffffffffffff-arm64.dmg",
17+
url: "https://example.invalid/arm64.dmg",
18+
sha256: "a".repeat(64),
19+
bytes: 248_000_000,
20+
},
21+
{
22+
platform: "win32-x64",
23+
file: "T3Code-ffffffffffff-x64.exe",
24+
url: "https://example.invalid/x64.exe",
25+
sha256: "b".repeat(64),
26+
bytes: 190_000_000,
27+
},
28+
],
29+
};
30+
31+
const INSTALLED: InstalledBuild = {
32+
commitHash: "aaaaaaaaaaaa",
33+
buildNumber: 19,
34+
platform: "darwin",
35+
arch: "arm64",
36+
isPackaged: true,
37+
};
38+
39+
function installed(overrides: Partial<InstalledBuild> = {}): InstalledBuild {
40+
return { ...INSTALLED, ...overrides };
41+
}
42+
43+
describe("decideUpdateAction", () => {
44+
it("acts on a newer build with a matching asset", () => {
45+
const decision = decideUpdateAction(MANIFEST, installed());
46+
expect(decision.kind).toBe("act");
47+
expect(decision.kind === "act" && decision.asset.platform).toBe("darwin-arm64");
48+
});
49+
50+
it("picks the asset for the running platform", () => {
51+
const decision = decideUpdateAction(MANIFEST, installed({ platform: "win32", arch: "x64" }));
52+
expect(decision.kind === "act" && decision.asset.platform).toBe("win32-x64");
53+
});
54+
55+
it("acts on first run, when no previous buildNumber is known", () => {
56+
const decision = decideUpdateAction(MANIFEST, installed({ buildNumber: undefined }));
57+
expect(decision.kind).toBe("act");
58+
});
59+
60+
it("skips a build this app is already running", () => {
61+
// Issue #47's core hazard: reinstalling the running build succeeds and changes nothing, which
62+
// is indistinguishable from a real update unless it is refused up front.
63+
const decision = decideUpdateAction(MANIFEST, installed({ commitHash: "ffffffffffff" }));
64+
expect(decision).toEqual({ kind: "skip", reason: "already-running-this-build" });
65+
});
66+
67+
it("skips a build that is already running even when its buildNumber is higher", () => {
68+
// A rebuild of the same commit. Different run number, identical content — restarting for it
69+
// would be a no-op the user was asked to approve.
70+
const decision = decideUpdateAction(
71+
{ ...MANIFEST, buildNumber: 999 },
72+
installed({ commitHash: "ffffffffffff" }),
73+
);
74+
expect(decision).toEqual({ kind: "skip", reason: "already-running-this-build" });
75+
});
76+
77+
it("skips an older build rather than downgrading", () => {
78+
// The out-of-order case: a slow Windows leg from run 19 announced after run 25 has landed.
79+
// "Different from mine" would accept it and quietly move the user backwards.
80+
const decision = decideUpdateAction({ ...MANIFEST, buildNumber: 19 }, installed({ buildNumber: 25 }));
81+
expect(decision).toEqual({ kind: "skip", reason: "not-newer" });
82+
});
83+
84+
it("skips a re-announcement of the build already staged", () => {
85+
const decision = decideUpdateAction(MANIFEST, installed({ buildNumber: 20 }));
86+
expect(decision).toEqual({ kind: "skip", reason: "not-newer" });
87+
});
88+
89+
describe("own-commit trust", () => {
90+
it.each([
91+
["the literal 'unknown' the build script emits on git failure", "unknown"],
92+
["an absent hash", undefined],
93+
["an empty hash", ""],
94+
["a non-hex hash", "zzzzzzzzzzzz"],
95+
])("refuses to act when its own commit is %s", (_label, commitHash) => {
96+
// Any of these would otherwise compare unequal to every manifest forever, so the app would
97+
// offer an update on every single payload — including right after installing one.
98+
const decision = decideUpdateAction(MANIFEST, installed({ commitHash }));
99+
expect(decision).toEqual({ kind: "skip", reason: "unknown-own-commit" });
100+
});
101+
102+
it("accepts a full 40-char hash by comparing its 12-char prefix", () => {
103+
const decision = decideUpdateAction(MANIFEST, installed({ commitHash: "f".repeat(40) }));
104+
expect(decision).toEqual({ kind: "skip", reason: "already-running-this-build" });
105+
});
106+
107+
it("is case-insensitive about its own hash", () => {
108+
const decision = decideUpdateAction(MANIFEST, installed({ commitHash: "FFFFFFFFFFFF" }));
109+
expect(decision).toEqual({ kind: "skip", reason: "already-running-this-build" });
110+
});
111+
});
112+
113+
it("does nothing in an unpackaged dev build", () => {
114+
const decision = decideUpdateAction(MANIFEST, installed({ isPackaged: false }));
115+
expect(decision).toEqual({ kind: "skip", reason: "not-packaged" });
116+
});
117+
118+
it.each([
119+
["Intel macOS", "darwin" as NodeJS.Platform, "x64"],
120+
["Linux", "linux" as NodeJS.Platform, "x64"],
121+
["Windows arm64", "win32" as NodeJS.Platform, "arm64"],
122+
])("stays silent on %s, which v1 does not publish", (_label, platform, arch) => {
123+
const decision = decideUpdateAction(MANIFEST, installed({ platform, arch }));
124+
expect(decision).toEqual({ kind: "skip", reason: "unsupported-platform" });
125+
});
126+
127+
it("skips when the manifest carries no asset for this platform", () => {
128+
const macOnly: UpdateManifest = {
129+
...MANIFEST,
130+
assets: MANIFEST.assets.filter((asset) => asset.platform === "darwin-arm64"),
131+
};
132+
const decision = decideUpdateAction(macOnly, installed({ platform: "win32", arch: "x64" }));
133+
expect(decision).toEqual({ kind: "skip", reason: "no-asset-for-platform" });
134+
});
135+
});
Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
import {
2+
currentAssetPlatform,
3+
findAssetForPlatform,
4+
SHORT_SHA_LENGTH,
5+
type UpdateAsset,
6+
type UpdateManifest,
7+
} from "./manifest.ts";
8+
9+
/**
10+
* "Should this app act on this manifest?"
11+
*
12+
* Kept pure and separate from every I/O concern, because each rejection below corresponds to a
13+
* failure that is invisible when it goes wrong: an app that updates forever, an app that
14+
* downgrades itself, an app that reinstalls a build it is already running and reports success.
15+
*/
16+
17+
/**
18+
* `resolveGitCommitHash` in `scripts/build-desktop-artifact.ts` returns this literal when git
19+
* fails during a build. It must never be treated as a commit hash — an app that believes its own
20+
* commit is "unknown" differs from every real manifest and would update on every payload, forever.
21+
*/
22+
export const UNKNOWN_COMMIT_HASH = "unknown";
23+
24+
export interface InstalledBuild {
25+
/** From `DesktopAppIdentity`. Absent for any build that has no embedded hash. */
26+
readonly commitHash: string | undefined;
27+
/** From the last manifest this app acted on. Absent on first run. */
28+
readonly buildNumber: number | undefined;
29+
readonly platform: NodeJS.Platform;
30+
readonly arch: string;
31+
readonly isPackaged: boolean;
32+
}
33+
34+
export type UpdateDecision =
35+
| { readonly kind: "act"; readonly asset: UpdateAsset }
36+
| { readonly kind: "skip"; readonly reason: UpdateSkipReason };
37+
38+
export type UpdateSkipReason =
39+
| "not-packaged"
40+
| "unknown-own-commit"
41+
| "unsupported-platform"
42+
| "already-running-this-build"
43+
| "not-newer"
44+
| "no-asset-for-platform";
45+
46+
export function describeSkipReason(reason: UpdateSkipReason): string {
47+
switch (reason) {
48+
case "not-packaged":
49+
return "Update delivery is only active in packaged builds.";
50+
case "unknown-own-commit":
51+
return "This build has no embedded commit hash, so it cannot tell whether an update applies.";
52+
case "unsupported-platform":
53+
return "No artifact is published for this platform and architecture.";
54+
case "already-running-this-build":
55+
return "This build is already running.";
56+
case "not-newer":
57+
return "The announced build is not newer than the one already staged or running.";
58+
case "no-asset-for-platform":
59+
return "The announced build has no artifact for this platform.";
60+
}
61+
}
62+
63+
function normalizeCommitHash(value: string | undefined): string | undefined {
64+
if (value === undefined) return undefined;
65+
const trimmed = value.trim().toLowerCase();
66+
if (trimmed === "" || trimmed === UNKNOWN_COMMIT_HASH) return undefined;
67+
if (!/^[0-9a-f]{7,40}$/u.test(trimmed)) return undefined;
68+
return trimmed.slice(0, SHORT_SHA_LENGTH);
69+
}
70+
71+
export function decideUpdateAction(
72+
manifest: UpdateManifest,
73+
installed: InstalledBuild,
74+
): UpdateDecision {
75+
// A dev build has no meaningful identity and cannot be installed over. Checked first so the
76+
// reason surfaced is the true one rather than a downstream symptom.
77+
if (!installed.isPackaged) {
78+
return { kind: "skip", reason: "not-packaged" };
79+
}
80+
81+
const ownHash = normalizeCommitHash(installed.commitHash);
82+
if (ownHash === undefined) {
83+
return { kind: "skip", reason: "unknown-own-commit" };
84+
}
85+
86+
const platform = currentAssetPlatform(installed.platform, installed.arch);
87+
if (platform === undefined) {
88+
return { kind: "skip", reason: "unsupported-platform" };
89+
}
90+
91+
// Before ordering, because reinstalling the build you are already running is the specific
92+
// failure issue #47 describes: it succeeds, reports success, and changes nothing.
93+
if (manifest.shortSha === ownHash) {
94+
return { kind: "skip", reason: "already-running-this-build" };
95+
}
96+
97+
// Strictly greater. A manifest that is merely *different* is not necessarily newer: the release
98+
// matrix has two legs, and a slow Windows leg from an earlier run can be announced after a
99+
// later run. Acting on it would move this app backwards onto an older build while every
100+
// indicator says the update worked.
101+
if (installed.buildNumber !== undefined && manifest.buildNumber <= installed.buildNumber) {
102+
return { kind: "skip", reason: "not-newer" };
103+
}
104+
105+
const asset = findAssetForPlatform(manifest, platform);
106+
if (asset === undefined) {
107+
return { kind: "skip", reason: "no-asset-for-platform" };
108+
}
109+
110+
return { kind: "act", asset };
111+
}
Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
import { describe, expect, it } from "vite-plus/test";
2+
3+
import {
4+
findEnclosingAppBundle,
5+
isTranslocatedPath,
6+
resolveMacInstallTarget,
7+
stagedBundlePath,
8+
} from "./installTarget.ts";
9+
10+
const APP = "/Applications/T3 Code (Alpha).app";
11+
const EXEC = `${APP}/Contents/MacOS/T3 Code (Alpha)`;
12+
13+
describe("isTranslocatedPath", () => {
14+
it("detects a translocated execPath", () => {
15+
expect(
16+
isTranslocatedPath(
17+
"/private/var/folders/x9/abc/T/AppTranslocation/1E2D-4F/d/T3 Code (Alpha).app/Contents/MacOS/T3 Code (Alpha)",
18+
),
19+
).toBe(true);
20+
});
21+
22+
it("does not flag a normal install", () => {
23+
expect(isTranslocatedPath(EXEC)).toBe(false);
24+
});
25+
26+
it("does not flag a path that merely mentions the word", () => {
27+
expect(isTranslocatedPath("/Users/me/AppTranslocationNotes/T3.app/Contents/MacOS/T3")).toBe(false);
28+
});
29+
});
30+
31+
describe("findEnclosingAppBundle", () => {
32+
it("walks up to the .app", () => {
33+
expect(findEnclosingAppBundle(EXEC)).toBe(APP);
34+
});
35+
36+
it("works for an app installed outside /Applications", () => {
37+
const home = "/Users/me/Applications/T3 Code (Alpha).app";
38+
expect(findEnclosingAppBundle(`${home}/Contents/MacOS/T3 Code (Alpha)`)).toBe(home);
39+
});
40+
41+
it("returns undefined when there is no enclosing bundle", () => {
42+
expect(findEnclosingAppBundle("/usr/local/bin/t3code")).toBeUndefined();
43+
});
44+
});
45+
46+
describe("resolveMacInstallTarget", () => {
47+
it("resolves the bundle from the running executable", () => {
48+
const result = resolveMacInstallTarget({
49+
execPath: EXEC,
50+
incomingAppName: "T3 Code (Alpha).app",
51+
});
52+
expect(result).toEqual({
53+
kind: "resolved",
54+
appBundlePath: APP,
55+
appName: "T3 Code (Alpha).app",
56+
});
57+
});
58+
59+
it("resolves an app installed outside /Applications", () => {
60+
// Never hardcode /Applications. Installing there while running from somewhere else would
61+
// create a second app and leave the running one untouched — a success that changes nothing.
62+
const home = "/Users/me/Applications/T3 Code (Alpha).app";
63+
const result = resolveMacInstallTarget({
64+
execPath: `${home}/Contents/MacOS/T3 Code (Alpha)`,
65+
incomingAppName: "T3 Code (Alpha).app",
66+
});
67+
expect(result.kind === "resolved" && result.appBundlePath).toBe(home);
68+
});
69+
70+
it("refuses when running translocated", () => {
71+
// The relaunch would re-exec the read-only translocated bundle, so the app would come back on
72+
// the OLD build while post-install verification passed against the wrong process.
73+
const result = resolveMacInstallTarget({
74+
execPath:
75+
"/private/var/folders/x9/abc/T/AppTranslocation/1E2D-4F/d/T3 Code (Alpha).app/Contents/MacOS/T3 Code (Alpha)",
76+
incomingAppName: "T3 Code (Alpha).app",
77+
});
78+
expect(result.kind === "refused" && result.refusal.kind).toBe("translocated");
79+
});
80+
81+
it("refuses when the incoming bundle has a different name", () => {
82+
// productName here is "T3 Code (Alpha)", not "T3 Code". The shell installer's own comment
83+
// records the consequence of guessing: it claimed an app that does not exist while a real
84+
// install replaced a differently-named one.
85+
const result = resolveMacInstallTarget({ execPath: EXEC, incomingAppName: "T3 Code.app" });
86+
expect(result.kind === "refused" && result.refusal.kind).toBe("name-mismatch");
87+
});
88+
89+
it("refuses when the executable is not inside a bundle", () => {
90+
const result = resolveMacInstallTarget({
91+
execPath: "/usr/local/bin/t3code",
92+
incomingAppName: "T3 Code (Alpha).app",
93+
});
94+
expect(result.kind === "refused" && result.refusal.kind).toBe("not-a-bundle");
95+
});
96+
});
97+
98+
describe("stagedBundlePath", () => {
99+
it("stages beside the target, on the same volume", () => {
100+
// Same directory so the swap is a rename. A staging dir on another volume would make `mv`
101+
// degrade into copy-then-delete, putting the expensive work back after the click.
102+
expect(stagedBundlePath(APP)).toBe(`${APP}.t3x-new`);
103+
});
104+
});

0 commit comments

Comments
 (0)