-
v0.15.2 Stable
released this
2026-11-02 20:50:12 +00:00 | 22 commits to main since this releaseVSKI v0.15.2
vplugin.yaml: plugin manifests in YAML (vski-sdk 0.11.0)Plugins were declared in
vski-plugin.json. IaC made YAML the house
format, so manifests follow: a plugin directory now carries a
vplugin.yaml, same schema, YAML spelling.# plugins/hello/vplugin.yaml name: hello version: 0.1.0 title: Hello Plugin runtime: entry: hello.main:app # package.module:attribute → vski.plugin.Plugin python: ">=3.11" config: greeting: {type: string, default: hello} subscribe: collections: [notes] functions: echo: {description: Returns the greeting}- The server (catalog scan at boot and on
POST /api/plugins/scan)
discoversvplugin.yaml(andvplugin.yml); the legacy
vski-plugin.jsonis still read — first match wins — so existing
distributions keep working. New plugins should use the YAML name. - Whatever the source format, the API's
manifestfield stays canonical
JSON (the dashboard, TS SDK and e2e suites parse it as JSON; nothing
downstream changed). - The Python plugin runner (
python -m vski.plugin.runner) reads both
formats for its display-name fallback; PyYAML stays a CLI-extra
dependency — without it, YAML manifests simply degrade to an empty
fallback name instead of killing the process. examples/plugins/*and the app template's starter plugin are converted
tovplugin.yaml; the platform e2e suites run against them.
vski seed: seed files for dev and initial deploymentsIaC deliberately doesn't manage record data. Seeds fill that gap: sample
data for development and initial deployments, as YAML files in git —
typicallyseeds/, one file per seed, the file name is the seed name.# seeds/dev.yaml version: 1 database: default collections: notes: - id: seed-welcome # stable ids make re-runs idempotent title: Welcome body: Hello from a seed filevski seed seeds # augment (default): insert only missing records vski seed seeds --overwrite # re-apply: update existing records by id vski seed seeds --drop --yes # empty seeded collections first, then insert- Every applied file is recorded in a
_seedstable in the target
database (seed name + sha256 of the file); in the default mode an
unchanged seed is skipped, sovski seedis safe to re-run on every
deploy.--overwriteand--dropalways re-apply. - The three modes are mutually exclusive flags; augment is the default.
--dropdeletes existing records of the seeded collections (through the
records API, so realtime/webhooks/pipeline triggers fire), prompts in
interactive use and requires--yesunder--json. - Records without an
idare always inserted (the server assigns one);
give records ids when you want idempotent behavior. A manually deleted
seeded record stays deleted until the file changes (or--overwrite),
at which point it is re-inserted. - Seeding needs an admin API key (the
_seedstable is maintained through
the SQL endpoint) and the collections to exist — apply IaC first. Files
are strict like IaC: unknown keys, wrong versions and bad collection
names are load-time errors. vski seedis also a thin SDK surface:vski.seed.load_seeds()/
SeedRunnerfor programmatic use.
Template:
plugins/directory, seeds demo (app template)The app template matches the platform
conventions:src/is renamed toplugins/— what it always contained (plugin
source baked into the image at/app/plugins); the dev overlay now
mounts./plugins, the Dockerfile, Makefile, unit-test layout checks
and docs follow.- The starter plugin ships
vplugin.yaml; the layout unit tests parse
the YAML manifest (PyYAML rides in withvski-sdk[cli]). - A
seeds/dev.yamldemo plus amake seedtarget, and an e2e test
proving the loop: seed → records exist → re-run skipped by file hash. - Template pins move to
vski-sdk[cli]>=0.11,<0.12. - Fixed the template's unit suite against current pytest-asyncio (its
filterwarningsescalation crashed on the plugin's configure-time
deprecation;asyncio_default_fixture_loop_scopeis now set
explicitly).
Also in this release
- Wiki: Plugins and the
tutorial showvplugin.yaml; CLI
gains a Seeds section; IaC's
"not managed" list points record seeding atvski seed;
Project Boilerplate
reflects theplugins/layout. gopkg.in/yaml.v3becomes a direct dependency of the server (manifest
parsing; it was already in the module graph).
Tests
- Server: new unit tests for manifest parsing (YAML, legacy JSON,
canonical-JSON output, invalid inputs); the full services suite passes. - Python SDK: 10 new seed unit tests (loader strictness, hash
idempotency, augment/overwrite/drop semantics over a fake client) and a
seed e2e suite against a real server (apply →_seedshash row → skip →
drift +--overwrite→--dropcounts → destructive-guard). The full
e2e suite (130 tests) passes, including the plugins suites now running
against YAML manifests end-to-end. - Template: unit suite passes with the new layout; the seed e2e covers
apply + idempotent skip.
Compatibility
- Additive.
vski-plugin.jsonmanifests keep working (discovery order:
vplugin.yaml,vplugin.yml,vski-plugin.json); the catalog API is
unchanged — the storedmanifestis canonical JSON regardless of
source format. vski seedwrites one new table (_seeds) per seeded database,
created on first use through the admin SQL endpoint; no server changes
are required to use it against an existing deployment.- vski-sdk 0.11.0 (published as part of this release) keeps the 0.10 API;
the new surface isvski.seedand thevski seedCLI command. - Distributions copying the template should rename
src/→plugins/
and their manifests tovplugin.yamlat their leisure — the old layout
keeps working with the old manifest name.
Downloads
-
Source code (ZIP)
2 downloads
-
Source code (TAR.GZ)
2 downloads
- The server (catalog scan at boot and on