heinzel-example 0.4.0__py3-none-any.whl

heinzel_example/__init__.py

@@ -0,0 +1,71 @@
+"""Show how a Heinzelmännchen plugin is built.
+
+A Heinzelmännchen plugin, discovered through the `heinzel.modules` entry point in pyproject.toml. Every package
+below it that declares `module = Module(...)` becomes a submodule (see `hello/`).
+"""
+
+from pathlib import Path
+
+from heinzel import MetricWidget, Module, Navigate, NoticeKind, Notifications, StatusItem
+
+from heinzel_example._models import ExampleAbout, ExampleSettings
+from heinzel_example._service import ExampleService
+
+module = Module("example", "Show how a Heinzelmännchen plugin is built.")
+module.settings(ExampleSettings)
+module.service(ExampleService)
+
+
+@module.operation
+def info(service: ExampleService) -> ExampleAbout:
+    """Show this plugin's version, the Heinzelmännchen it runs on and the modules it brings."""
+    return service.about()
+
+
+@module.info
+def system_info(service: ExampleService) -> ExampleAbout:
+    """Contribute this plugin's details to `hz system info`."""
+    return service.about()
+
+
+__all__ = ["ExampleAbout", "ExampleService", "ExampleSettings", "module"]
+
+
+@module.operation
+def sample() -> int:
+    """Read a tiny value used by every example representation."""
+    return 42
+
+
+@module.operation(read_only=False)
+def notify(notifications: Notifications) -> str:
+    """Send an example notice after the ordinary operation confirmation."""
+    notice = notifications.emit(
+        NoticeKind.PLUGIN, "Example is ready", route="/", command="hz example sample", key="example:ready"
+    )
+    return notice.title if notice else "Notifications are disabled"
+
+
+@module.status(source="sample", order=700, slots={"footer": False, "sidebar": True})
+def status(value: int) -> StatusItem:
+    """Render checked data through the same host slots as built-in modules."""
+    return StatusItem(text=f"Example: {value}", icon="star", effect=Navigate(path="/?panel=example:inspector"))
+
+
+@module.widget(source="sample", order=700)
+def today(value: int) -> MetricWidget:
+    """Contribute a Today widget without a core change."""
+    return MetricWidget(label="Example value", value=str(value))
+
+
+module.action("inspect", label="Example", icon="star", effect=Navigate(path="/?panel=example:inspector"), order=700)
+module.nav(title="Example", icon="star", sidebar=Navigate(path="/?panel=example:inspector"), order=700)
+module.view(
+    Path(__file__).parent / "views",
+    abi=1,
+    name="inspector",
+    source="sample",
+    title="Example",
+    fallback="Run hz example sample to read the value.",
+    order=700,
+)

heinzel_example/_models.py

@@ -0,0 +1,25 @@
+"""Models returned by the plugin's operations."""
+
+from heinzel import ModuleSettings
+from pydantic import BaseModel, Field
+
+
+class ExampleAbout(BaseModel):
+    """What this plugin is and where it runs."""
+
+    plugin: str = Field(description="Distribution name of the plugin.")
+    version: str = Field(description="Installed version of the plugin.")
+    heinzel_version: str = Field(description="Version of the Heinzelmännchen it runs in.")
+    modules: list[str] = Field(description="Qualified names of the modules the plugin provides.")
+
+
+class ExampleGreeting(BaseModel):
+    """A greeting."""
+
+    text: str
+
+
+class ExampleSettings(ModuleSettings):
+    """Settings of the plugin: its table in the `hz` config files, or `HZ_<PLUGIN>__<FIELD>` variables."""
+
+    greeting: str = Field(default="Hello", description="How `hello` greets.")

heinzel_example/_service.py

@@ -0,0 +1,35 @@
+"""The plugin's logic, independent of any head."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from heinzel import Kernel, __version__
+
+from heinzel_example._models import ExampleAbout, ExampleGreeting, ExampleSettings
+
+DISTRIBUTION = "heinzel-example"
+
+
+class ExampleService:
+    """Everything the example modules do; operations stay thin and call into it."""
+
+    def __init__(self, kernel: Kernel, settings: ExampleSettings) -> None:
+        """Create the service; the kernel and the plugin's settings are injected."""
+        self._kernel = kernel
+        self._settings = settings
+
+    def about(self) -> ExampleAbout:
+        """Describe the plugin and the Heinzelmännchen installation it runs in."""
+        try:
+            installed = version(DISTRIBUTION)
+        except PackageNotFoundError:  # pragma: no cover - only when running from an uninstalled source tree
+            installed = "0.0.0"
+        return ExampleAbout(
+            plugin=DISTRIBUTION,
+            version=installed,
+            heinzel_version=__version__,
+            modules=[r.qualname for r in self._kernel.modules if r.origin.distribution == DISTRIBUTION],
+        )
+
+    def greet(self, name: str) -> ExampleGreeting:
+        """Greet someone by name, the way the settings say."""
+        return ExampleGreeting(text=f"{self._settings.greeting}, {name}!")

heinzel_example/hello/__init__.py

