# CMA Extensions

This directory is the Maven source root for first-party CMA extensions. It is an aggregator
module (`extensions/pom.xml`) included in the root CMA build after `master` and `agent`.

## Module Structure

```
extensions/
  pom.xml               ← aggregator POM (parent of all extension submodules)
  vault-ext/            ← HashiCorp Vault extension
    vault-core/         ← shared Vault operations (VaultService, VaultConfiguration)
    vault-ext-master/   ← master SPI wrapper — shaded JAR bundled in CMA assembly
    vault-ext-agent/    ← agent SPI wrapper — shaded JAR bundled in CMA assembly
  target/               ← default dev extensions directory (gitignored)
```

## Adding a New Extension

1. Create a subdirectory (e.g. `my-ext/`) with its own `pom.xml` parented by this aggregator.
2. Add the new module to the `<modules>` list in `extensions/pom.xml`.
3. Implement `CmaMasterExtension` and/or `CmaAgentExtension` from the `extension-spi` artifact.
4. Add `fileSet` entries to `assembly/assembly/cma-component.xml` to include the shaded JAR(s)
   in `<cma-home>/extensions/`.

The `deploy` Maven profile (inherited from `extensions/pom.xml`) copies the built JAR to
`${extensions.dir}` (default: `extensions/target`) so you can test locally without a full
assembly build:

```bash
mvn verify -Pdeploy -pl extensions/my-ext
# or override the target directory:
mvn verify -Pdeploy -Dextensions.dir=/path/to/cma/extensions -pl extensions/my-ext
```

## Local Development

The `dev` Spring profile on both master and agent sets `cma.extensions-dir` to
`${cma.home}/extensions/target`, pointing at this directory's `target/` folder. Run the
`deploy` profile to place extension JARs there, then start CMA with the `dev` profile.

## How Extensions Are Loaded at Runtime

1. CMA scans `cma.extensions-dir` for `*.jar` files on startup.
2. Each JAR is loaded via a `URLClassLoader` whose parent is the host application classloader.
3. Extensions register via `java.util.ServiceLoader` using `CmaMasterExtension` (master) or
   `CmaAgentExtension` (agent) — only the matching SPI is loaded on each side.
4. Extension Spring configuration classes returned by `getSpringConfiguration()` are registered
   into the host application context.

## Further Reading

- [docs/architecture/extension-system.md](../docs/architecture/extension-system.md) — full technical specification of the extension system (SPI, classloader model, UI integration, REST API)
- [docs/architecture/extensions/vault-ext.md](../docs/architecture/extensions/vault-ext.md) — detailed walkthrough of the vault-ext implementation
