visync 1.0.1__tar.gz → 1.1.0__tar.gz

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.
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: visync
3
- Version: 1.0.1
4
- Summary: Ventoy ISO Synchronization Tool
3
+ Version: 1.1.0
4
+ Summary: Ventoy ISO Manager & Synchronization Tool
5
5
  Project-URL: Homepage, https://github.com/hxmbl/visync
6
6
  Project-URL: Repository, https://github.com/hxmbl/visync
7
7
  Project-URL: Issues, https://github.com/hxmbl/visync/issues
@@ -145,14 +145,17 @@ Config resolution order: explicit `--config` path, then `$VISYNC_CONFIG`, then `
145
145
 
146
146
  | Strategy | Description | Example |
147
147
  |---|---|---|
148
- | `direct_match` | Flat index page | Arch Linux |
148
+ | `direct_match` | Flat index page | Arch Linux, Kali Linux |
149
149
  | `fedora_nested` | Version dirs + variant subdirs | Fedora, Fedora KDE |
150
- | `ubuntu_nested` | Version dirs | Ubuntu, Parrot Security |
150
+ | `ubuntu_nested` | Version dirs | Ubuntu, CachyOS, Linux Mint, Parrot Security |
151
151
  | `nixos_channel` | Stable-channel lookup + channel page parse | NixOS Minimal, NixOS Graphical |
152
152
  | `popos_api` | JSON API | Pop!_OS |
153
153
  | `tails_api` | JSON API | Tails |
154
+ | `elementary_page` | Fresh homepage link + installation-guide checksum | elementary OS |
154
155
 
155
- **Checksum formats:** `gpg_checksum` (Fedora — inline `SHA256 (file) = hash`), `sha256sums` (Ubuntu, Arch, Parrot, NixOS, Tails), `json` (Tails)
156
+ **Checksum formats:** `gpg_checksum` (Fedora — inline `SHA256 (file) = hash`), `sha256sums` (Ubuntu, Arch, CachyOS, Linux Mint, Parrot, Kali, NixOS, Tails), `json` (Tails), `elementary_docs` (elementary OS — a SHA-256 tied to the exact ISO filename on the installation guide)
157
+
158
+ elementary OS publishes a temporary, tokenised download link on its homepage. visync reads that link fresh on every run and never hardcodes, generates, or caches the token; only `dl.elementaryos.org` is accepted, and an expired link is refreshed once before failing. The SHA-256 is read from the installation guide only when it is explicitly associated with the selected filename. A missing or ambiguous digest keeps the file and reports it as `UNVERIFIED`.
156
159
 
157
160
  Signature checking is configured separately via `signing_key_url` + `signing_key_fingerprint` and works with any signed layout, so Parrot's sectioned hash list gets both a signature check and a digest check.
158
161
 
@@ -107,14 +107,17 @@ Config resolution order: explicit `--config` path, then `$VISYNC_CONFIG`, then `
107
107
 
108
108
  | Strategy | Description | Example |
109
109
  |---|---|---|
110
- | `direct_match` | Flat index page | Arch Linux |
110
+ | `direct_match` | Flat index page | Arch Linux, Kali Linux |
111
111
  | `fedora_nested` | Version dirs + variant subdirs | Fedora, Fedora KDE |
112
- | `ubuntu_nested` | Version dirs | Ubuntu, Parrot Security |
112
+ | `ubuntu_nested` | Version dirs | Ubuntu, CachyOS, Linux Mint, Parrot Security |
113
113
  | `nixos_channel` | Stable-channel lookup + channel page parse | NixOS Minimal, NixOS Graphical |
114
114
  | `popos_api` | JSON API | Pop!_OS |
115
115
  | `tails_api` | JSON API | Tails |
116
+ | `elementary_page` | Fresh homepage link + installation-guide checksum | elementary OS |
116
117
 
117
- **Checksum formats:** `gpg_checksum` (Fedora — inline `SHA256 (file) = hash`), `sha256sums` (Ubuntu, Arch, Parrot, NixOS, Tails), `json` (Tails)
118
+ **Checksum formats:** `gpg_checksum` (Fedora — inline `SHA256 (file) = hash`), `sha256sums` (Ubuntu, Arch, CachyOS, Linux Mint, Parrot, Kali, NixOS, Tails), `json` (Tails), `elementary_docs` (elementary OS — a SHA-256 tied to the exact ISO filename on the installation guide)
119
+
120
+ elementary OS publishes a temporary, tokenised download link on its homepage. visync reads that link fresh on every run and never hardcodes, generates, or caches the token; only `dl.elementaryos.org` is accepted, and an expired link is refreshed once before failing. The SHA-256 is read from the installation guide only when it is explicitly associated with the selected filename. A missing or ambiguous digest keeps the file and reports it as `UNVERIFIED`.
118
121
 
119
122
  Signature checking is configured separately via `signing_key_url` + `signing_key_fingerprint` and works with any signed layout, so Parrot's sectioned hash list gets both a signature check and a digest check.
120
123
 
@@ -17,6 +17,8 @@ arch = "Arch Linux"
17
17
  fedora = "Fedora"
18
18
  ubuntu = "Ubuntu"
19
19
  debian = "Debian"
20
+ # CachyOS ISOs carry the abbreviated volume ID "COS_260809".
21
+ cos = "CachyOS Desktop"
20
22
 
21
23
  [fork_overrides]
22
24
  # Key format: "parent_distro.keyword_in_filename" = "Clean Name"
@@ -32,10 +34,20 @@ debian = "Debian"
32
34
 
33
35
  [standalone_matches]
34
36
  # Text matching targets for standalone distros, flavors, and tools
37
+ cachyos = "CachyOS Desktop"
38
+ # elementary OS writes "elementary OS" to the volume ID but prefixes its
39
+ # filenames with "elementaryos-", so both spellings must identify one distro.
40
+ elementary = "elementary OS"
41
+ elementaryos = "elementary OS"
35
42
  gparted = "GParted Live"
36
43
  hbcd = "Hiren's BootCD"
37
44
  hiren = "Hiren's BootCD"
38
45
  kodachi = "Linux Kodachi"
46
+ # Mint ISOs are prefixed "linuxmint-", which normalises to a single "linuxmint"
47
+ # token, so the "ubuntu.mint" fork override can never see a standalone "mint"
48
+ # token in the filename. Match the prefix directly or install/remove cannot
49
+ # target a downloaded Mint image.
50
+ linuxmint = "Linux Mint"
39
51
  nixos-minimal = "NixOS Minimal"
40
52
  nixos-graphical = "NixOS Graphical"
41
53
  nixos = "NixOS Minimal"
@@ -175,6 +187,25 @@ checksum_url = "{base_url}{version}/SHA256SUMS"
175
187
  checksum_format = "sha256sums"
176
188
  checksum_algo = "sha256"
177
189
 
190
+ [distros.LinuxMint]
191
+ clean_name = "Linux Mint"
192
+ keyword = "mint"
193
+ strategy = "ubuntu_nested"
194
+ # kernel.org mirrors linuxmint/stable (same bot-free mirror tree Fedora's
195
+ # releases use). The index holds numbered release dirs (22.1/, 22.2/, ...),
196
+ # each containing the edition ISOs and sha256sum.txt next to them.
197
+ base_url = "https://mirrors.kernel.org/linuxmint/stable/"
198
+ version_regex = 'href="([0-9\.]+)/"'
199
+ # Edition selection: pin the flagship Cinnamon image. Mate and Xfce share the
200
+ # same release directory and the resolver takes the first iso_regex match, so
201
+ # an unpinned pattern would depend on directory listing order.
202
+ iso_regex = 'href="(linuxmint-[0-9\.]+-cinnamon-64bit\.iso)"'
203
+ # {version} is parsed from the ISO filename ("22.1" in
204
+ # linuxmint-22.1-cinnamon-64bit.iso), which is also the release dir name.
205
+ checksum_url = "{base_url}{version}/sha256sum.txt"
206
+ checksum_format = "sha256sums"
207
+ checksum_algo = "sha256"
208
+
178
209
  [distros.ParrotSecurity]
