apx-example 0.1.0__tar.gz → 0.2.0__tar.gz

{apx_example-0.1.0 → apx_example-0.2.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: apx-example
-Version: 0.1.0
+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.16
+Requires-Dist: action-platform>=0.26
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
@@ -21,16 +21,17 @@ Template for an [Action Platform](https://github.com/actionplatform/action-platf
 | File | Extension point |
 |---|---|
 | `plugin.py` | the `Plugin`: slug, `needs`, `register`, `after_release`, `after_deploy` |
-| `tools.py` | an MCP tool, published as `example_hello` with input and output schemas |
+| `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`), `cli.py`, `overlays/index.json`.
+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`.

{apx_example-0.1.0 → apx_example-0.2.0}/README.md

@@ -5,16 +5,17 @@ Template for an [Action Platform](https://github.com/actionplatform/action-platf
 | File | Extension point |
 |---|---|
 | `plugin.py` | the `Plugin`: slug, `needs`, `register`, `after_release`, `after_deploy` |
-| `tools.py` | an MCP tool, published as `example_hello` with input and output schemas |
+| `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`), `cli.py`, `overlays/index.json`.
+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`.

apx_example-0.2.0/apx_example/overlays/cloud/example/DEPLOY.md

@@ -0,0 +1,7 @@
+# Deploy — example
+
+This project deploys to the `example` target. The files under `deploy/` came from the `example` plugin's overlay, copied as they are — no templating.
+
+The contract a real cloud overlay follows: every web project **serves HTTP on `$PORT`**, and the overlay's build step is `ap-build package` (from [images-base](https://github.com/actionplatform/images-base)), which assembles the app, its dependencies and `run.sh` for any language. One `template.yaml` (or Dockerfile, or workflow) per cloud is enough — no files per language. See [apx-aws-lambda](https://github.com/actionplatform/apx-aws-lambda) for the real thing: `template.yaml` with the runtime chosen by language, a `Makefile` with one line, `requirements/` with the least-privilege policy.
+
+The platform calls the target's `readiness(ctx)` after every release, for every scope of the app, and refuses a deploy the checks block. The scope's name arrives as `ctx.stage`.

{apx_example-0.1.0 → apx_example-0.2.0}/apx_example/plugin.py

@@ -15,8 +15,8 @@ from apx_example.tools import register_tools
 
 class ExamplePlugin(Plugin):
     slug = "example"
-    description = "Template plugin: a tool, a command, an overlay, a release strategy, stricter git-flow"
-    min_core = "0.16"
+    description = "Template plugin: a tool, a command, a deploy target with readiness, an overlay, a release strategy, stricter git-flow"
+    min_core = "0.26"
     needs = ["nothing outside this machine"]
 
     @property
@@ -24,8 +24,10 @@ class ExamplePlugin(Plugin):
         return Path(__file__).parent / "overlays"
 
     def register(self, surface: Surface) -> None:
+        self.options = surface.options
+
         if surface.mcp is not None:
-            register_tools(surface.mcp)
+            register_tools(surface.mcp, surface.options)
 
         if surface.cli is not None:
             surface.cli.add_typer(cli.app, name="example")
@@ -33,6 +35,7 @@ class ExamplePlugin(Plugin):
         surface.core.replace("gitflow_rules", StrictRules)
 
     def after_release(self, ctx: Context) -> None:
+        self.options.set("last_release", ctx.next_version)
         logger.info(f"example: released {ctx.next_version} from {ctx.branch}")
 
     def after_deploy(self, results: list[DeployResult]) -> None:

apx_example-0.2.0/apx_example/target.py

@@ -0,0 +1,56 @@
+"""The deploy target: what the platform calls to ship a release to the `example` cloud. Replace the bodies with your cloud's CLI; keep the shape."""
+
+from __future__ import annotations
+
+from action_platform.abc import DeployTarget
+from action_platform.core.context import Check, Context, DeployResult, Diagnosis
+from action_platform.core.process import stream
+from action_platform.logging import logger
+
+
+class ExampleTarget(DeployTarget):
+    name = "example"
+
+    def preflight(self, ctx: Context) -> None:
+        if not (ctx.repo_root / "deploy" / "run.sh").exists():
+            raise FileNotFoundError(
+                "deploy/run.sh not found: apply the example overlay first"
+            )
+
+    def readiness(self, ctx: Context) -> list[Check]:
+        present = (ctx.repo_root / "deploy" / "run.sh").exists()
+
+        return [
+            Check(
+                "example.overlay",
+                present,
+                "deploy/run.sh is there" if present else "deploy/run.sh not found",
+                fix=None if present else "action-platform cloud set example",
+            )
+        ]
+
+    def deploy(self, ctx: Context) -> DeployResult:
+        result = stream(
+            ["sh", "deploy/run.sh"],
+            cwd=ctx.repo_root,
+            env={**ctx.env, "SCOPE": ctx.stage},
+        )
+        logger.info("example: deployed %s to %s", ctx.next_version, ctx.stage)
+
+        return DeployResult(
+            ok=result.ok,
+            target=self.name,
+            version=ctx.next_version,
+            error=None if result.ok else result.output,
+        )
+
+    def verify(self, version: str, stage: str | None = None) -> bool:
+        return True
+
+    def diagnose(self, ctx: Context) -> Diagnosis:
+        return Diagnosis(
+            ok=True, target=self.name, status="example", details={"scope": ctx.stage}
+        )
+
+    def delete(self, ctx: Context) -> None:
+        logger.info("example: nothing to tear down for %s", ctx.stage)

apx_example-0.2.0/apx_example/tools.py

@@ -0,0 +1,34 @@
+"""MCP tools. They come out as `example_<name>`; annotate inputs and return a model so the client gets schemas. `options` is the plugin's own store — a file on a machine, a table on the hosted platform."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from action_platform.mcp.annotations import READ_ONLY, WRITES_LOCAL
+from action_platform.plugins import Options
+from pydantic import BaseModel, Field
+
+
+class Greeting(BaseModel):
+    greeting: str
+
+
+class Remembered(BaseModel):
+    key: str
+    value: Any
+
+
+def register_tools(mcp: Any, options: Options) -> None:
+    @mcp.tool(annotations=READ_ONLY)
+    def hello(
+        name: Annotated[str, Field(description="Who to greet")] = "world",
+    ) -> Greeting:
+        """Say hello — the smallest tool a plugin can add. The word comes from the plugin's options when set."""
+        return Greeting(greeting=f"{options.get('greeting', 'hello')} {name}")
+
+    @mcp.tool(annotations=WRITES_LOCAL)
+    def remember(key: str, value: str) -> Remembered:
+        """Store a value in the plugin's options — the platform keeps it for the next call."""
+        options.set(key, value)
+
+        return Remembered(key=key, value=value)

{apx_example-0.1.0 → apx_example-0.2.0}/apx_example.egg-info/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: apx-example
-Version: 0.1.0
+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.16
+Requires-Dist: action-platform>=0.26
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
@@ -21,16 +21,17 @@ Template for an [Action Platform](https://github.com/actionplatform/action-platf
 | File | Extension point |
 |---|---|
 | `plugin.py` | the `Plugin`: slug, `needs`, `register`, `after_release`, `after_deploy` |
-| `tools.py` | an MCP tool, published as `example_hello` with input and output schemas |
+| `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`), `cli.py`, `overlays/index.json`.
+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`.

{apx_example-0.1.0 → apx_example-0.2.0}/apx_example.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ apx_example/cli.py
 apx_example/plugin.py
 apx_example/release.py
 apx_example/rules.py
+apx_example/target.py
 apx_example/tools.py
 apx_example.egg-info/PKG-INFO
 apx_example.egg-info/SOURCES.txt

{apx_example-0.1.0 → apx_example-0.2.0}/apx_example.egg-info/entry_points.txt

@@ -1,6 +1,9 @@
 [action_platform.changelog]
 plain = apx_example.release:Plain
 
+[action_platform.deploy_target]
+example = apx_example.target:ExampleTarget
+
 [action_platform.plugins]
 example = apx_example:ExamplePlugin
 

{apx_example-0.1.0 → apx_example-0.2.0}/apx_example.egg-info/requires.txt

@@ -1,4 +1,4 @@
-action-platform>=0.16
+action-platform>=0.26
 
 [dev]
 pytest>=8

{apx_example-0.1.0 → apx_example-0.2.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "apx-example"
-version = "0.1.0"
+version = "0.2.0"
 description = "Template for an Action Platform plugin: tools, a CLI command, an overlay, a release strategy, a replaced slot, lifecycle hooks."
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.11"
 authors = [{ name = "Action Platform", email = "cloud@actionplatform.io" }]
-dependencies = ["action-platform>=0.16"]
+dependencies = ["action-platform>=0.26"]
 
 [project.optional-dependencies]
 dev = ["pytest>=8", "ruff>=0.6", "action-platform[mcp]"]
@@ -14,6 +14,9 @@ dev = ["pytest>=8", "ruff>=0.6", "action-platform[mcp]"]
 [project.entry-points."action_platform.plugins"]
 example = "apx_example:ExamplePlugin"
 
+[project.entry-points."action_platform.deploy_target"]
+example = "apx_example.target:ExampleTarget"
+
 [project.entry-points."action_platform.release_strategy"]
 calver = "apx_example.release:Calver"
 

{apx_example-0.1.0 → apx_example-0.2.0}/tests/test_plugin.py

@@ -57,3 +57,24 @@ class ExamplePluginTest(unittest.TestCase):
     def test_release_providers(self):
         self.assertTrue(Calver().next("1.0.0", "patch", False, []).count(".") == 2)
         self.assertIn("- feat: x", Plain().render("1.0.0", ["feat: x"]))
+
+
+class TargetTest(unittest.TestCase):
+    def test_readiness_names_the_overlay(self):
+        from pathlib import Path
+        from tempfile import TemporaryDirectory
+
+        from action_platform.core.context import Context
+
+        from apx_example.target import ExampleTarget
+
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            missing = ExampleTarget().readiness(Context(repo_root=root, stage="dev"))
+            (root / "deploy").mkdir()
+            (root / "deploy" / "run.sh").write_text("#!/bin/sh\necho ok\n")
+            present = ExampleTarget().readiness(Context(repo_root=root, stage="dev"))
+
+        self.assertFalse(missing[0].ok)
+        self.assertEqual(missing[0].fix, "action-platform cloud set example")
+        self.assertTrue(present[0].ok)

apx_example-0.1.0/apx_example/overlays/cloud/example/DEPLOY.md

@@ -1,3 +0,0 @@
-# Deploy — example
-
-This project deploys to the example target. The files under `deploy/` came from the `example` plugin's overlay, copied as they are — no templating. Replace them with what your target needs (a `template.yaml`, a `Dockerfile`, a workflow) and ship the matching `DeployTarget` under the `action_platform.deploy_target` entry-point group.

apx_example-0.1.0/apx_example/tools.py

@@ -1,21 +0,0 @@
-"""MCP tools. They come out as `example_<name>`; annotate inputs and return a model or a typed dict so the client gets schemas."""
-
-from __future__ import annotations
-
-from typing import Annotated, Any
-
-from action_platform.mcp.annotations import READ_ONLY
-from pydantic import BaseModel, Field
-
-
-class Greeting(BaseModel):
-    greeting: str
-
-
-def register_tools(mcp: Any) -> None:
-    @mcp.tool(annotations=READ_ONLY)
-    def hello(
-        name: Annotated[str, Field(description="Who to greet")] = "world",
-    ) -> Greeting:
-        """Say hello — the smallest tool a plugin can add."""
-        return Greeting(greeting=f"hello {name}")