[Server] Add ZIP as a second skill archive format

SkillArchiver now emits application/zip alongside application/gzip, giving
hosts the two formats SEP-2640 expects every conforming host to support.
The ZIP is built deterministically (sorted entries, DEFLATE, fixed
1980-01-01 timestamp) so the archive bytes -- and therefore the digest
advertised in the discovery index -- stay stable across rebuilds.

Author: wachterjohannes

src/Server/Skill/SkillArchiver.php

@@ -20,8 +20,8 @@
  * archive layout. Produced without temp files and with zeroed file metadata, so the same input
  * yields the same bytes (and therefore a stable digest).
  *
- * Currently emits gzip-compressed tar (`application/gzip`), which the SEP lists as one of the two
- * formats every conforming host is expected to support.
+ * Emits gzip-compressed tar (`application/gzip`) and ZIP (`application/zip`) — the two formats
+ * the SEP expects every conforming host to support.
  *
  * @author Johannes Wachter <johannes@sulu.io>
  */
@@ -32,6 +32,7 @@ final class SkillArchiver
      */
     public const FORMATS = [
         'application/gzip' => 'tar.gz',
+        'application/zip' => 'zip',
     ];
 
     /**
@@ -46,6 +47,31 @@ public function pack(array $files, string $mimeType): string
             throw new InvalidArgumentException(\sprintf('Unsupported skill archive format "%s". Supported: %s.', $mimeType, implode(', ', array_keys(self::FORMATS))));
         }
 
+        return match ($mimeType) {
+            'application/gzip' => $this->gzipTar($files),
+            'application/zip' => $this->zip($files),
+        };
+    }
+
+    /**
+     * @throws InvalidArgumentException if the format is unsupported
+     */
+    public function extension(string $mimeType): string
+    {
+        if (!isset(self::FORMATS[$mimeType])) {
+            throw new InvalidArgumentException(\sprintf('Unsupported skill archive format "%s". Supported: %s.', $mimeType, implode(', ', array_keys(self::FORMATS))));
+        }
+
+        return self::FORMATS[$mimeType];
+    }
+
+    /**
+     * @param array<string, string> $files
+     *
+     * @throws RuntimeException if compression fails
+     */
+    private function gzipTar(array $files): string
+    {
         $gzip = gzencode($this->tar($files), 9);
         if (false === $gzip) {
             throw new RuntimeException('Failed to gzip skill archive.');
@@ -55,15 +81,54 @@ public function pack(array $files, string $mimeType): string
     }
 
     /**
-     * @throws InvalidArgumentException if the format is unsupported
+     * Builds a deterministic ZIP archive: sorted entries, DEFLATE (method 8), and a fixed
+     * 1980-01-01 timestamp so the same input yields the same bytes.
+     *
+     * @param array<string, string> $files
+     *
+     * @throws RuntimeException if compression fails
      */
-    public function extension(string $mimeType): string
+    private function zip(array $files): string
     {
-        if (!isset(self::FORMATS[$mimeType])) {
-            throw new InvalidArgumentException(\sprintf('Unsupported skill archive format "%s". Supported: %s.', $mimeType, implode(', ', array_keys(self::FORMATS))));
+        ksort($files);
+
+        $local = '';
+        $central = '';
+        $offset = 0;
+        $count = 0;
+
+        foreach ($files as $path => $content) {
+            $compressed = gzdeflate($content, 9);
+            if (false === $compressed) {
+                throw new RuntimeException(\sprintf('Failed to deflate skill file "%s".', $path));
+            }
+
+            $crc = crc32($content) & 0xFFFFFFFF;
+
+            // version needed, flags, method (8 = deflate), mod time (0), mod date (0x0021 = 1980-01-01),
+            // crc32, compressed size, uncompressed size, name length, extra length.
+            $shared = pack('vvvvv', 20, 0, 8, 0, 0x0021)
+                .pack('VVV', $crc, \strlen($compressed), \strlen($content))
+                .pack('vv', \strlen($path), 0);
+
+            $localEntry = "PK\x03\x04".$shared.$path.$compressed;
+            $local .= $localEntry;
+
+            $central .= "PK\x01\x02"
+                .pack('v', 20)                  // version made by (MS-DOS, 2.0)
+                .$shared                        // version needed .. extra length
+                .pack('vvv', 0, 0, 0)           // comment length, disk number start, internal attributes
+                .pack('VV', 0, $offset)         // external attributes, relative offset of local header
+                .$path;
+
+            $offset += \strlen($localEntry);
+            ++$count;
         }
 
-        return self::FORMATS[$mimeType];
+        return $local.$central."PK\x05\x06"
+            .pack('vvvv', 0, 0, $count, $count)
+            .pack('VV', \strlen($central), $offset)
+            .pack('v', 0);
     }
 
     /**

tests/Unit/Server/Skill/SkillArchiverTest.php

@@ -49,13 +49,36 @@ public function testPackIsDeterministic(): void
     public function testExtensionForSupportedFormat(): void
     {
         $this->assertSame('tar.gz', (new SkillArchiver())->extension('application/gzip'));
+        $this->assertSame('zip', (new SkillArchiver())->extension('application/zip'));
+    }
+
+    public function testPackProducesReadableZip(): void
+    {
+        $files = $this->extractZip((new SkillArchiver())->pack([
+            'SKILL.md' => "# Skill\n",
+            'references/SECURITY.md' => "# Security\n",
+        ], 'application/zip'));
+
+        $this->assertSame("# Skill\n", $files['SKILL.md'] ?? null);
+        $this->assertSame("# Security\n", $files['references/SECURITY.md'] ?? null);
+    }
+
+    public function testPackZipIsDeterministic(): void
+    {
+        $archiver = new SkillArchiver();
+        $files = ['SKILL.md' => 'hello', 'a/b.txt' => 'world'];
+
+        $this->assertSame(
+            $archiver->pack($files, 'application/zip'),
+            $archiver->pack($files, 'application/zip'),
+        );
     }
 
     public function testPackRejectsUnsupportedFormat(): void
     {
         $this->expectException(InvalidArgumentException::class);
 
-        (new SkillArchiver())->pack(['SKILL.md' => 'x'], 'application/zip');
+        (new SkillArchiver())->pack(['SKILL.md' => 'x'], 'application/x-7z-compressed');
     }
 
     /**
@@ -88,6 +111,31 @@ private function extract(string $gzippedTar): array
         }
     }
 
+    /**
+     * @return array<string, string> relative path => content
+     */
+    private function extractZip(string $zip): array
+    {
+        $path = sys_get_temp_dir().'/skill-archiver-'.bin2hex(random_bytes(6)).'.zip';
+        file_put_contents($path, $zip);
+
+        try {
+            $archive = new \ZipArchive();
+            $this->assertTrue(true === $archive->open($path), 'Produced bytes are a readable ZIP archive');
+
+            $files = [];
+            for ($i = 0; $i < $archive->numFiles; ++$i) {
+                $name = (string) $archive->getNameIndex($i);
+                $files[$name] = (string) $archive->getFromIndex($i);
+            }
+            $archive->close();
+
+            return $files;
+        } finally {
+            @unlink($path);
+        }
+    }
+
     private function removeDirectory(string $directory): void
     {
         if (!is_dir($directory)) {

tests/Unit/Server/Skill/SkillProviderTest.php

@@ -189,7 +189,7 @@ public function testUnsupportedArchiveFormatThrows(): void
     {
         $this->expectException(InvalidArgumentException::class);
 
-        (new SkillProvider())->registerInto(Server::builder(), self::FIXTURES, archiveFormats: ['application/zip']);
+        (new SkillProvider())->registerInto(Server::builder(), self::FIXTURES, archiveFormats: ['application/x-7z-compressed']);
     }
 
     /**