@@ -0,0 +1,20 @@
+"""A submodule. Its only operation shares its name, so the CLI collapses it to `hz example hello`."""
+
+from typing import Annotated
+
+from heinzel import Module
+from pydantic import Field
+
+from heinzel_example._models import ExampleGreeting
+from heinzel_example._service import ExampleService
+
+module = Module("hello", "Greet someone.")
+
+
+@module.operation
+def hello(
+    service: ExampleService,
+    name: Annotated[str, Field(description="Who to greet.")] = "world",
+) -> ExampleGreeting:
+    """Greet someone by name."""
+    return service.greet(name)

heinzel_example/views/index.js

@@ -0,0 +1,10 @@
+// This small view needs no bundler. A specialist view can use the same versioned SDK with its own build.
+export default function createView(sdk) {
+  if (sdk.abi !== 1) throw new Error("Example requires plugin SDK 1");
+  return function Inspector({data, loading, onClose}) {
+    return sdk.React.createElement("section", {"aria-label": "Example", className: "p-4"},
+      sdk.React.createElement("h2", null, "Example"),
+      sdk.React.createElement("p", {role: "status"}, loading ? "Loading…" : `The value is ${data}.`),
+      sdk.React.createElement(sdk.Button, {onClick: onClose}, "Close example"));
+  };
+}

heinzel_example-0.4.0.dist-info/METADATA

@@ -0,0 +1,59 @@
+Metadata-Version: 2.5
+Name: heinzel-example
+Version: 0.4.0
+Summary: Show how a Heinzelmännchen plugin is built.
+Project-URL: Source, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/tree/main/plugins/heinzel-example
+Project-URL: Changelog, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/blob/main/plugins/heinzel-example/CHANGELOG.md
+Project-URL: Issues, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/issues
+Author-email: Helmut Hoffer von Ankershoffen <helmuthva@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: heinzel,heinzel-plugin,heinzelmaennchen
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: heinzel<0.10,>=0.9.1
+Description-Content-Type: text/markdown
+
+# heinzel-example
+
+Show how a Heinzelmännchen plugin is built: one module with an operation, settings, a health check and a submodule.
+
+A plugin for [Heinzelmännchen](https://github.com/helmut-hoffer-von-ankershoffen/heinzel), the open-source, AI-driven
+operating system for product development teams. It lives in
+[heinzel-plugins](https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins). Its earlier history is preserved
+in heinzel-contrib and the archived heinzel-example repository.
+
+## Install
+
+With Heinzelmännchen installed (`uv tool install git+https://github.com/helmut-hoffer-von-ankershoffen/heinzel`):
+
+```bash
+hz system plugin add "heinzel-example @ git+https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins#subdirectory=plugins/heinzel-example"
+```
+
+Running `hz system plugin add` again upgrades; `hz system plugin remove heinzel-example` removes it.
+
+## Use
+
+```bash
+hz example info                 # this plugin, its version and the Heinzelmännchen it runs on
+hz example hello --name Ada     # a submodule collapsed into a command
+hz example info --json          # every command speaks JSON, for scripts and agents
+hz system info                  # includes a section contributed by this plugin
+```
+
+## Develop
+
+From the repository root: `make check-fast NAME=example` runs this plugin's edit loop; `make check NAME=example`
+runs its full checks. `make build NAME=example` and `make acceptance NAME=example` verify its installed artifact.
+The modules live in
+`src/heinzel_example/`; read the root [AGENTS.md](../../AGENTS.md) before changing them.
+
+Development and release commands: [repository guide](../../README.md).
+
+Migration provenance: heinzel-contrib, before the 0.9 plugin-boundary migration.

heinzel_example-0.4.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+heinzel_example/__init__.py,sha256=Jj_OvwKJ2pfhwXefD5O3EGAFMFfLQwQ0hJlPGexeX04,2502
+heinzel_example/_models.py,sha256=IM1y8LwSGu1iAZir55mol1VhkNXbDHB53ty3Tt-8cUQ,842
+heinzel_example/_service.py,sha256=jmqDTiVgOAiZJVANCGwdqW4dRFz_4_-qFHll1pYdDu4,1366
+heinzel_example/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+heinzel_example/hello/__init__.py,sha256=SIOmKrv6S5FXIjboGMMI8V4uFfBI74zhZrz2UqnsU0g,554
+heinzel_example/views/index.js,sha256=frB2T8gchfvbxf37bRqkNaS7HFP343UcKiowzZhb8zc,612
+heinzel_example-0.4.0.dist-info/METADATA,sha256=RTI-T2GMIKVDlC5n236dkICPSsJtwCa2l2nLiro0lzg,2713
+heinzel_example-0.4.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+heinzel_example-0.4.0.dist-info/entry_points.txt,sha256=tOa-l6Z7Nu1zrehG7e_K5i8DtHCdPkz0yZ-Fie4vqfw,44
+heinzel_example-0.4.0.dist-info/licenses/LICENSE,sha256=uAnloDezQUp6s7yo2vDvfNU_f6qLKss3jcU01jGz1cU,1087
+heinzel_example-0.4.0.dist-info/RECORD,,

heinzel_example-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

heinzel_example-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[heinzel.modules]
+example = heinzel_example

heinzel_example-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Helmut Hoffer von Ankershoffen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.