179
210
  clean_name = "Parrot Security"
180
211
  keyword = "parrot"
@@ -198,6 +229,21 @@ signing_key_fingerprint = [
198
229
  "B711822346552E4D92DA02DF7A8286AF0E81EE4A",
199
230
  ]
200
231
 
232
+ [distros.CachyOS]
233
+ clean_name = "CachyOS Desktop"
234
+ keyword = "cachyos"
235
+ strategy = "ubuntu_nested"
236
+ base_url = "https://mirror.cachyos.org/ISO/desktop/"
237
+ # Release directories are date-numbered YYMMDD (260426/, 260628/, 260809/).
238
+ version_regex = 'href="([0-9]{6})/"'
239
+ # The release directory holds one desktop ISO alongside .sha1, .sha256,
240
+ # .sig and .pkgs.txt sidecars. The trailing quote keeps the sidecars out.
241
+ iso_regex = 'href="(cachyos-desktop-linux-[0-9]{6}\.iso)"'
242
+ # The .iso.sha256 sidecar is a standard "<digest> <filename>" line.
243
+ checksum_url = "{base_url}{version}/{iso_name}.sha256"
244
+ checksum_format = "sha256sums"
245
+ checksum_algo = "sha256"
246
+
201
247
  [distros.NixOS]
202
248
  clean_name = "NixOS Minimal"
203
249
  keyword = "nixos-minimal"
@@ -257,3 +303,33 @@ keyword = "pond"
257
303
  strategy = "content_disposition"
258
304
  base_url = "https://releases.butterfly.so/iso/"
259
305
  iso_regex = '^pond-installer-([0-9]+\.[0-9]+\.[0-9]+)-x86_64\.iso$'
306
+
307
+ [distros.Kali]
308
+ clean_name = "Kali Linux"
309
+ keyword = "kali"
310
+ strategy = "direct_match"
311
+ # cdimage.kali.org/current/ is a flat index of the current release: installer
312
+ # and live ISOs sit together with SHA256SUMS. The installer filenames are
313
+ # versioned (kali-linux-2026.3-installer-amd64.iso), so match on the version and
314
+ # architecture to select the standard x86_64 installer without picking up the
315
+ # netinst/purple/everything flavors or any live image (out of scope here).
316
+ base_url = "https://cdimage.kali.org/current/"
317
+ iso_regex = 'href="(kali-linux-[0-9]+\.[0-9]+-installer-amd64\.iso)"'
318
+ checksum_url = "{base_url}SHA256SUMS"
319
+ checksum_format = "sha256sums"
320
+ checksum_algo = "sha256"
321
+
322
+ [distros.ElementaryOS]
323
+ clean_name = "elementary OS"
324
+ keyword = "elementary"
325
+ strategy = "elementary_page"
326
+ # The homepage embeds a temporary, base64-looking token in the stable amd64
327
+ # download link. The scraper reads that link fresh on every run — it must never
328
+ # be hardcoded, generated, or cached. Only dl.elementaryos.org is accepted.
329
+ base_url = "https://elementary.io/"
330
+ # The installation guide publishes the SHA-256 next to the exact ISO filename.
331
+ # A missing or ambiguous digest leaves the download UNVERIFIED; HTTPS alone is
332
+ # never treated as integrity verification.
333
+ checksum_url = "https://elementary.io/docs/installation"
334
+ checksum_format = "elementary_docs"
335
+ checksum_algo = "sha256"
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "visync"
7
- version = "1.0.1"
8
- description = "Ventoy ISO Synchronization Tool"
7
+ version = "1.1.0"
8
+ description = "Ventoy ISO Manager & Synchronization Tool"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12,<3.16"
11
11
  license = { text = "MIT" }
@@ -15,7 +15,9 @@ from visync.download import (
15
15
  SyncStatus,
16
16
  _check_distro,
17
17
  _cleanup_old_versions,
18
+ _extract_elementary_amd64_url,
18
19
  _filename_variant_key,
20
+ _is_elementary_amd64_url,
19
21
  _variant_stem,
20
22
  download_iso,
21
23
  fetch_html,
@@ -173,6 +175,7 @@ class TestVariantStem(unittest.TestCase):
173
175
  ("Fedora-KDE-Live-44", "Fedora-KDE-Desktop-Live-44-1.7.x86_64.iso"),
174
176
  ("Pop_OS 24.04 amd64", "pop-os_24.04_amd64_generic_24.iso"),
175
177
  ("ARCH_202610", "archlinux-2026.10.01-x86_64.iso"),
178
+ ("COS_260809", "cachyos-desktop-linux-260809.iso"),
176
179
  ("Ubuntu-Server 26.04.1 LTS amd64", "ubuntu-26.04.1-live-server-amd64.iso"),
177
180
  ]
178
181
  for vid, filename in pairs:
@@ -378,6 +381,60 @@ class TestProcessScrapingStrategy(unittest.TestCase):
378
381
  self.assertIn("24.10/", url)
379
382
  _ok(f"Resolved to Ubuntu 24.10: {name}")
380
383
 
384
+ @patch("visync.download.ping_mirror", return_value=True)
385
+ @patch("visync.download.fetch_html")
386
+ def test_cachyos_nested_picks_newest_date_release(
387
+ self, mock_fetch_html: MagicMock, mock_ping: MagicMock
388
+ ):
389
+ """CachyOS release dirs are YYMMDD; the newest one wins and the
390
+ .sha256 sidecar must not be mistaken for the ISO."""
391
+ _section("Strategy: ubuntu_nested — CachyOS date releases")
392
+ mock_fetch_html.side_effect = [
393
+ (
394
+ '<a href="260426/">260426/</a>'
395
+ '<a href="260809/">260809/</a>'
396
+ '<a href="260628/">260628/</a>'
397
+ ),
398
+ (
399
+ '<a href="cachyos-desktop-linux-260809.iso">iso</a>'
400
+ '<a href="cachyos-desktop-linux-260809.iso.sha256">sum</a>'
401
+ ),
402
+ ]
403
+ settings = load_config()["distros"]["CachyOS"]
404
+ name, url = process_scraping_strategy("CachyOS Desktop", settings)
405
+ self.assertEqual(name, "cachyos-desktop-linux-260809.iso")
406
+ self.assertEqual(
407
+ url,
408
+ "https://mirror.cachyos.org/ISO/desktop/260809/"
409
+ "cachyos-desktop-linux-260809.iso",
410
+ )
411
+ _ok(f"Resolved to newest CachyOS release: {name}")
412
+
413
+ @patch("visync.download.ping_mirror", return_value=True)
414
+ @patch("visync.download.fetch_html")
415
+ def test_kali_picks_installer_amd64(
416
+ self, mock_fetch_html: MagicMock, mock_ping: MagicMock
417
+ ):
418
+ """Kali's flat current/ index mixes installer, live and VM images; only
419
+ the standard x86_64 installer ISO may be selected."""
420
+ _section("Strategy: direct_match — Kali installer amd64")
421
+ mock_fetch_html.return_value = (
422
+ '<a href="kali-linux-2026.3-hyperv-amd64.7z">vm</a>'
423
+ '<a href="kali-linux-2026.3-installer-amd64.iso">iso</a>'
424
+ '<a href="kali-linux-2026.3-installer-arm64.iso">arm</a>'
425
+ '<a href="kali-linux-2026.3-installer-netinst-amd64.iso">net</a>'
426
+ '<a href="kali-linux-2026.3-installer-purple-amd64.iso">purple</a>'
427
+ '<a href="kali-linux-2026.3-live-amd64.iso.torrent">live</a>'
428
+ )
429
+ settings = load_config()["distros"]["Kali"]
430
+ name, url = process_scraping_strategy("Kali Linux", settings)
431
+ self.assertEqual(name, "kali-linux-2026.3-installer-amd64.iso")
432
+ self.assertEqual(
433
+ url,
434
+ "https://cdimage.kali.org/current/kali-linux-2026.3-installer-amd64.iso",
435
+ )
436
+ _ok(f"Resolved to Kali installer: {name}")
437
+
381
438
  @patch("visync.download.ping_mirror", return_value=True)
