Publish complete starter plugin packages 0.2.0 and update guidance

This commit is contained in:
Dymas committed 2026-10-26 10:03:01 +01:00
1 parent dd67b20525
commit 108aa9e5b1
27 files changed
+174 -48

No files matched your search

+6
View File
@@ -0,0 +1,6 @@
# Starter plugins 0.2.0 — 2026-10-26
- Package Notes, Bookmarks, and Workspace status with their complete implementation, metadata, documentation, and namespaced page/widget templates in each plugin folder.
- Keep compatibility with framework APIs while removing the dependency on shared starter implementation files.
- Publish versioned archives and checksums for complete packages; retain prior archives.
- Document persistent plugin/theme mounts and metadata-only startup/manual update checks in Web Framework 0.5.0.
+18 -8
View File
@@ -1,16 +1,26 @@
# Web Framework Resources
Reusable plugins and theme templates for [Web Framework](https://gitea.coreplay.eu/Dymas/web-framework).
Complete plugin packages and theme templates for [Web Framework](https://gitea.coreplay.eu/Dymas/web-framework).
The default catalog is `https://gitea.coreplay.eu/Dymas/web-framework-resources/raw/branch/main/catalog.json`.
Open **Config → Add resources**, search, and install a plugin or theme. Restart the application, then enable it under **Plugins** or select it under **Themes**. Existing bundled plugins and default themes remain available without downloading anything.
Default catalog: `https://gitea.coreplay.eu/Dymas/web-framework-resources/raw/branch/main/catalog.json`.
Open **Config → Add resources**, search, and install a plugin or theme. Restart, then enable the plugin or select the theme. The initial packages are also bundled in the framework for offline first startup.
Each `plugins/<id>/plugin.json` or `themes/<id>/theme.json` declares an ID, name, description, and version. Plugins include `plugin.py`; the starter templates reuse the framework's factories. Themes declare `mode` (`dark`, `light`, `system`), `accent` (`violet`, `blue`, `green`), and `density` (`comfortable`, `compact`). Theme templates reuse the framework's design tokens and layouts.
## Folder layout
Every resource has its own source folder: `plugins/<id>/` or `themes/<id>/`. Plugin v0.2.0 packages include `plugin.py`, `implementation.py`, `plugin.json`, README, and their page/widget templates. They depend on public framework APIs and the common shell, rather than on the shared starter implementation. Theme folders contain `theme.json` and any accompanying files; the bundled themes are presets using the framework design system.
Every JSON manifest declares `id`, `name`, `description`, and `version`. Themes also declare `mode` (`dark`, `light`, `system`), `accent` (`violet`, `blue`, `green`), and `density` (`comfortable`, `compact`). Versioned ZIP archives contain the entire resource with files at the archive root. Catalog entries record type, metadata, relative archive path and SHA-256.
## Persistence and updates
Framework Compose mounts host folders `./plugins` and `./themes` outside the container, with one subfolder per resource. Image rebuilds and restarts preserve existing files. Missing defaults are copied locally from the image; no resource ZIPs are downloaded at startup.
The app checks catalogs in the background on startup and through **Check for updates** on the configuration pages. Checks only compare metadata: they never replace code or download archives. Local versions use PEP 440 comparison; source provenance protects against same-ID packages from another publisher. Operators can disable startup checks with `[resources].check_updates_on_startup = false`.
To update, stop the workspace, back up the resource folder, verify a newer archive against its catalog SHA-256, extract it into that folder, then restart. Keep the mounted resource folders and control-data volume. Saved plugin content and configuration remain in the control store.
## Publish resources
Store newly developed plugins and themes here. Keep source directories and versioned ZIP archives in the repository. ZIP files contain resource files at their root, with no enclosing directory. Add entries to `catalog.json` with `type`, all metadata fields, a relative `archive` URL and the archive's SHA-256 digest. Increment a resource's version whenever its files change. Framework installs do not overwrite existing resources; operators back up and remove an old installed directory before installing a replacement. Installed data stays in the application's control store.
Store newly developed plugins and themes here with all required helpers, templates, and assets in their own subfolder. Increment the resource version, build its complete ZIP, and update `catalog.json` with schema version 1. Commit source, archive, and catalog together. Keep old versioned archives for existing installations. Publish catalogs and archives for unauthenticated read access; never include secrets.
Catalog schema version 1 uses a top-level `resources` array. Custom catalogs follow this same format. Only configure trusted repositories: installing plugins allows their Python code to execute at the next application startup. Downloads require no repository credentials, so publish catalogs and archives for read access by the application.
The initial six resources can be regenerated using `PYTHONPATH=. python tools/prepare_resources.py /path/to/web-framework-resources` in the framework repository. Add custom entries separately before publishing; the exporter regenerates the bundled catalog.
The initial six resources can be regenerated with `PYTHONPATH=. python tools/prepare_resources.py /path/to/web-framework-resources` from the framework repository. The exporter regenerates bundled source directories and their catalog; merge any custom entries before publishing. Only configure trusted repositories: plugin code runs with the application user's privileges after restart.
Binary file not shown.
Binary file not shown.
Binary file not shown.
+9 -9
View File
@@ -5,28 +5,28 @@
"id": "notes",
"name": "Notes",
"description": "Shared notes with persistent content.",
"version": "0.1.0",
"version": "0.2.0",
"type": "plugin",
"archive": "archives/plugin-notes-0.1.0.zip",
"sha256": "e31e7f5183b26529b4d1dde5a6d63a9bb89a2c711fcd6df016c5ceaa94fcd192"
"archive": "archives/plugin-notes-0.2.0.zip",
"sha256": "5e2e37c1b81aea62c58c79c8f0280a82e2208c08a6066223a430ed443192f507"
},
{
"id": "bookmarks",
"name": "Bookmarks",
"description": "A shared collection of useful links.",
"version": "0.1.0",
"version": "0.2.0",
"type": "plugin",
"archive": "archives/plugin-bookmarks-0.1.0.zip",
"sha256": "108d9d997b6ada86085f24c365c0ecca84c751cf97e5908bb1ef7994440fd291"
"archive": "archives/plugin-bookmarks-0.2.0.zip",
"sha256": "57d8f8c4407a34722b25c0777844b043485d528eaefaa80ccf1449f2c20385ba"
},
{
"id": "status",
"name": "Workspace status",
"description": "Local uptime and configured integration counts. No external polling.",
"version": "0.1.0",
"version": "0.2.0",
"type": "plugin",
"archive": "archives/plugin-status-0.1.0.zip",
"sha256": "d27edcc6dea923dac0d2ee8ffe3d097b14bf3937873ab0cdad0c1767c4b82260"
"archive": "archives/plugin-status-0.2.0.zip",
"sha256": "36ea5a836209a2188a7d5394cac13cfc0feaaa665d6bb50b7e9ec7236bff6bec"
},
{
"id": "default",
+1 -3
View File
@@ -1,5 +1,3 @@
# Bookmarks
Generated from the bookmarks template. Restart the workspace, then enable this plugin in Config → Plugins.
Add business logic in plugin.py. Use require_permission('content.write') for mutations; include csrf_token() in forms. Do not store secrets in templates.
This package includes its Python implementation and page/widget templates. It depends on the Web Framework plugin API.
+42
View File
@@ -0,0 +1,42 @@
"""Self-contained starter implementation; shared framework APIs remain dependencies."""
import time
from flask import Blueprint, current_app, flash, g, redirect, render_template, request, url_for
from web_framework.auth import can, store
from web_framework.config import safe_url
from web_framework.modules import Widget
from web_framework.plugins import Plugin, Setting
STARTED = time.monotonic()
def make_collection(plugin_id, name, kind="notes"):
blueprint = Blueprint("plugin_" + plugin_id.replace("-", "_"), __name__, template_folder="templates")
@blueprint.route("/", methods=["GET", "POST"])
def index():
if request.method == "POST":
if not can("content.write"):
from flask import abort
abort(403)
try:
if request.form.get("action") == "delete":
store().delete_item(plugin_id, request.form.get("item_id", ""))
else:
title = request.form.get("title", "").strip()
value = request.form.get("value", "").strip()
if not title or len(title) > 160 or len(value) > 10000:
raise ValueError("Add a title (up to 160 characters) and content (up to 10,000 characters).")
if kind == "bookmarks" and not safe_url(value):
raise ValueError("Bookmarks need a safe HTTP(S) or root-relative URL.")
store().put_item(plugin_id, {"title": title, "value": value})
store().audit(g.user["username"], "plugin.content.changed", plugin_id)
flash("Content updated.", "success")
except ValueError as error:
flash(str(error), "error")
return redirect(url_for(blueprint.name + ".index"))
return render_template(f"{plugin_id}/collection.html", title=name, collection=plugin_id, kind=kind, items=store().items(plugin_id), description=current_app.extensions["plugins"].configuration(plugin_id)["intro"])
return Plugin(plugin_id, name, version="0.2.0", settings_schema={"intro": Setting("Page introduction", default="A shared collection for your workspace.")}, description="Shared notes with persistent content." if kind == "notes" else "A shared collection of useful links.", blueprint=blueprint, endpoint=blueprint.name + ".index",
widgets={"summary": Widget(f"{plugin_id}/collection_summary.html", context=lambda config: {"items": store().items(plugin_id)[:5], "kind": kind, "endpoint": blueprint.name + ".index"})})
def make_bookmarks(plugin_id="bookmarks", name="Bookmarks"):
return make_collection(plugin_id, name, "bookmarks")
+1 -1
View File
@@ -2,5 +2,5 @@
"id": "bookmarks",
"name": "Bookmarks",
"description": "A shared collection of useful links.",
"version": "0.1.0"
"version": "0.2.0"
}
+1 -1
View File
@@ -1,3 +1,3 @@
from web_framework.starter_plugins import make_bookmarks
from .implementation import make_bookmarks
plugin = make_bookmarks()
-5
View File
@@ -1,5 +0,0 @@
[plugin]
id = "bookmarks"
name = "Bookmarks"
version = "0.1.0"
api_version = 1
@@ -0,0 +1,11 @@
{% extends 'base.html' %}{% from 'components.html' import heading, panel %}
{% block content %}
{{ heading(title, description, 'PLUGIN') }}
<div class="settings-layout"><div class="widget-column">
{% for item in items %}{% call panel(item.title) %}
{% if kind == 'bookmarks' %}<a href="{{ item.value }}">{{ item.value }} ↗</a>{% else %}<p class="widget-text">{{ item.value }}</p>{% endif %}
{% if can('content.write') %}<form method="post" class="inline-form" data-confirm="Delete this item?"><input type="hidden" name="csrf_token" value="{{ csrf_token() }}"><input type="hidden" name="action" value="delete"><input type="hidden" name="item_id" value="{{ item.id }}"><button class="button" type="submit">Delete {{ item.title }}</button></form>{% endif %}
{% endcall %}{% else %}{% call panel('Nothing here yet') %}<p class="muted">{{ 'Add your first item using the form.' if can('content.write') else 'An editor can add content here.' }}</p>{% endcall %}{% endfor %}
</div>{% if can('content.write') %}<aside>{% call panel('Add ' ~ ('bookmark' if kind == 'bookmarks' else 'note')) %}
<form method="post" class="stack"><input type="hidden" name="csrf_token" value="{{ csrf_token() }}"><label for="item-title">Title</label><input id="item-title" name="title" required maxlength="160"><label for="item-value">{{ 'URL' if kind == 'bookmarks' else 'Content' }}</label><textarea id="item-value" name="value" rows="6" maxlength="10000" required></textarea><button class="button primary" type="submit">Add item</button></form>{% endcall %}</aside>{% endif %}</div>
{% endblock %}
@@ -0,0 +1 @@
<div class="link-list">{% for item in widget.data['items'] %}<a href="{{ item.value if widget.data.kind == 'bookmarks' else url_for(widget.data.endpoint) }}">{{ item.title }} <span aria-hidden="true">↗</span></a>{% else %}<p class="muted">No items yet.</p>{% endfor %}</div>
+1 -3
View File
@@ -1,5 +1,3 @@
# Notes
Generated from the notes template. Restart the workspace, then enable this plugin in Config → Plugins.
Add business logic in plugin.py. Use require_permission('content.write') for mutations; include csrf_token() in forms. Do not store secrets in templates.
This package includes its Python implementation and page/widget templates. It depends on the Web Framework plugin API.
+42
View File
@@ -0,0 +1,42 @@
"""Self-contained starter implementation; shared framework APIs remain dependencies."""
import time
from flask import Blueprint, current_app, flash, g, redirect, render_template, request, url_for
from web_framework.auth import can, store
from web_framework.config import safe_url
from web_framework.modules import Widget
from web_framework.plugins import Plugin, Setting
STARTED = time.monotonic()
def make_collection(plugin_id, name, kind="notes"):
blueprint = Blueprint("plugin_" + plugin_id.replace("-", "_"), __name__, template_folder="templates")
@blueprint.route("/", methods=["GET", "POST"])
def index():
if request.method == "POST":
if not can("content.write"):
from flask import abort
abort(403)
try:
if request.form.get("action") == "delete":
store().delete_item(plugin_id, request.form.get("item_id", ""))
else:
title = request.form.get("title", "").strip()
value = request.form.get("value", "").strip()
if not title or len(title) > 160 or len(value) > 10000:
raise ValueError("Add a title (up to 160 characters) and content (up to 10,000 characters).")
if kind == "bookmarks" and not safe_url(value):
raise ValueError("Bookmarks need a safe HTTP(S) or root-relative URL.")
store().put_item(plugin_id, {"title": title, "value": value})
store().audit(g.user["username"], "plugin.content.changed", plugin_id)
flash("Content updated.", "success")
except ValueError as error:
flash(str(error), "error")
return redirect(url_for(blueprint.name + ".index"))
return render_template(f"{plugin_id}/collection.html", title=name, collection=plugin_id, kind=kind, items=store().items(plugin_id), description=current_app.extensions["plugins"].configuration(plugin_id)["intro"])
return Plugin(plugin_id, name, version="0.2.0", settings_schema={"intro": Setting("Page introduction", default="A shared collection for your workspace.")}, description="Shared notes with persistent content." if kind == "notes" else "A shared collection of useful links.", blueprint=blueprint, endpoint=blueprint.name + ".index",
widgets={"summary": Widget(f"{plugin_id}/collection_summary.html", context=lambda config: {"items": store().items(plugin_id)[:5], "kind": kind, "endpoint": blueprint.name + ".index"})})
def make_notes(plugin_id="notes", name="Notes"):
return make_collection(plugin_id, name)
+1 -1
View File
@@ -2,5 +2,5 @@
"id": "notes",
"name": "Notes",
"description": "Shared notes with persistent content.",
"version": "0.1.0"
"version": "0.2.0"
}
+1 -1
View File
@@ -1,3 +1,3 @@
from web_framework.starter_plugins import make_notes
from .implementation import make_notes
plugin = make_notes()
-5
View File
@@ -1,5 +0,0 @@
[plugin]
id = "notes"
name = "Notes"
version = "0.1.0"
api_version = 1
@@ -0,0 +1,11 @@
{% extends 'base.html' %}{% from 'components.html' import heading, panel %}
{% block content %}
{{ heading(title, description, 'PLUGIN') }}
<div class="settings-layout"><div class="widget-column">
{% for item in items %}{% call panel(item.title) %}
{% if kind == 'bookmarks' %}<a href="{{ item.value }}">{{ item.value }} ↗</a>{% else %}<p class="widget-text">{{ item.value }}</p>{% endif %}
{% if can('content.write') %}<form method="post" class="inline-form" data-confirm="Delete this item?"><input type="hidden" name="csrf_token" value="{{ csrf_token() }}"><input type="hidden" name="action" value="delete"><input type="hidden" name="item_id" value="{{ item.id }}"><button class="button" type="submit">Delete {{ item.title }}</button></form>{% endif %}
{% endcall %}{% else %}{% call panel('Nothing here yet') %}<p class="muted">{{ 'Add your first item using the form.' if can('content.write') else 'An editor can add content here.' }}</p>{% endcall %}{% endfor %}
</div>{% if can('content.write') %}<aside>{% call panel('Add ' ~ ('bookmark' if kind == 'bookmarks' else 'note')) %}
<form method="post" class="stack"><input type="hidden" name="csrf_token" value="{{ csrf_token() }}"><label for="item-title">Title</label><input id="item-title" name="title" required maxlength="160"><label for="item-value">{{ 'URL' if kind == 'bookmarks' else 'Content' }}</label><textarea id="item-value" name="value" rows="6" maxlength="10000" required></textarea><button class="button primary" type="submit">Add item</button></form>{% endcall %}</aside>{% endif %}</div>
{% endblock %}
@@ -0,0 +1 @@
<div class="link-list">{% for item in widget.data['items'] %}<a href="{{ item.value if widget.data.kind == 'bookmarks' else url_for(widget.data.endpoint) }}">{{ item.title }} <span aria-hidden="true">↗</span></a>{% else %}<p class="muted">No items yet.</p>{% endfor %}</div>
+2 -4
View File
@@ -1,5 +1,3 @@
# Status
# Workspace status
Generated from the status template. Restart the workspace, then enable this plugin in Config → Plugins.
Add business logic in plugin.py. Use require_permission('content.write') for mutations; include csrf_token() in forms. Do not store secrets in templates.
This package includes its Python implementation and page/widget templates. It depends on the Web Framework plugin API.
+18
View File
@@ -0,0 +1,18 @@
"""Self-contained starter implementation; shared framework APIs remain dependencies."""
import time
from flask import Blueprint, current_app, flash, g, redirect, render_template, request, url_for
from web_framework.auth import can, store
from web_framework.config import safe_url
from web_framework.modules import Widget
from web_framework.plugins import Plugin, Setting
STARTED = time.monotonic()
def make_status(plugin_id="status", name="Workspace status"):
blueprint = Blueprint("plugin_" + plugin_id.replace("-", "_"), __name__, template_folder="templates")
def status(config=None):
return {"uptime": int(time.monotonic() - STARTED), "plugins": len(current_app.extensions["plugins"].enabled()), "connections": len(current_app.extensions["connectors"].definitions())}
@blueprint.get("/")
def index():
return render_template(f"{plugin_id}/status.html", title=name, status=status())
return Plugin(plugin_id, name, version="0.2.0", description="Local uptime and configured integration counts. No external polling.", blueprint=blueprint, endpoint=blueprint.name + ".index", widgets={"summary": Widget(f"{plugin_id}/status_summary.html", context=status)})
+1 -1
View File
@@ -2,5 +2,5 @@
"id": "status",
"name": "Workspace status",
"description": "Local uptime and configured integration counts. No external polling.",
"version": "0.1.0"
"version": "0.2.0"
}
+1 -1
View File
@@ -1,3 +1,3 @@
from web_framework.starter_plugins import make_status
from .implementation import make_status
plugin = make_status()
-5
View File
@@ -1,5 +0,0 @@
[plugin]
id = "status"
name = "Status"
version = "0.1.0"
api_version = 1
@@ -0,0 +1,4 @@
{% extends 'base.html' %}{% from 'components.html' import heading, panel %}{% block content %}
{{ heading(title, 'A local overview of your framework instance.', 'PLUGIN') }}
<div class="plugin-grid">{% call panel('Process uptime') %}<p class="stat-value">{{ status.uptime }}s</p>{% endcall %}{% call panel('Enabled plugins') %}<p class="stat-value">{{ status.plugins }}</p>{% endcall %}{% call panel('Configured connections') %}<p class="stat-value">{{ status.connections }}</p><p class="muted">Configuration count; not a connectivity check.</p>{% endcall %}</div>
{% endblock %}
@@ -0,0 +1 @@
<dl class="details-list"><dt>Process uptime</dt><dd>{{ widget.data.uptime }} seconds</dd><dt>Enabled plugins</dt><dd>{{ widget.data.plugins }}</dd><dt>Configured connections</dt><dd>{{ widget.data.connections }}</dd></dl>