Metadata-Version: 2.4
Name: apx-example
Version: 0.2.0
Summary: Template for an Action Platform plugin: tools, a CLI command, an overlay, a release strategy, a replaced slot, lifecycle hooks.
Author-email: Action Platform <cloud@actionplatform.io>
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: action-platform>=0.26
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: action-platform[mcp]; extra == "dev"
Dynamic: license-file

# apx-example

Template for an [Action Platform](https://github.com/actionplatform/action-platform) plugin — an *apx*, Action Platform extension; every package is named `apx-<slug>`. Every extension point once, small enough to read in one sitting:

| File | Extension point |
|---|---|
| `plugin.py` | the `Plugin`: slug, `needs`, `register`, `after_release`, `after_deploy` |
| `tools.py` | MCP tools `example_hello` and `example_remember`, with input and output schemas; `remember` writes the plugin's options store |
| `cli.py` | `action-platform example hello` |
| `rules.py` | a replaced core slot (`gitflow_rules`) — stricter branch kinds while the plugin is enabled |
| `release.py` | named providers: `[release] strategy = "calver"`, `[release] changelog = "plain"` |
| `target.py` | the `DeployTarget` for the `example` cloud: `preflight`, `readiness` (checks before a deploy), `deploy` (streams its output to the job log), `verify`, `diagnose`, `delete` |
| `overlays/` | a cloud overlay `example` — plain files, copied as they are by `action-platform cloud set example`; add a `cookiecutter.json` only when the files need rendering |

## Use this template

1. Create a repository from it, named `apx-<slug>`.
2. Rename `apx_example` → `apx_<slug>`, `example` → `<slug>` in `pyproject.toml` (package name, entry points), `plugin.py` (`slug`), `target.py` (`name`), `cli.py`, `overlays/index.json`.
3. Delete what you do not need; a plugin with only `plugin.py` and one tool is fine.
4. `pip install -e ".[dev]"`, `pytest`, `action-platform plugin list` (shows `example` once installed).
5. Publish to PyPI; open a pull request to [plugins-index](https://github.com/actionplatform/plugins-index) with `<slug>.json`.

## Rules

- `register` only declares; no I/O, threads or connections at import or in `register`.
- No monkey-patching of `action_platform.*` — replace a slot (`surface.core.replace`) or ask for a hook.
- `needs` lists every host you talk to and every environment variable you read.

Reference: [writing a plugin](https://github.com/actionplatform/action-platform/blob/master/docs/contribute_plugins.md) · [plugins](https://github.com/actionplatform/action-platform/blob/master/docs/use_plugins.md).