382
439
  @patch("visync.download.fetch_html")
383
440
  def test_fedora_empty_root(self, mock_fetch_html: MagicMock, mock_ping: MagicMock):
@@ -635,6 +692,172 @@ class TestProcessScrapingStrategy(unittest.TestCase):
635
692
  _ok("Empty strings returned for unknown strategy")
636
693
 
637
694
 
695
+ class TestElementaryProvider(unittest.TestCase):
696
+ """elementary OS links carry a temporary token and the checksum lives in
697
+ prose on the installation guide, so both need provider-specific handling."""
698
+
699
+ TOKEN = "MTc5MzgzMzczNA==" # noqa: S105 - URL path segment, not a credential
700
+ AMD64 = "elementaryos-8.1-stable-amd64.20260219.iso"
701
+ ARM64 = "elementaryos-8.1-stable-arm64.20260219.iso"
702
+ AMD64_URL = f"https://dl.elementaryos.org/{TOKEN}/{AMD64}"
703
+ ARM64_URL = f"https://dl.elementaryos.org/{TOKEN}/{ARM64}"
704
+ AMD64_HASH = "bda93040d08c05911fb159f8150bf8f4ef2db6567ef6e2acd197cb6f395d3446"
705
+ ARM64_HASH = "85116d48c406ae7cd60c936050a099d4b8610321273f6f0a694796db4d4e86ba"
706
+
707
+ HOME_HTML = (
708
+ f'<a class="button download-link http arm" href="{ARM64_URL}">'
709
+ "ARM</a>"
710
+ '<a class="button download-link magnet x86" '
711
+ 'href="magnet:?xt=urn:btih:0314&dn=elementaryos-8.1-stable-amd64.20260219.iso">'
712
+ "magnet</a>"
713
+ f'<a autofocus class="button download-link http x86" href="{AMD64_URL}">'
714
+ "Download</a>"
715
+ )
716
+
717
+ CHECKSUM_HTML = (
718
+ f"<pre>SHA256 hash of Downloads\\{AMD64}:\n{AMD64_HASH}</pre>"
719
+ f"<pre>SHA256 hash of Downloads\\{ARM64}:\n{ARM64_HASH}</pre>"
720
+ )
721
+
722
+ def _settings(self) -> dict:
723
+ return dict(load_config()["distros"]["ElementaryOS"])
724
+
725
+ def test_extracts_exact_amd64_href_with_token(self) -> None:
726
+ _section("elementary: extract stable amd64 href")
727
+ url = _extract_elementary_amd64_url(self.HOME_HTML)
728
+ self.assertEqual(url, self.AMD64_URL)
729
+ _ok("arm64 and magnet links skipped, token preserved verbatim")
730
+
731
+ def test_accepts_only_exact_download_hostname(self) -> None:
732
+ _section("elementary: download URL validation")
733
+ self.assertTrue(_is_elementary_amd64_url(self.AMD64_URL))
734
+ bad_urls = [
735
+ self.AMD64_URL.replace("dl.elementaryos.org", "evil.example.com"),
736
+ self.AMD64_URL.replace(
737
+ "dl.elementaryos.org", "dl.elementaryos.org.evil.example.com"
738
+ ),
739
+ self.AMD64_URL.replace("https://", "http://"),
740
+ self.AMD64_URL.replace("dl.elementaryos.org", "user@dl.elementaryos.org"),
741
+ self.AMD64_URL.replace("dl.elementaryos.org", "dl.elementaryos.org:8443"),
742
+ self.AMD64_URL.replace("-amd64.", "-arm64."),
743
+ ]
744
+ for url in bad_urls:
745
+ with self.subTest(url=url):
746
+ self.assertFalse(_is_elementary_amd64_url(url))
747
+ _ok("lookalike hosts, cleartext, credentials, ports and arch are refused")
748
+
749
+ @patch("visync.download.ping_mirror", return_value=True)
750
+ @patch("visync.download.fetch_html")
751
+ def test_strategy_resolves_link_and_checksum(
752
+ self, mock_fetch: MagicMock, _mock_ping: MagicMock
753
+ ) -> None:
754
+ _section("elementary: strategy resolves link and checksum")
755
+ mock_fetch.side_effect = [self.HOME_HTML, self.CHECKSUM_HTML]
756
+ settings = self._settings()
757
+ with patch(
758
+ "visync.download._probe_elementary_download", return_value=(True, "")
759
+ ):
760
+ filename, url = process_scraping_strategy("elementary OS", settings)
761
+
762
+ self.assertEqual(filename, self.AMD64)
763
+ self.assertEqual(url, self.AMD64_URL)
764
+ self.assertEqual(settings["resolved_checksum"], self.AMD64_HASH)
765
+ _ok("fresh link returned and amd64 digest stashed")
766
+
767
+ @patch("visync.download.ping_mirror", return_value=True)
768
+ @patch("visync.download.fetch_html")
769
+ def test_strategy_refreshes_expired_link_once(
770
+ self, mock_fetch: MagicMock, _mock_ping: MagicMock
771
+ ) -> None:
772
+ _section("elementary: expired link refresh")
773
+ fresh_url = self.AMD64_URL.replace(self.TOKEN, "RlJFU0g==")
774
+ fresh_html = self.HOME_HTML.replace(self.AMD64_URL, fresh_url)
775
+ mock_fetch.side_effect = [self.HOME_HTML, fresh_html]
776
+ settings = self._settings()
777
+ with (
778
+ patch(
779
+ "visync.download._probe_elementary_download",
780
+ side_effect=[(False, "HEAD probe returned HTTP 403"), (True, "")],
781
+ ),
782
+ patch("visync.download._elementary_checksum_for", return_value=""),
783
+ ):
784
+ filename, url = process_scraping_strategy("elementary OS", settings)
785
+
786
+ self.assertEqual(filename, self.AMD64)
787
+ self.assertEqual(url, fresh_url)
788
+ self.assertEqual(mock_fetch.call_count, 2)
789
+ _ok("homepage fetched twice and the fresh token used")
790
+
791
+ @patch("visync.download.ping_mirror", return_value=True)
792
+ def test_strategy_gives_up_after_one_refresh(self, _mock_ping: MagicMock) -> None:
793
+ _section("elementary: retry is bounded to one refresh")
794
+ settings = self._settings()
795
+ with (
796
+ patch("visync.download.fetch_html", return_value=self.HOME_HTML),
797
+ patch(
798
+ "visync.download._probe_elementary_download",
799
+ return_value=(False, "HEAD probe returned HTTP 403"),
800
+ ),
801
+ ):
802
+ filename, url = process_scraping_strategy("elementary OS", settings)
803
+ self.assertEqual(filename, "")
804
+ self.assertEqual(url, "")
805
+ self.assertIn("403", settings["resolve_error"])
806
+ _ok("two failed probes stop instead of looping")
807
+
808
+ @patch("visync.download.ping_mirror", return_value=True)
809
+ @patch("visync.download.fetch_html")
810
+ def test_missing_checksum_still_allows_download(
811
+ self, mock_fetch: MagicMock, _mock_ping: MagicMock
812
+ ) -> None:
813
+ _section("elementary: unavailable checksum keeps download")
814
+ mock_fetch.side_effect = [self.HOME_HTML, "<html>no hashes here</html>"]
815
+ settings = self._settings()
816
+ # Simulate a digest stashed by an earlier resolution; it must not be
817
+ # reused for this image when the guide no longer provides one.
818
+ settings["resolved_checksum"] = "0" * 64
819
+ with patch(
820
+ "visync.download._probe_elementary_download", return_value=(True, "")
821
+ ):
822
+ filename, url = process_scraping_strategy("elementary OS", settings)
823
+
824
+ self.assertEqual(filename, self.AMD64)
825
+ self.assertEqual(url, self.AMD64_URL)
826
+ self.assertNotIn("resolved_checksum", settings)
827
+ _ok("download proceeds and is left for the UNVERIFIED policy")
828
+
829
+ @patch("visync.download.find_installed_isos")
830
+ @patch("visync.download.process_scraping_strategy")
831
+ def test_build_date_is_an_update(
832
+ self, mock_scrape: MagicMock, mock_find: MagicMock
833
+ ) -> None:
834
+ _section("elementary: build date is an update")
835
+ mock_scrape.return_value = (self.AMD64, self.AMD64_URL)
836
+ mock_find.return_value = [
837
+ Path("/tmp/elementaryos-8.1-stable-amd64.20260101.iso")
838
+ ]
839
+ settings = {"clean_name": "elementary OS"}
840
+
841
+ result = _check_distro("ElementaryOS", settings, Path("/tmp"), force=False)
842
+ self.assertIs(result.status, SyncStatus.STALE)
843
+ self.assertEqual(result.download_url, self.AMD64_URL)
844
+ _ok("same release, newer build is STALE")
845
+
846
+ @patch("visync.download.find_installed_isos")
847
+ @patch("visync.download.process_scraping_strategy")
848
+ def test_same_build_is_current(
849
+ self, mock_scrape: MagicMock, mock_find: MagicMock
850
+ ) -> None:
851
+ _section("elementary: same release+build is current")
852
+ mock_scrape.return_value = (self.AMD64, self.AMD64_URL)
853
+ mock_find.return_value = [Path(f"/tmp/{self.AMD64}")]
854
+ settings = {"clean_name": "elementary OS"}
855
+
856
+ result = _check_distro("ElementaryOS", settings, Path("/tmp"), force=False)
857
+ self.assertIs(result.status, SyncStatus.CURRENT)
858
+ _ok("exact release+build match is CURRENT")
859
+
860
+
638
861
  class _FakeResponse:
