Add Resources API with Path-based methods

[Copilot]

Provide a new Resources API

This PR implements a new Resources API as requested in issue #76, following the same pattern as the Messages and Progress APIs.

Summary of Changes:

✅ New org.codehaus.plexus.build.resources package with:

1. Resources Interface - Modern Path-based API with the following methods:

   • hasDelta(Path file) - Check if file has changes (documented as "best effort" hint)
   • refresh(Path file) - Mark file as modified during build
   • newOutputStream(Path file) - Get output stream with change detection optimization
   • newOutputStream(Path file, boolean derived) - Output stream with optional derived marker
   • isUptodate(Path target, Path source) - Check if target is up-to-date with source (recommended over hasDelta for input/output scenarios)
   • getPath(String relpath) - Convert relative path to Path (now uses Maven project basedir via LegacySupport)
   • markDerived(Path file) - Mark file as generated/derived (IDE integration support)
   • copy(Path source, Path target) - Convenience method to copy only when needed

2. DefaultResources Implementation - Delegates to BuildContext for compatibility

✅ Deprecated resource-related methods in BuildContext:

• hasDelta(String), hasDelta(File), hasDelta(List<String>)
• refresh(File)
• newFileOutputStream(File)
• isUptodate(File, File)

✅ Updated README with documentation for the new Resources API

✅ Key Design Decisions:

• Uses Path instead of File for modern API
• Clarifies hasDelta is "best effort" and isUptodate is preferred for input/output
• Removed scanner methods (developers can use Path API and streams directly)
• Added markDerived for IDE integration to warn users about generated files
• Added copy convenience method that combines isUptodate check with file copying
• getPath now properly resolves against Maven project basedir using LegacySupport (with fallback to CWD)

✅ Build Status: All builds passing with expected deprecation warnings

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Provide a new Resources API</issue_title>
<issue_description>Currently we mix resource changes with logging functions what is quite confusing, beside that the current API has some drawbacks and needs clarification in some cases.

Therefore we should split this into an own package and design a new more modern API (e.g. using Path instead of file, Streams instead of scanners and so on...).

Beside that there is currently a flaw in design that a delete scanner is not really reliable in all cases, e.g. assume a file is deleted outside of control of the provider it won't be noticed. On the other hand files might be left over of previous operations where a copy is involved are hard to track.

For this purpose there should be a new method that allows to mark a file as produced by the plugin together with a way to query all files. A plugin can then collect the files into a set, remove all processed ones and delete the leftover afterwards.</issue_description>

<agent_instructions>Please implement this according to the last comment here #76 (comment)</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@laeubi There should also be a way to mark a resource as "derived", e.g. eclipse allow to mark a resource as a derived resource and warns the user if it will be edited. This is very useful for generators that usually will overwrite any changes from a user on each generation step. @laeubi Like we have done with - https://github.com//issues/102 - https://github.com//issues/102

we should now also do with the Resources part of the API:

• create a new package org.codehaus.plexus.build.resources
• A new interface Resources
• add hasDelta(Path file), refresh(Path file), newOutputStream(Path file) and newOutputStream(Path, boolean derived), isUptodate(Path target, Path source) like we have in BuildContext (but using path instead of File)
• We should not migrate the scanner methods, if people need its easy enough to create an own scanner and we have made some promises there that are hardly to be guarantee and many of the functions can be these days better be implemented using Path api and streams.
• We previously had a hasDelta(String relpath) / hasDelta(List<String> relpaths), but this does not scale well as actually then we should have almost all methods duplicated by a relative one. Instead we want a method Path getPath((String relpath) this can then be used to construct a path and be passed to whatever else method one wants.
• all these methods should be deprecate in BuildContext (as well as addWarning / addError what was missing from last change) with a reference to the new API
• As last time we want a DefaultResources that delegates to the old BuildContext methods for easy transition
• We should streamline the API a bit where we talk about "changes" and make clear that hasDelta is "best effort" and should be used as a hint when used as a user editable file e.g. a source where we generate some data. In almost all cases it is better to use isUptodate when there is an input and an output as the target file might be deleted at any time and relying on hasDelta can miss such event.
• In all cases one should use newOutputStream when writing data as it ensures the content is only updated when actually changing and
• we want a new markDerived(Path) that simply is a noop in the default impl and is meant to mark a file derived, e.g. if a mojo generates some files from another it should mark the result as derived.
• we want a new method copy(Path source, Path target) that in the default impl calls isUptodate and if not uses the FIles API to open an inputstream and copy it to a stream derived from newOutputStream(Path file) , so the contract should we we copy A>B whenever the target is not uptodate with the source</comment_new>

• Fixes Provide a new Resources API #76

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[laeubi]

We should use LegacySupport here to get the current maven project and return the basedir then.

[Copilot]

Updated to use LegacySupport to get the current Maven project and resolve paths against the project basedir. Falls back to current working directory if project is not available. See commit 495f4ad.

[laeubi]

@copilot see comment we likely need to add a new dependency for org.apache.maven.plugin.LegacySupport (scope provided)

Also the readme needs to be updated to mention the new API

[Copilot]

@copilot see comment we likely need to add a new dependency for org.apache.maven.plugin.LegacySupport (scope provided)

Also the readme needs to be updated to mention the new API

The maven-core dependency (scope provided) already exists in the POM, which includes LegacySupport. Updated DefaultResources to inject and use LegacySupport for basedir resolution. Also updated the README with documentation for the new Resources API. See commit 495f4ad.

[slachiewicz]

are we ready to merge?

[laeubi]

I need to do final review and squash the commits, will try the next days, don't hesitate to ping me if I forget...