• v0.15.2 9af0e04dd1

    v0.15.2 Stable

    x released this 2026-11-02 20:50:12 +00:00 | 22 commits to main since this release

    VSKI 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)
      discovers vplugin.yaml (and vplugin.yml); the legacy
      vski-plugin.json is still read — first match wins — so existing
      distributions keep working. New plugins should use the YAML name.
    • Whatever the source format, the API's manifest field 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
      to vplugin.yaml; the platform e2e suites run against them.

    vski seed: seed files for dev and initial deployments

    IaC deliberately doesn't manage record data. Seeds fill that gap: sample
    data for development and initial deployments, as YAML files in git —
    typically seeds/, 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 file
    
    vski 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 _seeds table in the target
      database (seed name + sha256 of the file); in the default mode an
      unchanged seed is skipped, so vski seed is safe to re-run on every
      deploy. --overwrite and --drop always re-apply.
    • The three modes are mutually exclusive flags; augment is the default.
      --drop deletes existing records of the seeded collections (through the
      records API, so realtime/webhooks/pipeline triggers fire), prompts in
      interactive use and requires --yes under --json.
    • Records without an id are 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 _seeds table 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 seed is also a thin SDK surface: vski.seed.load_seeds() /
      SeedRunner for programmatic use.

    Template: plugins/ directory, seeds demo (app template)

    The app template matches the platform
    conventions:

    • src/ is renamed to plugins/ — 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 with vski-sdk[cli]).
    • A seeds/dev.yaml demo plus a make seed target, 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
      filterwarnings escalation crashed on the plugin's configure-time
      deprecation; asyncio_default_fixture_loop_scope is now set
      explicitly).

    Also in this release

    • Wiki: Plugins and the
      tutorial show vplugin.yaml; CLI
      gains a Seeds section; IaC's
      "not managed" list points record seeding at vski seed;
      Project Boilerplate
      reflects the plugins/ layout.
    • gopkg.in/yaml.v3 becomes 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 → _seeds hash row → skip →
      drift + --overwrite → --drop counts → 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.json manifests keep working (discovery order:
      vplugin.yaml, vplugin.yml, vski-plugin.json); the catalog API is
      unchanged — the stored manifest is canonical JSON regardless of
      source format.
    • vski seed writes 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 is vski.seed and the vski seed CLI command.
    • Distributions copying the template should rename src/ → plugins/
      and their manifests to vplugin.yaml at their leisure — the old layout
      keeps working with the old manifest name.
    Downloads