639
862
  """A minimal context-manager response for use with mock urlopen."""
640
863
 
@@ -58,6 +58,26 @@ class TestIdentifyDistro(unittest.TestCase):
58
58
  self.assertEqual(result, expected)
59
59
  _ok(f"'{vid}' / '{fname}' -> {result}")
60
60
 
61
+ def test_cachyos_volume_id_and_filename(self) -> None:
62
+ _section("CachyOS: abbreviated volume ID and filename")
63
+ self.assertEqual(identify_distro("COS_202608", ""), "CachyOS Desktop")
64
+ self.assertEqual(
65
+ identify_distro("", "cachyos-desktop-linux-260809.iso"),
66
+ "CachyOS Desktop",
67
+ )
68
+ _ok("COS_202608 / cachyos-desktop-linux-260809.iso -> CachyOS Desktop")
69
+
70
+ def test_elementary_volume_id_and_filename(self) -> None:
71
+ _section("elementary OS: spaced volume ID and prefixed filename")
72
+ self.assertEqual(
73
+ identify_distro("elementary OS 8.1 amd64", ""), "elementary OS"
74
+ )
75
+ self.assertEqual(
76
+ identify_distro("", "elementaryos-8.1-stable-amd64.20260219.iso"),
77
+ "elementary OS",
78
+ )
79
+ _ok("both spellings resolve to one distro")
80
+
61
81
  def test_filename_fallback(self) -> None:
62
82
  _section("Layer 4: Filename Regex Fallback")
63
83
  result = identify_distro("UNKNOWN", "alpine-3.19.iso")
@@ -676,7 +676,7 @@ class TestStrategyDispatchTerminates(unittest.TestCase):
676
676
  offenders.append(test)
677
677
  self.assertEqual(offenders, [], f"branches that fall through: {offenders}")
678
678
 
679
- def test_all_six_strategies_are_present(self):
679
+ def test_all_strategies_are_present(self):
680
680
  tests = [ast.unparse(n.test) for n in self._dispatch_chain()]
681
681
  for strategy in (
682
682
  "direct_match",
@@ -685,6 +685,7 @@ class TestStrategyDispatchTerminates(unittest.TestCase):
685
685
  "nixos_channel",
686
686
  "popos_api",
687
687
  "tails_api",
688
+ "elementary_page",
688
689
  ):
689
690
  with self.subTest(strategy=strategy):
