npm - cornhsu-polymigrate - Versions diffs - 2.3.1 → 3.0.0 - Mend

cornhsu-polymigrate 2.3.1 → 3.0.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.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -3,27 +3,39 @@
 [![NuGet](https://img.shields.io/nuget/v/Cornhsu.PolyMigrate.svg?label=Cornhsu.PolyMigrate)](https://www.nuget.org/packages/Cornhsu.PolyMigrate)
 [![Downloads](https://img.shields.io/nuget/dt/Cornhsu.PolyMigrate.svg)](https://www.nuget.org/packages/Cornhsu.PolyMigrate)
 [![CI](https://github.com/HSU-YU-MING/cornhsu-polymigrate/actions/workflows/ci.yml/badge.svg)](https://github.com/HSU-YU-MING/cornhsu-polymigrate/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/HSU-YU-MING/cornhsu-polymigrate/blob/main/LICENSE)
 > **The i18n-first static-site migrator** — the only site migrator that pairs your multilingual pages automatically.
-**[Project write-up](https://cornhsu.com/polymigrate) · [NuGet](https://www.nuget.org/packages/Cornhsu.PolyMigrate) · [繁體中文說明](README.zh-Hant.md) · MIT**
+**[Project write-up](https://cornhsu.com/polymigrate) · [NuGet](https://www.nuget.org/packages/Cornhsu.PolyMigrate) · [繁體中文說明](https://github.com/HSU-YU-MING/cornhsu-polymigrate/blob/main/README.zh-Hant.md) · MIT**
 PolyMigrate turns legacy dynamic sites (old PHP sites and the like) into clean, static-site-ready
 Markdown — and it treats multilingual content as a first-class concern, not an afterthought.
 Config-driven, fully offline-rerunnable, built on .NET.
-**Status: 2.3.** The extraction pipeline, pairing, verification, thumbnails and orphan-page
+**Status: 3.0.** The extraction pipeline, pairing, verification, thumbnails and orphan-page
 recovery are complete and validated against a real full-site migration (see below). The **CLI
-surface and the Phase output contracts remain stable** (unchanged since 1.0): new features bump
-the minor version, fixes bump the patch. 2.0 was an engineering release — it narrowed the
+surface, exit codes, Phase output contracts and YAML config are frozen within a major version**:
+new features bump the minor version, fixes bump the patch, and anything that changes one of those
+four surfaces waits for a major. **3.0 is such a release** — it changes exit codes in a few cases
+so they follow the 0 / 1 / 2 / 130 contract (an orphan probe that got no usable answer, a failed
+npm launcher and an interrupted command no longer look like success), gives each section its own
+orphan slug list (`orphan_slugs.<section>.txt`), keeps animated GIF/WebP thumbnails animated, and
+adds probe/fetch entry points and cancellable overloads to the library. Config fields, CSV columns
+and frontmatter fields are unchanged, but a config with an invalid value (a CSS selector, a regex, a
+path that isn't a single segment, a malformed URL or language tag, a key left without a value…) is now
+rejected when it is loaded, by every command, instead of when some page or command happens to use it, and a probe in
+which only some candidates got no answer exits 1 (the list is written, but may be incomplete).
+**Read the 3.0 upgrade checklist in the CHANGELOG before upgrading**.
+Earlier history: 2.0 was an engineering release — it narrowed the
 `Cornhsu.PolyMigrate.Core` public .NET API to its intended entry points and removed unused
-config fields; 2.1 fixed up the release pipeline (arm64 npm packages, symbol packages).
+config fields; 2.1 fixed up the release pipeline (arm64 npm packages, symbol packages) — though
+the npm launcher could only start the Windows/Linux arm64 builds from 2.3.1 on.
 2.2 closed a blind spot in `verify` — pages nothing links to were reported as fine, because a
 link-following audit never reaches them — and added `slugs` for keeping up with a source site
 that is still being updated. **Upgrading to 2.2 can turn a passing `verify` into exit 1**.
 2.3 reads the source site's own `hreflang` declarations (see below) and reports them in a new
-`hreflang_map.csv`. See the [CHANGELOG](CHANGELOG.md) for the migration notes.
+`hreflang_map.csv`. See the [CHANGELOG](https://github.com/HSU-YU-MING/cornhsu-polymigrate/blob/main/CHANGELOG.md) for the migration notes.
 ## Why
@@ -62,6 +74,8 @@ A declaration is only used for pairing if it:
 - resolves to a page actually in your mirror — **same host included**, since plenty of sites put
   the English version on `en.example.org`, where a path-only comparison would make a page its
   own translation,
+- has a content page at both ends — neither end is a site-level page (a language picker and the
+  like, which isn't anyone's translation),
 - and **isn't one of many same-language pages claiming the same target**. This is the classic
   failure: one `<link>` pasted into the site-wide template, so every Chinese page declares the
   English homepage as its English version. One page cannot be the translation of three others,
@@ -74,7 +88,7 @@ Everything declared — including the rejected ones — is written to `hreflang_
 Pairs are still only ever *suggested*: `hreflang` raises the evidence quality, it does not
 switch the tool into merging pages on its own. That is a deliberate call, not an unfinished
 one — the measurement behind it, and what would have to change to revisit it, are recorded in
-[docs/hreflang_量測與決策.md](docs/hreflang_量測與決策.md).
+[docs/hreflang_量測與決策.md](https://github.com/HSU-YU-MING/cornhsu-polymigrate/blob/main/docs/hreflang_%E9%87%8F%E6%B8%AC%E8%88%87%E6%B1%BA%E7%AD%96.md).
 ## Battle-tested defaults
@@ -123,7 +137,7 @@ Two channels — pick whichever runtime you already have. **Same tool, same beha
 ```
 npx cornhsu-polymigrate extract site.yaml   # Node — no .NET install needed
-dotnet tool install -g Cornhsu.PolyMigrate  # .NET
+dotnet tool install -g Cornhsu.PolyMigrate  # .NET 10
 ```
 > The npm build ships a self-contained native binary and only downloads the one
@@ -134,13 +148,24 @@ dotnet tool install -g Cornhsu.PolyMigrate  # .NET
 ```
 dotnet tool install -g Cornhsu.PolyMigrate
 polymigrate extract site.yaml               # mirror HTML -> frontmatter Markdown + inventories
-polymigrate verify out/                     # link/media/frontmatter/unlinked-page audit, CI exit codes
+polymigrate verify .                        # link/media/frontmatter/unlinked-page audit, CI exit codes
 polymigrate thumbs site.yaml                # EXIF-corrected, width-capped thumbnails
-polymigrate probe-orphans site.yaml --section news --years 2021-2023
-polymigrate fetch-orphans site.yaml --section news
+polymigrate probe-orphans site.yaml --section news --years 2021-2023   # -> orphan_slugs.news.txt
+polymigrate fetch-orphans site.yaml --section news                      # reads orphan_slugs.news.txt
 polymigrate slugs . --section news          # slugs already mirrored under ./raw (pipeable)
 ```
+> **Animated GIF/WebP thumbnails keep every frame — within limits.** Scaling an animation frame by
+> frame costs memory and time in proportion to frames × width × height (measured: a 400-frame
+> 1300×900 GIF took 39 s and 3.2 GB). So an animation over **50 megapixels** in total, or one whose
+> animated thumbnail would be larger than the original, gets a first-frame thumbnail instead — the
+> same result as before 3.0 (an animation that needs no scaling is copied as-is instead). At the limit it takes about 6 s and a 250–400 MB memory peak, depending on the content
+> (two 100-frame 1000×500 GIFs measured 250 MB and 384 MB). The `thumbs` summary lists
+> which files got a first frame and why; neither case is a failure or changes the exit code.
+> Still images get a limit too: one over **179 megapixels** (Pillow's decompression-bomb threshold —
+> a 270 KB GIF can declare 20000×20000, and decoding it took 14.8 s and 1.6 GB) is not decoded at all and
+> counts as a failed thumbnail (exit 1). 100-megapixel camera originals are well within it.
 > **`raw/` is the one thing you cannot regenerate.** Re-crawling a site takes hours at a
 > polite request rate, and the source site may be switched off the moment you finish
 > migrating — at which point your mirror is the only copy left. No PolyMigrate command
@@ -148,10 +173,10 @@ polymigrate slugs . --section news          # slugs already mirrored under ./raw
 > off, and back them up if the source is going away.
 > No .NET? Every command above also runs with **zero install** via npm — just prefix it:
-> `npx cornhsu-polymigrate extract site.yaml`, `npx cornhsu-polymigrate verify out/`, and so on.
+> `npx cornhsu-polymigrate extract site.yaml`, `npx cornhsu-polymigrate verify .`, and so on.
 One YAML config per site describes everything site-specific — see
-[examples/ibps-austin.yaml](examples/ibps-austin.yaml) for a fully-annotated real example.
+[examples/ibps-austin.yaml](https://github.com/HSU-YU-MING/cornhsu-polymigrate/blob/main/examples/ibps-austin.yaml) for a fully-annotated real example.
 ```yaml
 config_version: 1
@@ -185,8 +210,16 @@ if (report.HasErrors) { /* unsafe paths were skipped; see path_issues.csv */ }
 var verify = PolyMigrator.Verify("out/");      // no config needed; reads Phase 2 output only
 Console.WriteLine($"{verify.Errors} errors, {verify.Warnings} warnings");
+// Orphan pages (probe-orphans / fetch-orphans). Nothing is written until you decide to.
+var probe = await migrator.ProbeOrphansAsync("out/", "news", 2021, 2023);
+if (probe.NoUsableAnswers) { /* the site never answered: an empty list means nothing */ }
+else { await migrator.FetchOrphansAsync("out/", "news", probe.Found); }
 ```
+Extract, Verify and GenerateThumbnails also have overloads that take a `CancellationToken`
+(the probe/fetch methods take one as their last parameter).
 ## Layout
 | Path | Contents |
@@ -214,9 +247,9 @@ signals in priority order, why "just read `hreflang`" often misses on real legac
 (measured on one: 528 pages, **0** declarations, sitemap 404), the five gates a declaration has to
 pass before it is usable at all, and why URL string similarity is the wrong tool for this job.
-License: [MIT](LICENSE). All dependencies are MIT/BSD/Apache-2.0
+License: [MIT](https://github.com/HSU-YU-MING/cornhsu-polymigrate/blob/main/LICENSE). All dependencies are MIT/BSD/Apache-2.0
 (imaging via **Magick.NET**; ImageSharp was dropped when its 4.x line began requiring a
-license key at build time). See [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES.md).
+license key at build time). See [THIRD-PARTY-NOTICES](https://github.com/HSU-YU-MING/cornhsu-polymigrate/blob/main/THIRD-PARTY-NOTICES.md).
 PolyMigrate fetches pages from the site you point it at, and can be configured to send
 cookies past a bot challenge. **It assumes the site is yours, or that you are migrating

package/THIRD-PARTY-NOTICES.md CHANGED Viewed

@@ -1,49 +1,307 @@
 # Third-party notices
 PolyMigrate itself is licensed under the [MIT License](LICENSE). It builds on the
-following third-party packages. All of their licences are compatible with MIT, and
-none of them are copyleft.
+third-party components below. All of their licences are compatible with MIT, and none
+of them are copyleft. The full licence texts are at the end of this file.
-| Package | Licence | Project |
+## What each channel ships
+Whether a channel redistributes a component — and so has to carry its notices — depends
+on how it is packaged:
+| Channel | What is inside | Notices shipped with it |
 |---|---|---|
-| AngleSharp | MIT | https://anglesharp.github.io/ |
-| ReverseMarkdown | MIT | https://github.com/mysticmind/reversemarkdown-net |
-| YamlDotNet | MIT | https://github.com/aaubry/YamlDotNet |
-| Magick.NET (`Magick.NET-Q8-AnyCPU`, `Magick.NET.Core`) | Apache-2.0 | https://github.com/dlemstra/Magick.NET |
-## Why this file exists
-For the NuGet packages (`Cornhsu.PolyMigrate`, `Cornhsu.PolyMigrate.Core`) the
-dependencies are resolved by NuGet and each package carries its own licence — nothing
-further is required from us.
-**The npm channel is different.** `cornhsu-polymigrate` ships a self-contained native
-binary that embeds `Magick.Native-Q8-*` directly, which makes it a redistribution of
-Magick.NET and of ImageMagick. Magick.NET is Apache-2.0 and its package includes a
-`Notice.txt`, so section 4(d) of the Apache License applies: that notice must travel
-with the redistribution.
-## Magick.NET / ImageMagick
-> Copyright Dirk Lemstra, https://github.com/dlemstra/Magick.NET
-> Licensed under the Apache License, Version 2.0.
->
-> Bundles ImageMagick, used under the ImageMagick License —
-> https://imagemagick.org/license/
-The full, authoritative notice ships inside the Magick.NET package as `Notice.txt`
-(and covers the exact ImageMagick version bundled by that release). Reproduce that
-file, not this summary, when redistributing.
-**This is automated, not a checklist item.** `npm/prepare.mjs` resolves the actual
-Magick.NET version from `project.assets.json`, reads `Notice.txt` from the NuGet cache,
-and writes it into every platform package as `NOTICE.txt` — **aborting the build if it
-cannot find it**. `release.yml` then verifies the built packages really carry it. A
-licence obligation that depends on someone remembering a checklist is one that will
+| **`Cornhsu.PolyMigrate`** — .NET tool on NuGet | `PackAsTool` puts the whole publish output into the package (`tools/net10.0/any/`): every dependency DLL **and** Magick.NET's native libraries for all platforms (`runtimes/*/native/Magick.Native-Q8-*`, which contain ImageMagick). The tool package itself is a redistribution of all of them. | `NOTICE.txt` (Magick.NET's `Notice.txt`, verbatim) and this file, at the package root |
+| **`Cornhsu.PolyMigrate.Core`** — library on NuGet | `PolyMigrate.Core.dll` only. Its dependencies are declared, not bundled: NuGet resolves them on the consumer's side, and each package carries its own licence. | Nothing further is required |
+| **npm** — `cornhsu-polymigrate` and `@cornhsu/polymigrate-<os>-<cpu>` | Each platform package is a self-contained executable: every dependency DLL, the `Magick.Native-Q8-*` for that platform, **and the .NET runtime**. The main package holds only the launcher script. | Platform packages: `NOTICE.txt`, this file and `LICENSE`. Main package: this file and `LICENSE` |
+## Components
+| Component | Licence | Copyright | Project | Shipped in |
+|---|---|---|---|---|
+| AngleSharp | MIT | Copyright (c) 2013 - 2026 AngleSharp | https://anglesharp.github.io/ | tool, npm |
+| ReverseMarkdown | MIT | Copyright (c) 2015 Babu Annamalai | https://github.com/mysticmind/reversemarkdown-net | tool, npm |
+| YamlDotNet | MIT | Copyright (c) 2008, 2009, 2010, 2011, 2012, 2013, 2014 Antoine Aubry and contributors | https://github.com/aaubry/YamlDotNet | tool, npm |
+| Magick.NET (`Magick.NET-Q8-AnyCPU`, `Magick.NET.Core` and the native `Magick.Native-Q8-*`) | Apache-2.0 | Copyright 2013-2026 Dirk Lemstra | https://github.com/dlemstra/Magick.NET | tool, npm |
+| ImageMagick and the libraries built into `Magick.Native-Q8-*` | ImageMagick License; each bundled library under its own licence | ImageMagick Studio LLC and the respective authors — see `NOTICE.txt` | https://imagemagick.org/ | tool, npm |
+| .NET runtime | MIT | Copyright (c) .NET Foundation and Contributors | https://github.com/dotnet/runtime | npm only |
+The copyright lines are taken from each project's own licence file (Magick.NET: its package
+metadata) at the versions this release resolves: AngleSharp 1.7.2, ReverseMarkdown 6.2.1,
+YamlDotNet 18.1.0, Magick.NET 14.16.0. The exact versions inside a given package are listed
+in its `polymigrate.deps.json`.
+The .NET runtime contains third-party code of its own; its notices are at
+https://github.com/dotnet/runtime/blob/main/THIRD-PARTY-NOTICES.TXT.
+## Magick.NET and ImageMagick: `NOTICE.txt`
+Magick.NET is Apache-2.0 and its package includes a `Notice.txt`, so section 4(d) of the
+Apache License applies: whoever redistributes it must pass that notice on. The file also
+reproduces the ImageMagick License and the licence of every library built into the native
+binaries, for the exact ImageMagick version of that Magick.NET release — which is why the
+packages ship the file itself, not a summary of it.
+**This is automated, not a checklist item.** Both channels that redistribute Magick.NET
+resolve the Magick.NET version that was actually restored, read `Notice.txt` from the NuGet
+cache, and ship it as `NOTICE.txt` — **and fail if they cannot find it**:
+- **tool package:** the `_PackMagickNotice` target in `src/PolyMigrate.Cli/PolyMigrate.Cli.csproj`
+  fails `dotnet pack`;
+- **npm:** `npm/prepare.mjs` aborts, and `release.yml` then checks that every built package
+  really carries `NOTICE.txt` and this file.
+A licence obligation that depends on someone remembering a checklist is one that will
 eventually be missed.
 ## Keeping this current
-This file lists licences as of the versions pinned in `src/*/*.csproj`. **When a
-dependency is added, removed, or bumped to a version with a different licence, update
-this file in the same commit** — Dependabot bumps will not do it for you.
+This file describes what the CLI's build output actually contains
+(`src/PolyMigrate.Cli/bin/Release/net10.0`, listed in `polymigrate.deps.json`), not only what the
+`.csproj` files reference: a build-time package can still leak a runtime DLL into the output.
+**When a dependency is added, removed, or bumped, check the output and update this file in the
+same commit** — Dependabot bumps will not do it for you.
+## Licence texts
+### MIT License
+Applies to AngleSharp, ReverseMarkdown, YamlDotNet and the .NET runtime.
+```text
+MIT License
+Copyright (c) 2013 - 2026 AngleSharp
+Copyright (c) 2015 Babu Annamalai
+Copyright (c) 2008, 2009, 2010, 2011, 2012, 2013, 2014 Antoine Aubry and contributors
+Copyright (c) .NET Foundation and Contributors
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+### Apache License 2.0
+Applies to Magick.NET (`Magick.NET-Q8-AnyCPU`, `Magick.NET.Core` and the native
+`Magick.Native-Q8-*`), Copyright 2013-2026 Dirk Lemstra. ImageMagick and the libraries built
+into the native binaries are under their own licences, reproduced in full in `NOTICE.txt`.
+```text
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+   1. Definitions.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+   END OF TERMS AND CONDITIONS
+   APPENDIX: How to apply the Apache License to your work.
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+   Copyright [yyyy] [name of copyright owner]
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+       http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+```

package/bin/polymigrate.js CHANGED Viewed

@@ -34,13 +34,27 @@ const TARGETS = {
 const key = `${process.platform} ${process.arch}`;
 const target = TARGETS[key];
-if (!target) {
+// 啟動腳本自己失敗 = PolyMigrate 根本沒有執行 = error,所以是 2(3.0 起)。
+// 2.3.1 以前是 1,和 CLI 契約的「1 = 只有 warning」撞號:依「0/1 放行」的 CI 會把「工具沒跑」當成通過
+// (2.1.0~2.3.0 的 arm64 事故走的就是這條路)。訊息用英文(與 CLI 其他輸出一致),明講工具沒有執行。
+const LAUNCHER_FAILURE_EXIT = 2;
+function fail(...lines) {
   console.error(
-    `Cornhsu.PolyMigrate 沒有 ${key} 的預先建置版本。\n` +
-      `目前支援:${Object.keys(TARGETS).join("、")}\n` +
-      `其他平台請改用 .NET 版本:dotnet tool install -g Cornhsu.PolyMigrate`
+    [
+      `error: ${lines[0]} PolyMigrate did not run.`,
+      ...lines.slice(1),
+    ].join("\n")
+  );
+  process.exit(LAUNCHER_FAILURE_EXIT);
+}
+if (!target) {
+  fail(
+    `no prebuilt binary for ${key}.`,
+    `Supported platforms: ${Object.keys(TARGETS).join(", ")}.`,
+    "On other platforms, use the .NET tool instead: dotnet tool install -g Cornhsu.PolyMigrate"
   );
-  process.exit(1);
 }
 let binary;
@@ -50,19 +64,22 @@ try {
   const manifest = require.resolve(`${target.pkg}/package.json`);
   binary = path.join(path.dirname(manifest), "bin", target.bin);
 } catch {
-  console.error(
-    `找不到平台套件 ${target.pkg}。\n` +
-      `可能是安裝時加了 --no-optional,或安裝過程中斷。\n` +
-      `請重新安裝:npm install cornhsu-polymigrate`
+  fail(
+    `the platform package ${target.pkg} is not installed.`,
+    "It is an optional dependency: --no-optional / --omit=optional skips it, or the install was interrupted.",
+    "Reinstall: npm install cornhsu-polymigrate"
   );
-  process.exit(1);
 }
+// Ctrl-C:主控台的 Ctrl-C 同時送給這個 node 行程與子行程(Windows 的主控台群組、Unix 的前景行程群組都是如此)。
+// node 沒有 SIGINT 處理器的話會先被結束——Windows 上結束碼是 0xC000013A,子行程乾淨回的 130 傳不出去。
+// 掛一個什麼都不做的處理器,讓 node 等子行程自己收尾,再原樣轉傳它的 exit code。
+process.on("SIGINT", () => {});
 const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
 if (result.error) {
-  console.error(`無法執行 ${binary}:${result.error.message}`);
-  process.exit(1);
+  fail(`could not start ${binary}: ${result.error.message}.`);
 }
 // 被訊號中斷時 status 會是 null;轉成慣例的 128+signal,別讓 CI 誤判為成功

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "cornhsu-polymigrate",
-  "version": "2.3.1",
+  "version": "3.0.0",
   "description": "The i18n-first static-site migrator — the only one that pairs your multilingual pages automatically. Mirrors a legacy site into frontmatter Markdown, auto-matches language versions, and honestly lists what it could not pair.",
   "keywords": [
     "i18n",
@@ -36,11 +36,11 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@cornhsu/polymigrate-win32-x64": "2.3.1",
-    "@cornhsu/polymigrate-win32-arm64": "2.3.1",
-    "@cornhsu/polymigrate-linux-x64": "2.3.1",
-    "@cornhsu/polymigrate-linux-arm64": "2.3.1",
-    "@cornhsu/polymigrate-darwin-x64": "2.3.1",
-    "@cornhsu/polymigrate-darwin-arm64": "2.3.1"
+    "@cornhsu/polymigrate-win32-x64": "3.0.0",
+    "@cornhsu/polymigrate-win32-arm64": "3.0.0",
+    "@cornhsu/polymigrate-linux-x64": "3.0.0",
+    "@cornhsu/polymigrate-linux-arm64": "3.0.0",
+    "@cornhsu/polymigrate-darwin-x64": "3.0.0",
+    "@cornhsu/polymigrate-darwin-arm64": "3.0.0"
   }
 }