feat: adopt selective dependency packaging (profiles) (#1228)

* architecture document for adding exclusions and profiles for offline buildpacks

* feat: adopt selective dependency packaging profiles

Add packaging_profiles to manifest.yml and wire --profile/--exclude/--include
flags through scripts/package.sh to buildpack-packager.

Depends on libbuildpack PR cloudfoundry/libbuildpack#212 which introduces
PackageWithOptions, resolveExclusions, and the three new CLI flags in
buildpack-packager.

Changes:
- manifest.yml: add packaging_profiles section with 'minimal' (28 deps)
  and 'standard' (32 deps) profiles
- scripts/package.sh: parse and forward --profile, --exclude, --include
  to buildpack-packager; update usage()
- README.md: document selective offline packaging, updated --help output
  and package examples
- docs/DEVELOPING.md: document profile/exclude options in packaging section
- docs/buildpack-modes.md: add Selective Offline Packaging subsection

Author: ramonskie

README.md

@@ -233,6 +233,48 @@ Building buildpack (version: 0.0.0, stack: cflinuxfs4, cached: true, output: bui
 
 The offline package will be significantly larger (1.0-1.2 GB depending on cached dependencies) as it includes all JRE versions and framework agents specified in `manifest.yml`.
 
+#### Selective Dependency Packaging
+
+For air-gapped environments or security-conscious deployments, you can build a smaller offline package that contains only a named subset of dependencies using packaging profiles or explicit exclusions.
+
+**Using a profile** (defined in `manifest.yml`):
+
+```bash
+# Minimal: JDKs, CF utilities, Tomcat, and common frameworks only (~28 dependencies)
+$ ./scripts/package.sh --cached --profile minimal
+
+# Standard: core + open-source APM, OTel, and JDBC drivers (~32 dependencies)
+$ ./scripts/package.sh --cached --profile standard
+```
+
+**Ad-hoc exclusions** (no profile required):
+
+```bash
+# Exclude specific agents you don't have licences for
+$ ./scripts/package.sh --cached --exclude jrebel,your-kit-profiler,jprofiler-profiler
+```
+
+**Combining a profile with overrides**:
+
+```bash
+# Start from standard profile but also drop jacoco
+$ ./scripts/package.sh --cached --profile standard --exclude jacoco
+
+# Start from minimal profile but add back jprofiler for triage builds
+$ ./scripts/package.sh --cached --profile minimal --include jprofiler-profiler
+```
+
+The output zip filename reflects the profile/exclusion applied so that different variants can coexist:
+
+| Invocation | Output filename |
+|---|---|
+| `--cached` | `java_buildpack-cached-cflinuxfs4-v<ver>.zip` |
+| `--cached --profile minimal` | `java_buildpack-cached-minimal-cflinuxfs4-v<ver>.zip` |
+| `--cached --exclude newrelic` | `java_buildpack-cached-custom-cflinuxfs4-v<ver>.zip` |
+| `--cached --profile minimal --include jprofiler-profiler` | `java_buildpack-cached-minimal+custom-cflinuxfs4-v<ver>.zip` |
+
+> **Note**: `--profile`, `--exclude`, and `--include` are only valid with `--cached`. Using them on an uncached build is an error. `--include` requires `--profile` to be set.
+
 ### Package Versioning
 To specify a version number when creating a package, use the `--version` flag:
 
@@ -260,6 +302,9 @@ OPTIONS
   --cached                           cache the buildpack dependencies (default: false)
   --stack  <stack>                   specifies the stack (default: cflinuxfs4)
   --output <file>                    output file path (default: build/buildpack.zip)
+  --profile <name>                   packaging profile from manifest.yml (e.g. minimal, standard)
+  --exclude <dep1,dep2,...>          comma-separated dependency names to exclude (cached only)
+  --include <dep1,dep2,...>          comma-separated dependency names to restore, overriding profile exclusions (cached only)
 ```
 
 ### Customizing Dependencies
@@ -289,14 +334,26 @@ dependencies:
 # Online package with version 5.0.0
 $ ./scripts/package.sh --version 5.0.0
 
-# Offline package with version 5.0.0
+# Offline package with version 5.0.0 (all dependencies)
 $ ./scripts/package.sh --version 5.0.0 --cached
 
 # Package for specific stack
 $ ./scripts/package.sh --stack cflinuxfs4 --cached
 
 # Custom output location
 $ ./scripts/package.sh --version 5.0.0 --cached --output /tmp/my-buildpack.zip
+
+# Offline package with minimal profile (JDKs + CF utilities only)
+$ ./scripts/package.sh --version 5.0.0 --cached --profile minimal
+
+# Offline package with standard profile (core + open-source observability)
+$ ./scripts/package.sh --version 5.0.0 --cached --profile standard
+
+# Exclude specific dependencies without a profile
+$ ./scripts/package.sh --version 5.0.0 --cached --exclude jrebel,your-kit-profiler
+
+# Minimal profile, but add back jprofiler for this specific build
+$ ./scripts/package.sh --version 5.0.0 --cached --profile minimal --include jprofiler-profiler
 ```
 
 ## Running Tests

docs/DEVELOPING.md

@@ -482,6 +482,28 @@ Create a package with all dependencies cached (no internet required at runtime):
 
 **Output:** `build/buildpack.zip` (~500MB, varies based on cached dependencies)
 
+#### Selective Dependency Packaging (Profiles)
+
+For environments that only need a subset of dependencies, use packaging profiles or
+explicit exclusions to reduce the offline package size:
+
+```bash
+# Minimal: JDKs, CF utilities, Tomcat only (~28 deps, much smaller download)
+./scripts/package.sh --version 1.0.0 --cached --profile minimal
+
+# Standard: core + open-source APM, OTel, JDBC (~32 deps)
+./scripts/package.sh --version 1.0.0 --cached --profile standard
+
+# Ad-hoc: exclude specific agents (no profile needed)
+./scripts/package.sh --version 1.0.0 --cached --exclude jrebel,your-kit-profiler
+
+# Restore one dep excluded by a profile
+./scripts/package.sh --version 1.0.0 --cached --profile minimal --include jprofiler-profiler
+```
+
+Profiles are declared in the `packaging_profiles` section of `manifest.yml`. See
+[Selective Dependency Packaging](selective-dependency-packaging.md) for full details.
+
 ### Package Options
 
 ```bash
@@ -496,6 +518,12 @@ Create a package with all dependencies cached (no internet required at runtime):
 
 # Offline with custom stack
 ./scripts/package.sh --version 1.0.0 --cached --stack cflinuxfs4
+
+# Offline with minimal profile
+./scripts/package.sh --version 1.0.0 --cached --profile minimal
+
+# Offline excluding specific dependencies
+./scripts/package.sh --version 1.0.0 --cached --exclude datadog-javaagent,newrelic
 ```
 
 ### Automated Packaging (CI/CD)

docs/buildpack-modes.md

@@ -44,6 +44,39 @@ The "Offline Mode" buildpack is a self-contained packaging of either the "Easy M
 
 You can download specific versions of the "Offline Mode" buildpack to use with the `create-buildpack` and `update-buildpack` Cloud Foundry CLI commands.  To find these, navigate to the [Java Buildpack Releases page][v] and download one of the `java-buildpack-offline-v<VERSION>.zip` file.   In order to package a modified "Offline Mode" buildpack, refer to [Building Packages][p].  To add the buildpack to an instance of Cloud Foundry, use the `cf create-buildpack java-buildpack java-buildpack-offline-v<VERSION>.zip` command.  For more details refer to the [Cloud Foundry buildpack documentation][b].
 
+### Selective Offline Packaging
+
+The full offline package bundles every dependency in `manifest.yml` (~47 binaries, 1.0-1.2 GB). For
+air-gapped environments that only need a subset, you can build a smaller offline package using
+**packaging profiles** or explicit exclusions.
+
+**Using a profile** (defined in `manifest.yml`'s `packaging_profiles` section):
+
+```bash
+# Minimal: JDKs, CF utilities, Tomcat, and common frameworks only (~28 deps)
+$ ./scripts/package.sh --cached --profile minimal
+
+# Standard: core + open-source APM, OTel, and JDBC drivers (~32 deps)
+$ ./scripts/package.sh --cached --profile standard
+```
+
+**Ad-hoc exclusions** without a profile:
+
+```bash
+# Remove specific agents you don't have licences for
+$ ./scripts/package.sh --cached --exclude jrebel,your-kit-profiler,jprofiler-profiler
+```
+
+**Overriding a profile** to restore a specific dependency:
+
+```bash
+# Start from minimal but include jprofiler for triage builds
+$ ./scripts/package.sh --cached --profile minimal --include jprofiler-profiler
+```
+
+For full details on profiles, validation rules, and output filename conventions, see
+[Selective Dependency Packaging](selective-dependency-packaging.md).
+
 
 [b]: http://docs.pivotal.io/pivotalcf/adminguide/buildpacks.html
 [c]: ../README.md#configuration-and-extension