690
691
  self.assertTrue(
@@ -1610,6 +1611,38 @@ class TestNixosChecksumUrls(unittest.TestCase):
1610
1611
  print("NixOS checksums resolve to releases.nixos.org")
1611
1612
 
1612
1613
 
1614
+ class TestKaliProvider(unittest.TestCase):
1615
+ """Kali uses the flat current/ index; select only the x86_64 installer."""
1616
+
1617
+ def _settings(self) -> dict:
1618
+ return load_config()["distros"]["Kali"]
1619
+
1620
+ def test_regex_selects_installer_amd64_only(self):
1621
+ regex = self._settings()["iso_regex"]
1622
+ html = (
1623
+ '<a href="kali-linux-2026.3-hyperv-amd64.7z">vm</a>'
1624
+ '<a href="kali-linux-2026.3-installer-amd64.iso">iso</a>'
1625
+ '<a href="kali-linux-2026.3-installer-arm64.iso">arm</a>'
1626
+ '<a href="kali-linux-2026.3-installer-netinst-amd64.iso">net</a>'
1627
+ '<a href="kali-linux-2026.3-installer-purple-amd64.iso">purple</a>'
1628
+ '<a href="kali-linux-2026.3-live-amd64.iso.torrent">live</a>'
1629
+ )
1630
+ self.assertEqual(
1631
+ re.findall(regex, html), ["kali-linux-2026.3-installer-amd64.iso"]
1632
+ )
1633
+
1634
+ def test_checksum_url_expands_to_sums_file(self):
1635
+ entry = self._settings()
1636
+ url = expand_url(
1637
+ entry["checksum_url"],
1638
+ "kali-linux-2026.3-installer-amd64.iso",
1639
+ entry["base_url"],
1640
+ )
1641
+ self.assertEqual(url, "https://cdimage.kali.org/current/SHA256SUMS")
1642
+ self.assertEqual(entry["checksum_format"], "sha256sums")
1643
+ self.assertEqual(entry["checksum_algo"], "sha256")
1644
+
1645
+
1613
1646
  # ── Distro identity: variant keys and config/name consistency ────────────────
1614
1647
 
1615
1648
  ISO_VID = 32808
@@ -1641,6 +1674,7 @@ class TestVariantKey(unittest.TestCase):
1641
1674
  cases = {
1642
1675
  "Pop_OS 24.04 amd64": "pop-os",
1643
1676
  "ARCH_202610": "arch",
1677
+ "COS_260809": "cachyos",
1644
1678
  "Fedora-E-dvd-x86_64-44": "fedora-e-dvd",
1645
1679
  "Fedora-KDE-Live-44": "fedora-kde-live",
1646
1680
  "Ubuntu-Server 26.04.1 LTS amd64": "ubuntu-server",
@@ -1648,6 +1682,10 @@ class TestVariantKey(unittest.TestCase):
1648
1682
  "archlinux-2026.10.01-x86_64.iso": "archlinux",
1649
1683
  "tails-amd64-7.14.img": "tails",
1650
1684
  "ipxe.iso": "ipxe",
1685
+ # The build date is glued to the arch token; without stripping the
1686
+ # leading dot it stayed in the key and two builds never grouped.
1687
+ "elementaryos-8.1-stable-amd64.20260219.iso": "elementaryos-stable",
1688
+ "elementary OS 8.1 amd64": "elementary-os",
1651
1689
  }
1652
1690
  for raw, expected in cases.items():
1653
1691
  with self.subTest(text=raw):
@@ -1702,6 +1740,18 @@ class TestVariantKey(unittest.TestCase):
1702
1740
 
1703
1741
  self.assertFalse(same_variant_prefix("fedora-kde-live", "archlinux"))
1704
1742
 
1743
+ def test_elementary_volume_id_matches_filename_key(self):
1744
+ """The volume ID spells 'elementary OS' while filenames use
1745
+ 'elementaryos', so cleanup must still pair them."""
1746
+ from visync.download import same_variant_prefix, variant_key
1747
+
1748
+ self.assertTrue(
1749
+ same_variant_prefix(
1750
+ variant_key("elementary OS 8.1 amd64"),
1751
+ variant_key("elementaryos-8.1-stable-amd64.20260219.iso"),
1752
+ )
1753
+ )
1754
+
1705
1755
  def test_empty_keys_are_permissive(self):
1706
1756
  from visync.download import same_variant_prefix
1707
1757
 
@@ -1732,6 +1782,42 @@ class TestCleanupDeletionSafety(unittest.TestCase):
1732
1782
  self.assertFalse(old.exists(), "older Pop!_OS build must be removed")
1733
1783
  self.assertTrue(new.exists(), "newest build must survive")
1734
1784
 
1785
+ def test_cleanup_removes_older_cachyos_build(self):
1786
+ """CachyOS volume IDs are abbreviated ("COS_..."), so the filename and
1787
+ volume-ID variant keys only match once the abbreviation is expanded."""
1788
+ from visync.download import _cleanup_old_versions
1789
+
1790
+ with tempfile.TemporaryDirectory() as tmpdir:
1791
+ drive = self._drive(tmpdir)
1792
+ old = _make_iso(drive / "cachyos-desktop-linux-260628.iso", "COS_260628")
1793
+ new = _make_iso(drive / "cachyos-desktop-linux-260809.iso", "COS_260809")
1794
+
1795
+ _cleanup_old_versions(new, drive)
1796
+
1797
+ self.assertFalse(old.exists(), "older CachyOS build must be removed")
1798
+ self.assertTrue(new.exists(), "newest build must survive")
1799
+
1800
+ def test_cleanup_removes_older_elementary_build(self):
1801
+ """A rebuild of the same release has a new build date, not a new
1802
+ release, so the older build must still be recognised as stale."""
1803
+ from visync.download import _cleanup_old_versions
1804
+
1805
+ with tempfile.TemporaryDirectory() as tmpdir:
1806
+ drive = self._drive(tmpdir)
1807
+ old = _make_iso(
1808
+ drive / "elementaryos-8.1-stable-amd64.20260101.iso",
1809
+ "elementary OS 8.1 amd64",
1810
+ )
1811
+ new = _make_iso(
1812
+ drive / "elementaryos-8.1-stable-amd64.20260219.iso",
1813
+ "elementary OS 8.1 amd64",
1814
+ )
1815
+
1816
+ _cleanup_old_versions(new, drive)
1817
+
1818
+ self.assertFalse(old.exists(), "older elementary OS build must be removed")
1819
+ self.assertTrue(new.exists(), "newest build must survive")
1820
+
1735
1821
  def test_cleanup_keeps_different_variants(self):
1736
1822
  """Desktop and server must never be treated as the same variant."""
1737
1823
  from visync.download import _cleanup_old_versions
@@ -1856,6 +1942,7 @@ class TestConfigNameConsistency(unittest.TestCase):
1856
1942
  "Fedora-Workstation-Live-44-1.7.aarch64.iso",
1857
1943
  ),
1858
1944
  "ArchLinux": ("ARCH_202610", "archlinux-2026.10.01-x86_64.iso"),
1945
+ "CachyOS": ("COS_202608", "cachyos-desktop-linux-260809.iso"),
1859
1946
  "UbuntuServer": (
1860
1947
  "Ubuntu-Server 26.04.1 LTS amd64",
1861
1948
  "ubuntu-26.04.1-live-server-amd64.iso",
@@ -1864,6 +1951,10 @@ class TestConfigNameConsistency(unittest.TestCase):
1864
1951
  "Ubuntu 26.04.1 LTS amd64",
1865
1952
  "ubuntu-26.04.1-desktop-amd64.iso",
1866
1953
  ),
1954
+ "LinuxMint": (
1955
+ "Linux Mint 22.1 Cinnamon 64-bit",
1956
+ "linuxmint-22.1-cinnamon-64bit.iso",
1957
+ ),
1867
1958
  "ParrotSecurity": ("Parrot", "Parrot-security-7.4_amd64.iso"),
1868
1959
  "NixOS": ("NIXOS_26.05_x86_64", "nixos-minimal-26.05.11045-x86_64-linux.iso"),
1869
1960
  "NixOSGraphical": (
@@ -1873,6 +1964,11 @@ class TestConfigNameConsistency(unittest.TestCase):
1873
1964
  "PopOS": ("Pop_OS 24.04 amd64", "pop-os_24.04_amd64_generic_24.iso"),
1874
1965
  "Pond": ("", "pond-installer-0.1.4-x86_64.iso"),
1875
1966
  "Tails": ("", "tails-amd64-7.14.img"),
1967
+ "Kali": ("Kali Linux 2026.3", "kali-linux-2026.3-installer-amd64.iso"),
1968
+ "ElementaryOS": (
1969
+ "elementary OS 8.1 amd64",
1970
+ "elementaryos-8.1-stable-amd64.20260219.iso",
1971
+ ),
1876
1972
  }
1877
1973
 
1878
1974
  def test_every_clean_name_is_identifiable(self):
