feat: Refactor release metadata structure to support nested artifacts by type and architecture, and implement external minisig file handling

Author: davej

README.md

@@ -123,38 +123,39 @@ async function createRelease() {
 
 ## Manifest Format
 
-The manifest is output as JSON with embedded minisign signatures:
+The manifest is output as JSON with a nested artifacts structure, organized by artifact type (zip/dmg) and architecture:
 
 ```json
 {
 	"version": "1.2.3",
 	"schemaVersion": 1,
 	"releaseDate": "2024-03-20T10:00:00.000Z",
 	"expires": "2099-12-31T23:59:59Z",
-	"files": [
-		{
-			"path": "MyApp-1.2.3-arm64.zip",
-			"sha512": "abcdef1234567890...",
-			"size": 123456789,
-			"arch": "arm64",
-			"minisig": "untrusted comment: signature from minisign secret key\n..."
-		},
-		{
-			"path": "MyApp-1.2.3-x64.zip",
-			"sha512": "0987654321fedcba...",
-			"size": 123456789,
-			"arch": "x64",
-			"minisig": "untrusted comment: signature from minisign secret key\n..."
+	"artifacts": {
+		"zip": {
+			"arm64": {
+				"path": "MyApp-1.2.3-arm64.zip",
+				"sha512": "abcdef1234567890...",
+				"size": 123456789
+			},
+			"x64": {
+				"path": "MyApp-1.2.3-x64.zip",
+				"sha512": "0987654321fedcba...",
+				"size": 123456789
+			}
 		}
-	],
+	},
 	"releaseNotes": "What's new in this release:\n- Feature A\n- Bug fix B"
 }
 ```
 
+Signatures are stored as external `.minisig` files alongside each artifact (e.g., `MyApp-1.2.3-arm64.zip.minisig`).
+
 **Important:**
 
 - **Version** is automatically extracted from the filename (e.g., `MyApp-1.2.3-arm64.zip` → `1.2.3`). This includes prerelease tags like `1.2.3-beta.1`. Use `--app-version` only if you need to override the detected version.
 - **Architecture** must be detectable from the filename. Include one of: `arm64`, `aarch64`, `x64`, `x86_64`, `amd64`, `x86`, `ia32`, `i386`, or `universal`.
+- **Artifact type** is determined by the file extension. Supported types: `.zip`, `.dmg`.
 
 ## Options
 

src/file-utils.ts

@@ -60,6 +60,18 @@ export function extractArchFromFilename(filename: string): string | undefined {
 	return undefined;
 }
 
+/**
+ * Extract artifact type from filename extension
+ */
+export function extractArtifactTypeFromFilename(
+	filename: string,
+): "zip" | "dmg" | undefined {
+	const lowerFilename = filename.toLowerCase();
+	if (lowerFilename.endsWith(".zip")) return "zip";
+	if (lowerFilename.endsWith(".dmg")) return "dmg";
+	return undefined;
+}
+
 /**
  * Read release notes from a file if path is provided
  */

src/integration.test.ts

@@ -40,6 +40,11 @@ function createTestServer(
 				const urlPath = req.url ?? "/";
 				const filePath = urlPath.startsWith("/") ? urlPath.slice(1) : urlPath;
 
+				// Debug: log all requests
+				process.stderr.write(
+					`[Server] Request: ${urlPath} -> ${filePath in files ? "200" : "404"}\n`,
+				);
+
 				if (filePath in files) {
 					const content = files[filePath];
 					res.writeHead(200, {
@@ -245,20 +250,31 @@ describe("Integration Tests", () => {
 			"utf-8",
 		);
 
-		// Verify the manifest is valid JSON
+		// Read the zip's signature (external minisig file)
+		const zipSigContent = await fs.readFile(`${zipPath}.minisig`, "utf-8");
+
+		// Verify the manifest is valid JSON with nested artifacts structure
 		const manifest = JSON.parse(manifestContent) as ReleaseManifest;
 		expect(manifest.version).toBe("1.0.0");
-		expect(manifest.files).toHaveLength(1);
-		expect(manifest.files[0].arch).toBe(arch);
-		expect(manifest.files[0].minisig).toBeDefined();
+		expect(manifest.artifacts).toBeDefined();
+		expect(manifest.artifacts.zip).toBeDefined();
+		const archKey = arch as "arm64" | "x64";
+		expect(manifest.artifacts.zip?.[archKey]).toBeDefined();
+		expect(manifest.artifacts.zip?.[archKey]?.sha512).toBeDefined();
 
 		// Step 3: Start the test server
 		const serverFiles: ServerFiles = {
 			"manifest.json": manifestContent,
 			"manifest.json.minisig": manifestSigContent,
 			[zipFilename]: zipContent,
+			[`${zipFilename}.minisig`]: zipSigContent,
 		};
 
+		// Debug: log server files
+		process.stderr.write(
+			`[Server] Available files: ${Object.keys(serverFiles).join(", ")}\n`,
+		);
+
 		server = await createTestServer(serverFiles, PORT);
 
 		// Step 4: Modify the installer's Info.plist
@@ -281,8 +297,10 @@ describe("Integration Tests", () => {
 
 		// Step 6: Verify the installation
 		if (exitCode !== 0) {
-			console.error("Installer stdout:", stdout);
-			console.error("Installer stderr:", stderr);
+			// Use process.stderr to bypass mocked console
+			process.stderr.write(`Installer stdout: ${stdout}\n`);
+			process.stderr.write(`Installer stderr: ${stderr}\n`);
+			process.stderr.write(`Manifest content: ${manifestContent}\n`);
 		}
 		expect(exitCode).toBe(0);
 
@@ -358,15 +376,19 @@ describe("Integration Tests", () => {
 		const manifestPath = path.join(tempDir, "manifest.json");
 		const manifestContent = await fs.readFile(manifestPath, "utf-8");
 
+		// Read the valid zip signature
+		const zipSigContent = await fs.readFile(`${zipPath}.minisig`, "utf-8");
+
 		// Corrupt the manifest signature
 		const corruptedSig =
 			"untrusted comment: corrupted signature\nRUQNnHQoKEDznXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=\ntrusted comment: corrupted\nXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==";
 
-		// Start the test server with corrupted signature
+		// Start the test server with corrupted manifest signature but valid zip signature
 		const serverFiles: ServerFiles = {
 			"manifest.json": manifestContent,
 			"manifest.json.minisig": corruptedSig,
 			[zipFilename]: zipContent,
+			[`${zipFilename}.minisig`]: zipSigContent,
 		};
 
 		server = await createTestServer(serverFiles, PORT);

src/manifest.test.ts

@@ -48,12 +48,10 @@ describe("createReleaseMetadata", () => {
 			size: 12345,
 		});
 		vi.mocked(fileUtils.extractArchFromFilename).mockReturnValue("x64");
+		vi.mocked(fileUtils.extractArtifactTypeFromFilename).mockReturnValue("zip");
 		vi.mocked(fileUtils.readReleaseNotes).mockResolvedValue(
 			"Mocked release notes",
 		);
-		vi.mocked(fileUtils.readMinisigFile).mockResolvedValue(
-			"untrusted comment: signature from minisign secret key\nmocked-signature-content",
-		);
 		vi.mocked(fs.mkdir).mockResolvedValue(undefined);
 		vi.mocked(fs.writeFile).mockResolvedValue(undefined);
 
@@ -89,7 +87,7 @@ describe("createReleaseMetadata", () => {
 		expect(result).toBe(path.join(".", "manifest-latest-mac.json"));
 	});
 
-	it("should output valid JSON", async () => {
+	it("should output valid JSON with nested artifacts structure", async () => {
 		const writeFileMock = vi.mocked(fs.writeFile);
 
 		await createReleaseMetadata({
@@ -101,31 +99,33 @@ describe("createReleaseMetadata", () => {
 		// Get the written content
 		const writtenContent = writeFileMock.mock.calls[0][1] as string;
 
-		// Verify it's valid JSON
+		// Verify it's valid JSON with nested structure
 		const parsed = JSON.parse(writtenContent) as ReleaseManifest;
 		expect(parsed.version).toBe("1.0.0");
 		expect(parsed.schemaVersion).toBe(1);
-		expect(parsed.files).toHaveLength(1);
-		expect(parsed.files[0].path).toBe("app-x64-1.0.0.zip");
-		expect(parsed.files[0].arch).toBe("x64");
-		expect(parsed.files[0].minisig).toContain("mocked-signature-content");
+		expect(parsed.artifacts).toBeDefined();
+		expect(parsed.artifacts.zip).toBeDefined();
+		expect(parsed.artifacts.zip?.x64).toBeDefined();
+		expect(parsed.artifacts.zip?.x64?.path).toBe("app-x64-1.0.0.zip");
+		expect(parsed.artifacts.zip?.x64?.sha512).toBe("mocked-hash");
+		expect(parsed.artifacts.zip?.x64?.size).toBe(12345);
 	});
 
-	it("should embed minisig content in file entries", async () => {
-		const writeFileMock = vi.mocked(fs.writeFile);
+	it("should create external minisig files for distributables", async () => {
+		const childProcess = await import("node:child_process");
+		const spawnMock = vi.mocked(childProcess.spawn);
 
 		await createReleaseMetadata({
 			distributables: ["app-x64-1.0.0.zip"],
 			secretKeyPath: "secret.key",
 			appVersion: "1.0.0",
 		});
 
-		const writtenContent = writeFileMock.mock.calls[0][1] as string;
-		const parsed = JSON.parse(writtenContent) as ReleaseManifest;
-
-		// Verify minisig is embedded
-		expect(parsed.files[0].minisig).toBe(
-			"untrusted comment: signature from minisign secret key\nmocked-signature-content",
+		// Verify minisign was called to sign the distributable (creates external .minisig file)
+		expect(spawnMock).toHaveBeenCalledWith(
+			"minisign",
+			expect.arrayContaining(["-S", "-m", "app-x64-1.0.0.zip"]),
+			expect.any(Object),
 		);
 	});
 
@@ -160,6 +160,21 @@ describe("createReleaseMetadata", () => {
 		).rejects.toThrow("Could not detect architecture from filename");
 	});
 
+	it("should throw an error when artifact type cannot be detected", async () => {
+		// Mock extractArtifactTypeFromFilename to return undefined
+		vi.mocked(fileUtils.extractArtifactTypeFromFilename).mockReturnValue(
+			undefined,
+		);
+
+		await expect(
+			createReleaseMetadata({
+				distributables: ["app-x64-1.0.0.tar.gz"],
+				secretKeyPath: "secret.key",
+				appVersion: "1.0.0",
+			}),
+		).rejects.toThrow("Could not detect artifact type from filename");
+	});
+
 	it("should include expires field when provided", async () => {
 		const writeFileMock = vi.mocked(fs.writeFile);
 		const expiresDate = "2099-12-31T23:59:59Z";
@@ -320,4 +335,52 @@ describe("createReleaseMetadata", () => {
 		// Second spawn call should be signing the manifest
 		expect(spawnMock).toHaveBeenCalledTimes(2);
 	});
+
+	it("should support multiple architectures in the same artifact type", async () => {
+		const writeFileMock = vi.mocked(fs.writeFile);
+
+		// Mock different architectures for different files
+		vi.mocked(fileUtils.extractArchFromFilename)
+			.mockReturnValueOnce("arm64")
+			.mockReturnValueOnce("x64");
+
+		await createReleaseMetadata({
+			distributables: ["app-arm64-1.0.0.zip", "app-x64-1.0.0.zip"],
+			secretKeyPath: "secret.key",
+			appVersion: "1.0.0",
+		});
+
+		const writtenContent = writeFileMock.mock.calls[0][1] as string;
+		const parsed = JSON.parse(writtenContent) as ReleaseManifest;
+
+		// Verify both architectures are present
+		expect(parsed.artifacts.zip?.arm64).toBeDefined();
+		expect(parsed.artifacts.zip?.x64).toBeDefined();
+		expect(parsed.artifacts.zip?.arm64?.path).toBe("app-arm64-1.0.0.zip");
+		expect(parsed.artifacts.zip?.x64?.path).toBe("app-x64-1.0.0.zip");
+	});
+
+	it("should support both zip and dmg artifact types", async () => {
+		const writeFileMock = vi.mocked(fs.writeFile);
+
+		// Mock different artifact types
+		vi.mocked(fileUtils.extractArtifactTypeFromFilename)
+			.mockReturnValueOnce("zip")
+			.mockReturnValueOnce("dmg");
+
+		await createReleaseMetadata({
+			distributables: ["app-x64-1.0.0.zip", "app-x64-1.0.0.dmg"],
+			secretKeyPath: "secret.key",
+			appVersion: "1.0.0",
+		});
+
+		const writtenContent = writeFileMock.mock.calls[0][1] as string;
+		const parsed = JSON.parse(writtenContent) as ReleaseManifest;
+
+		// Verify both artifact types are present
+		expect(parsed.artifacts.zip).toBeDefined();
+		expect(parsed.artifacts.dmg).toBeDefined();
+		expect(parsed.artifacts.zip?.x64?.path).toBe("app-x64-1.0.0.zip");
+		expect(parsed.artifacts.dmg?.x64?.path).toBe("app-x64-1.0.0.dmg");
+	});
 });