feat: add manual CPAN port update pipeline

[fglock]

Summary

Add a manual CPAN-port update pipeline, parallel to dev/import-perl5/sync.pl, for externally ported CPAN distributions maintained in PerlOnJava.

Perl-core and dual-life modules already imported through dev/import-perl5/sync.pl remain owned by that workflow. Scheduled checks and automated pull requests are out of scope for this first version.

Proposed interface

Add dev/import-cpan/sync.pl plus a declarative config.yaml registry of maintained CPAN ports.

The command should support:

• --check: query and stage updates without modifying tracked files
• --only <distribution>: process one registered distribution
• --apply: apply an update only after all staging and validation gates pass

Use MetaCPAN's latest stable, non-developer release as the default source.

Registry and update modes

Each entry should record:

• CPAN distribution and primary module names
• currently imported upstream release
• port mode
• source, test, and support-file mappings
• fixture directory under src/test/resources/module/
• version targets
• optional PerlOnJava patches

Support two port modes:

1. Full import: refresh declared vendored Perl sources and upstream test/support files, then reapply any PerlOnJava patches.
2. Rewritten port: preserve the PerlOnJava implementation, refresh upstream test/support files, and update only declared module version targets.

Import patches for this pipeline should have their own location under dev/import-cpan/; they must remain separate from Perl 5 import patches and the CPAN distroprefs/patches shipped for end-user jcpan installs.

Test synchronization and audit

• Refresh every manifest-declared test/support path exactly from the selected release.
• Report newly added upstream tests that are not yet selected, so maintainers can decide whether to adopt them.
• Fail if a tracked fixture cannot be traced to the staged release.
• Audit that every refreshed runnable .t file is discovered by ModuleTestExecutionTest and therefore executed by make test-bundled-modules.
• Allow exceptions only through the existing documented bundled-test skip mechanism.

Safe update sequence

For each candidate release:

1. Download and unpack it outside the working checkout, validating release metadata/checksums.
2. Apply configured PerlOnJava patches in staging; abort if any patch no longer applies.
3. Run the selected/upstream tests with system Perl to verify that the release itself is healthy.
4. Run the staged sources and the same tests with the current jperl.
5. Apply the candidate update in an isolated temporary Git worktree.
6. Run make in that immutable worktree.
7. Run make test-bundled-modules and verify the refreshed tests were discovered and executed.
8. Copy the resulting diff to the developer's checkout and update the registry version only when every gate passes.

Any download, patch, test, build, or audit failure must leave the developer's tracked files unchanged and retain useful logs/diffs.

Tests for the updater

• Manifest parsing and validation
• Latest stable release selection, excluding trial/developer releases
• Distribution/package name mismatches
• Full-import and rewritten-port behavior
• Version replacement and --only filtering
• Test/support fixture synchronization and provenance audit
• Detection of undiscovered runnable .t files
• Failure atomicity for download, checksum, patch, Perl, jperl, build, and bundled-test failures

Documentation

Document manual operation and clearly distinguish this pipeline from:

• dev/import-perl5/sync.pl
• bundled CPAN distroprefs and tarball patches used by jcpan
• make test-bundled-modules

Acceptance criteria

• At least one full-import port and one rewritten port are registered as end-to-end examples.
• A newer stable CPAN release can be detected, staged, validated, and applied manually.
• Rewritten Java/PerlOnJava implementations are never overwritten by upstream source synchronization.
• Updated test fixtures are proven to originate from the selected release and are exercised by make test-bundled-modules.
• Failed updates make no tracked working-tree changes.