@@ -14,6 +14,9 @@ from visync.verify import (
14
14
  ChecksumUnavailable,
15
15
  compute_iso_hash,
16
16
  expand_url,
17
+ extract_iso_metadata,
18
+ extract_version_from_filename,
19
+ parse_elementary_checksum,
17
20
  parse_gpg_checksum,
18
21
  parse_hashsums,
19
22
  parse_tails_json,
@@ -307,6 +310,110 @@ class TestParseTailsJson(unittest.TestCase):
307
310
  self.assertIsNone(parse_tails_json(json.dumps(data)))
308
311
 
309
312
 
313
+ class TestParseElementaryChecksum(unittest.TestCase):
314
+ """The installation guide is prose; only a digest tied to the exact ISO
315
+ filename may be used, and an ambiguous match must stay unverified."""
316
+
317
+ AMD64 = "bda93040d08c05911fb159f8150bf8f4ef2db6567ef6e2acd197cb6f395d3446"
318
+ ARM64 = "85116d48c406ae7cd60c936050a099d4b8610321273f6f0a694796db4d4e86ba"
319
+
320
+ PAGE = (
321
+ "<pre><code>CertUtil -hashfile Downloads\\"
322
+ "elementaryos-8.1-stable-amd64.20260219.iso sha256</code></pre>"
323
+ "<p>It should produce the output:</p>"
324
+ "<pre><code>SHA256 hash of Downloads\\"
325
+ "elementaryos-8.1-stable-amd64.20260219.iso:\n"
326
+ f"{AMD64}</code></pre>"
327
+ "<p>If you are using the image for ARM systems:</p>"
328
+ "<pre><code>CertUtil -hashfile Downloads\\"
329
+ "elementaryos-8.1-stable-arm64.20260219.iso sha256\n"
330
+ "SHA256 hash of Downloads\\"
331
+ "elementaryos-8.1-stable-arm64.20260219.iso:\n"
332
+ f"{ARM64}</code></pre>"
333
+ "<pre><code>sha256sum elementaryos-8.1-stable-amd64.20260219.iso</code></pre>"
334
+ "<p>It should produce the output:</p>"
335
+ f"<pre><code>{AMD64}</code></pre>"
336
+ )
337
+
338
+ def test_selects_digest_for_exact_amd64_filename(self) -> None:
339
+ _section("parse_elementary_checksum: amd64")
340
+ result = parse_elementary_checksum(
341
+ self.PAGE, "elementaryos-8.1-stable-amd64.20260219.iso"
342
+ )
343
+ self.assertEqual(result, self.AMD64)
344
+ _ok("amd64 digest selected, arm64 digest ignored")
345
+
346
+ def test_selects_digest_for_exact_arm64_filename(self) -> None:
347
+ result = parse_elementary_checksum(
348
+ self.PAGE, "elementaryos-8.1-stable-arm64.20260219.iso"
349
+ )
350
+ self.assertEqual(result, self.ARM64)
351
+ _ok("arm64 digest selected independently")
352
+
353
+ def test_missing_filename_returns_none(self) -> None:
354
+ self.assertIsNone(
355
+ parse_elementary_checksum(
356
+ self.PAGE, "elementaryos-8.2-stable-amd64.20260301.iso"
357
+ )
358
+ )
359
+ _ok("Absent filename yields None (unavailable, keep the file)")
360
+
361
+ def test_ambiguous_digests_return_none(self) -> None:
362
+ page = (
363
+ f"elementaryos-8.1-stable-amd64.20260219.iso\n{self.AMD64}\n{self.ARM64}\n"
364
+ )
365
+ self.assertIsNone(
366
+ parse_elementary_checksum(
367
+ page, "elementaryos-8.1-stable-amd64.20260219.iso"
368
+ )
369
+ )
370
+ _ok("Two different digests for one filename are refused")
371
+
372
+ def test_wrong_algorithm_returns_none(self) -> None:
373
+ self.assertIsNone(
374
+ parse_elementary_checksum(
375
+ self.PAGE,
376
+ "elementaryos-8.1-stable-amd64.20260219.iso",
377
+ "sha512",
378
+ )
379
+ )
380
+ _ok("Only the published SHA-256 algorithm is accepted")
381
+
382
+ def test_non_elementary_filename_returns_none(self) -> None:
383
+ self.assertIsNone(parse_elementary_checksum(self.PAGE, "other.iso"))
384
+
385
+
386
+ class TestElementaryVersion(unittest.TestCase):
387
+ def test_release_and_build_are_combined(self) -> None:
388
+ _section("elementary OS version: release + build date")
389
+ self.assertEqual(
390
+ extract_version_from_filename("elementaryos-8.1-stable-amd64.20260219.iso"),
391
+ "8.1.20260219",
392
+ )
393
+ _ok("8.1.20260219 compares above an older build of 8.1")
394
+
395
+ def test_newer_release_sorts_above_newer_build(self) -> None:
396
+ from visync.verify import compare_versions
397
+
398
+ self.assertGreater(
399
+ compare_versions("8.2.20260301", "8.1.20260219"),
400
+ 0,
401
+ )
402
+ self.assertGreater(
403
+ compare_versions("8.1.20260219", "8.1.20260101"),
404
+ 0,
405
+ )
406
+ self.assertEqual(
407
+ compare_versions("8.1.20260219", "8.1.20260219"),
408
+ 0,
409
+ )
410
+ _ok("Release and build are both part of the comparison")
411
+
412
+ def test_metadata_carries_combined_version(self) -> None:
413
+ meta = extract_iso_metadata("elementaryos-8.1-stable-amd64.20260219.iso")
414
+ self.assertEqual(meta["version"], "8.1.20260219")
415
+
416
+
310
417
  class TestExpandUrl(unittest.TestCase):
311
418
  def test_substitutes_iso_name(self) -> None:
312
419
  _section("expand_url: Template Substitution")
@@ -339,6 +446,22 @@ class TestExpandUrl(unittest.TestCase):
339
446
  self.assertEqual(result, "https://releases.ubuntu.com/24.04.4/SHA256SUMS")
340
447
  _ok("Substituted {version}")
341
448
 
449
+ def test_cachyos_checksum_sidecar_url_and_digest(self) -> None:
450
+ from visync.finder import load_config
451
+
452
+ _section("expand_url: CachyOS .iso.sha256 sidecar")
453
+ settings = load_config()["distros"]["CachyOS"]
454
+ iso = "cachyos-desktop-linux-260809.iso"
455
+ digest = "959f6577f45e25ee9fd8c220fd221b08e4ea79412c7315c0f922dd6d86d5e33c"
456
+ url = expand_url(settings["checksum_url"], iso, settings["base_url"])
457
+ self.assertEqual(
458
+ url,
459
+ "https://mirror.cachyos.org/ISO/desktop/260809/"
460
+ "cachyos-desktop-linux-260809.iso.sha256",
461
+ )
462
+ self.assertEqual(parse_hashsums(f"{digest} {iso}\n", iso), digest)
463
+ _ok("CachyOS checksum URL and sidecar digest resolve")
464
+
342
465
 
343
466
  class TestVerifyIso(unittest.TestCase):
344
467
  def _make_iso(self, tmpdir: Path, data: bytes) -> Path:
@@ -324,7 +324,7 @@ wheels = [
324
324
 
325
325
  [[package]]
326
326
  name = "visync"
327
- version = "1.0.1"
327
+ version = "1.1.0"
328
328
  source = { editable = "." }
329
329
  dependencies = [
330
330
  { name = "rich" },
@@ -0,0 +1,3 @@
1
+ """Visync - Ventoy ISO Manager & Synchronization Tool"""
2
+
3
+ __version__ = "1.1.0"
@@ -12,9 +12,10 @@ import urllib.error
12
12
  import urllib.request
13
13
  from collections.abc import Callable
14
14
  from enum import StrEnum
15
+ from html import unescape as _html_unescape
15
16
  from pathlib import Path
16
17
  from typing import NamedTuple
17
- from urllib.parse import urlparse
18
+ from urllib.parse import unquote, urlparse
18
19
 
19
20
  from rich.markup import escape as _esc
20
21
 
@@ -43,7 +44,12 @@ from visync.output import (
43
44
  success,
44
45
  warn,
45
46
  )
46
- from visync.verify import compare_versions, extract_version_from_filename, parse_version
47
+ from visync.verify import (
48
+ compare_versions,
49
+ extract_version_from_filename,
50
+ parse_elementary_checksum,
51
+ parse_version,
52
+ )
47
53
 
48
54
  DEBUG = os.environ.get("VISYNC_DEBUG", "0") == "1"
49
55
 
@@ -224,6 +230,155 @@ def _nixos_stable_channel(settings: dict) -> tuple[str, str]:
224
230
  return max(channels, key=_key), ""
225
231
 
226
232
 
233
+ ELEMENTARY_HOME = "https://elementary.io/"
234
+ ELEMENTARY_DOWNLOAD_HOST = "dl.elementaryos.org"
235
+ # The selected image is the stable amd64 build: elementaryos-<release>-stable-amd64.<build>.iso.
236
+ # The homepage also links an arm64 image and a magnet URI that carries the same
237
+ # temporary token, so the architecture and filename are part of the match.
238
+ _ELEMENTARY_AMD64_ISO_RE = re.compile(
239
+ r"^elementaryos-\d+(?:\.\d+)*-stable-amd64\.\d{8}\.iso$", re.IGNORECASE
240
+ )
241
+
242
+
243
+ def _html_attr(tag: str, name: str) -> str:
244
+ """Read one HTML attribute, accepting either quote style."""
245
+ match = re.search(
246
+ rf"""\b{re.escape(name)}\s*=\s*(["'])(.*?)\1""",
247
+ tag,
248
+ re.IGNORECASE | re.DOTALL,
249
+ )
250
+ return match.group(2) if match else ""
251
+
252
+
253
+ def _is_elementary_amd64_url(url: str) -> bool:
254
+ """True only for an HTTPS stable-amd64 ISO on dl.elementaryos.org.
255
+
256
+ The hostname is compared exactly, not by suffix: a lookalike such as
257
+ ``dl.elementaryos.org.example.com`` must be refused. Credentials and
258
+ non-standard ports are refused too, and the filename must match the
259
+ upstream elementary OS naming scheme.
260
+ """
261
+ try:
262
+ parsed = urlparse(url)
263
+ port = parsed.port
264
+ except ValueError:
265
+ return False
266
+ if parsed.scheme.lower() != "https":
267
+ return False
268
+ if (parsed.hostname or "").lower() != ELEMENTARY_DOWNLOAD_HOST:
269
+ return False
270
+ if parsed.username is not None or parsed.password is not None:
271
+ return False
272
+ if port not in (None, 443):
273
+ return False
274
+ filename = _safe_filename(unquote(parsed.path))
275
+ return bool(_ELEMENTARY_AMD64_ISO_RE.fullmatch(filename))
276
+
277
+
278
+ def _extract_elementary_amd64_url(page: str) -> str:
279
+ """Find the stable amd64 download href in elementary's homepage HTML.
280
+
281
+ The download button is an ``<a>`` with ``download-link`` and ``x86``
282
+ classes, but the magnet button carries those classes too. Only an href that
283
+ itself validates as an HTTPS amd64 ISO URL is accepted, so the magnet link
284
+ and the arm64 button are skipped. The href is returned verbatim: its
285
+ base64-looking token is part of the temporary download URL and must never
286
+ be reconstructed or cached.
287
+ """
288
+ hrefs: list[str] = []
289
+ for tag in re.findall(r"<a\b[^>]*>", page, flags=re.IGNORECASE):
290
+ classes = set(_html_attr(tag, "class").split())
291
+ href = _html_unescape(_html_attr(tag, "href").strip())
292
+ if href and {"download-link", "x86"}.issubset(classes):
293
+ hrefs.append(href)
294
+
295
+ # Fallback for a markup change that drops the button classes: consider
296
+ # every href and let the URL validator pick the stable amd64 image.
297
+ for _quote, href in re.findall(
298
+ r"""\bhref\s*=\s*(["'])(.*?)\1""", page, re.IGNORECASE
299
+ ):
300
+ hrefs.append(_html_unescape(href.strip()))
301
+
302
+ for href in hrefs:
303
+ if _is_elementary_amd64_url(href):
304
+ return href
305
+ return ""
306
+
307
+
308
+ def _probe_elementary_download(url: str) -> tuple[bool, str]:
309
+ """HEAD-probe a resolved elementary link so an expired token is caught early.
310
+
311
+ urllib follows the 307 to the storage backend, so a valid token ends at a
312
+ 2xx response. A failure is reported rather than raised; the caller refreshes
313
+ the homepage once and tries the newly resolved link.
314
+ """
315
+ try:
316
+ require_https(url, "ISO download")
317
+ request = urllib.request.Request(
318
+ url, method="HEAD", headers={"User-Agent": "Mozilla/5.0"}
319
+ )
320
+ with urllib.request.urlopen( # require_https above is the allowlist
321
+ request, timeout=MIRROR_HTTP_TIMEOUT
322
+ ) as response:
323
+ status = getattr(response, "status", 200)
324
+ if 200 <= status < 400:
325
+ return True, ""
326
+ return False, f"HEAD probe returned HTTP {status}"
327
+ except urllib.error.HTTPError as e:
328
+ return False, f"HEAD probe returned HTTP {e.code}"
329
+ except Exception as e:
330
+ return False, f"HEAD probe failed: {e}"
331
+
332
+
333
+ def _resolve_elementary_download(settings: dict) -> tuple[str, str, str]:
334
+ """Resolve a fresh stable amd64 URL, refreshing once if it has expired.
335
+
336
+ Returns ``(filename, url, reason)``; *reason* is non-empty on failure. The
337
+ homepage is fetched on every call, so no token is ever cached, generated, or
338
+ hardcoded. If the extracted link fails its HEAD probe (an expired token, a
339
+ stale page, or a transient probe failure), the homepage is fetched once more
340
+ and the fresh link is tried. The URL is returned exactly as published.
341
+ """
342
+ base_url = str(settings.get("base_url") or ELEMENTARY_HOME)
343
+ reason = ""
344
+ for _attempt in range(2):
345
+ page = fetch_html(base_url)
346
+ if not page:
347
+ reason = f"could not fetch {base_url}"
348
+ continue
349
+ url = _extract_elementary_amd64_url(page)
350
+ if not url:
351
+ reason = f"no stable amd64 download link found on {base_url}"
352
+ continue
353
+ if not _is_elementary_amd64_url(url):
354
+ reason = f"refusing untrusted elementary download URL {url!r}"
355
+ continue
356
+ ok, probe_reason = _probe_elementary_download(url)
357
+ if ok:
358
+ filename = _safe_filename(unquote(urlparse(url).path))
359
+ return filename, url, ""
360
+ reason = probe_reason
361
+ _debug(f"elementary download link rejected, refreshing: {probe_reason}")
362
+ return "", "", reason or "could not resolve an elementary download link"
363
+
364
+
365
+ def _elementary_checksum_for(settings: dict, filename: str) -> str:
366
+ """Return the SHA-256 the installation guide publishes for *filename*.
367
+
368
+ An empty string means the guide could not be read or the digest was absent
369
+ or ambiguous. Callers keep the download and let the normal unverified-file
370
+ policy handle it; HTTPS alone is never treated as integrity verification.
371
+ """
372
+ checksum_url = str(settings.get("checksum_url") or "")
373
+ if not checksum_url:
374
+ return ""
375
+ page = fetch_html(checksum_url)
376
+ if not page:
377
+ _debug(f"elementary checksum page unavailable: {checksum_url}")
378
+ return ""
379
+ return parse_elementary_checksum(page, filename, "sha256") or ""
380
+
381
+
227
382
  def process_scraping_strategy(name: str, settings: dict) -> tuple[str, str]:
228
383
  """Resolve specific folder parsing pipelines based on the configured strategy.
229
384
 
@@ -420,6 +575,24 @@ def process_scraping_strategy(name: str, settings: dict) -> tuple[str, str]:
420
575
  except Exception as e:
421
576
  return fail(f"HEAD probe failed for {iso_url}: {e}")
422
577
 
578
+ # Strategy: elementary OS homepage link + installation-guide checksum
579
+ if strategy == "elementary_page":
580
+ if not base_url:
581
+ warn(f"{name} — elementary_page requires base_url")
582
+ return fail("config incomplete: needs base_url")
583
+ filename, url, reason = _resolve_elementary_download(settings)
584
+ if not filename:
585
+ warn(f"{name} — {reason}")
586
+ return fail(reason)
587
+ # A previous resolution in this process may have stashed a digest. Drop
588
+ # it before reading the guide so an unavailable checksum cannot silently
589
+ # reuse an older image's digest.
590
+ settings.pop("resolved_checksum", None)
591
+ checksum = _elementary_checksum_for(settings, filename)
592
+ if checksum:
593
+ settings["resolved_checksum"] = checksum
594
+ return filename, url
595
+
423
596
  if strategy == "content_disposition":
424
597
  requirements = ["base_url", "iso_regex"]
425
598
  if not base_url or not iso_regex:
@@ -1079,12 +1252,21 @@ _ARCH_IN_KEY_RE = re.compile(
1079
1252
  re.IGNORECASE,
1080
1253
  )
1081
1254
  # Version tokens: pure numbers, optionally dotted, tolerating a trailing
1082
- # separator left behind by a stripped arch token ("live-1.7.").
1083
- _VERSION_IN_KEY_RE = re.compile(r"^\d+(?:\.\d+)*\.?$")
1255
+ # separator left behind by a stripped arch token ("live-1.7."). The leading dot
1256
+ # matters for elementary OS, whose build date is glued to the arch as
1257
+ # "…-amd64.20260219"; without it the build date became part of the variant key
1258
+ # and two builds of the same release never grouped for cleanup.
1259
+ _VERSION_IN_KEY_RE = re.compile(r"^\.?\d+(?:\.\d+)*\.?$")
1084
1260
  # Release-type words that appear in volume IDs but never distinguish a variant.
1085
1261
  _RELEASE_WORD_RE = re.compile(
1086
1262
  r"^(?:lts|esd|point|pre|rc|beta|alpha|rc\d*)$", re.IGNORECASE
1087
1263
  )
1264
+ # Volume IDs sometimes abbreviate the distro name. CachyOS publishes
1265
+ # "COS_260809" while its filename is "cachyos-desktop-linux-260809.iso", so
1266
+ # without expanding the abbreviation the cleanup pre-filter rejects every
1267
+ # candidate and old CachyOS builds are never removed. Only the leading token is
1268
+ # expanded; the confirmation step still compares distro and full stem.
1269
+ _VARIANT_TOKEN_ALIASES = {"cos": "cachyos"}
1088
1270
 
1089
1271
 
1090
1272
  def variant_key(text: str) -> str:
@@ -1108,6 +1290,7 @@ def variant_key(text: str) -> str:
1108
1290
  'pop-os_24.04_amd64_generic_24.iso' -> 'pop-os-generic'
1109
1291
  'Ubuntu-Server 26.04.1 LTS amd64' -> 'ubuntu-server'
1110
1292
  'ubuntu-24.04.1-live-server-amd64.iso' -> 'ubuntu-live-server'
1293
+ 'COS_260809' -> 'cachyos'
1111
1294
  """
1112
1295
  stem = re.sub(r"\.(iso|img)$", "", text, flags=re.IGNORECASE)
1113
1296
  # Remove arch tokens with their surrounding separator so "…-amd64" does not
@@ -1122,6 +1305,8 @@ def variant_key(text: str) -> str:
1122
1305
  if _RELEASE_WORD_RE.fullmatch(token):
1123
1306
  continue
1124
1307
  tokens.append(token)
1308
+ if tokens and tokens[0] in _VARIANT_TOKEN_ALIASES:
1309
+ tokens[0] = _VARIANT_TOKEN_ALIASES[tokens[0]]
1125
1310
  return "-".join(tokens)
1126
1311
 
1127
1312
 
@@ -108,6 +108,15 @@ _ARCH_TOKEN_RE = re.compile(
108
108
  r"x86[_-]?64|amd64|aarch64|arm64|armhfp|i[36]86|riscv64|x86", re.IGNORECASE
109
109
  )
110
110
  _VERSION_TOKEN_RE = re.compile(r"\d+(?:\.\d+)*")
111
+ # elementary OS names its images "elementaryos-<release>-stable-<arch>.<build>.iso",
112
+ # e.g. elementaryos-8.1-stable-amd64.20260219.iso. The release alone is not
113
+ # enough to detect updates: upstream rebuilds the same release with a new build
114
+ # date. Both parts are returned as one comparable version so a rebuild sorts
115
+ # above the previous image.
116
+ _ELEMENTARY_ISO_RE = re.compile(
117
+ r"^elementaryos-(\d+(?:\.\d+)*)-stable-[a-z0-9_]+\.(\d{8})\.iso$",
118
+ re.IGNORECASE,
119
+ )
111
120
 
112
121
 
113
122
  def extract_version_from_filename(filename: str) -> str:
@@ -119,6 +128,12 @@ def extract_version_from_filename(filename: str) -> str:
119
128
  dotted numeric run for names like 'nixos-minimal-26.05.1947.a037-x86_64-linux.iso'.
120
129
  Returns the raw version substring or empty string if no numeric version found.
121
130
  """
131
+ elementary = _ELEMENTARY_ISO_RE.match(filename)
132
+ if elementary:
133
+ # Keep the build date in the version: 8.1.20260219 sorts above
134
+ # 8.1.20260101, so a rebuild of the same release is an update.
135
+ return f"{elementary.group(1)}.{elementary.group(2)}"
136
+
122
137
  stem = re.sub(r"\.(iso|img)$", "", filename, flags=re.IGNORECASE)
123
138
  stem = _ARCH_TOKEN_RE.sub("-", stem)
124
139
  for token in re.split(r"[\s_\-]+", stem):
@@ -390,11 +405,55 @@ def parse_tails_json(
390
405
  return digest or None
391
406
 
392
407
 
408
+ def parse_elementary_checksum(
409
+ content: str, iso_name: str, algo: str = "sha256"
410
+ ) -> str | None:
411
+ """Parse elementary OS's installation guide for a filename-keyed SHA-256.
412
+
413
+ The guide is prose, not a sums file. It repeats the digest next to commands
414
+ such as ``sha256sum elementaryos-...iso`` and labels such as
415
+ ``SHA256 hash of Downloads\\elementaryos-...iso:``. A digest is accepted
416
+ only when it appears after the exact selected filename and before the next
417
+ ISO name, so the arm64 image's digest can never be attributed to the amd64
418
+ one. Repeated copies of the same digest are fine (the guide repeats each
419
+ platform's instructions). Two *different* digests for one filename are
420
+ ambiguous: returning None keeps the download UNVERIFIED instead of guessing.
421
+ """
422
+ if algo.strip().lower().replace("-", "") != "sha256":
423
+ return None
424
+ if not iso_name or not _ELEMENTARY_ISO_RE.fullmatch(iso_name):
425
+ return None
426
+ want = _hex_len_for(algo)
427
+ if want is None:
428
+ return None
429
+
430
+ digests: set[str] = set()
431
+ found_name = False
432
+ for match in re.finditer(re.escape(iso_name), content, re.IGNORECASE):
433
+ found_name = True
434
+ start = match.end()
435
+ next_iso = re.search(r"\.iso\b", content[start:], re.IGNORECASE)
436
+ end = start + next_iso.start() if next_iso else len(content)
437
+ # The cap guards against a page that omits the next filename entirely:
438
+ # without it a later image's digest could fall into this window.
439
+ window = content[start : min(end, start + 512)]
440
+ for digest_match in re.finditer(
441
+ r"(?<![0-9a-fA-F])([0-9a-fA-F]{64})(?![0-9a-fA-F])", window
442
+ ):
443
+ digests.add(digest_match.group(1).lower())
444
+
445
+ if not found_name or len(digests) != 1:
446
+ return None
447
+ digest = next(iter(digests))
448
+ return digest if len(digest) == want else None
449
+
450
+
393
451
  FORMAT_PARSERS = {
394
452
  "gpg_checksum": parse_gpg_checksum,
395
453
  "sha256sums": parse_hashsums,
396
454
  "sha1sums": parse_hashsums,
397
455
  "json": parse_tails_json,
456
+ "elementary_docs": parse_elementary_checksum,
398
457
  }
399
458
 
400
459
 
@@ -530,9 +589,19 @@ def extract_iso_metadata(iso_name: str) -> dict[str, str]:
530
589
  meta["release"] = f"{channel}.{nixos.group(2)}.{nixos.group(3)}"
531
590
  return meta
532
591
 
592
+ elementary = _ELEMENTARY_ISO_RE.match(iso_name)
593
+ if elementary:
594
+ meta["version"] = f"{elementary.group(1)}.{elementary.group(2)}"
595
+ return meta
596
+
533
597
  generic = re.search(r"(\d+\.\d+(?:\.\d+)?)", iso_name)
534
598
  if generic:
535
599
  meta["version"] = generic.group(1)
600
+ else:
601
+ # Date-versioned releases such as CachyOS use YYMMDD directories.
602
+ dated = re.search(r"(?<!\d)(\d{6})(?!\d)", iso_name)
603
+ if dated:
604
+ meta["version"] = dated.group(1)
536
605
  return meta
537
606
 
538
607
 
@@ -1,3 +0,0 @@
1
- """Visync - Ventoy ISO Synchronization Tool."""
2
-
3
- __version__ = "1.0.1"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes