Skip to content

blockether.vis.extension_package

Extension manifest validation and trusted source installation APIs.

For building, distributing and installing packages, use the extension package guide.

CATALOG = 'https://vis.blockether.com'
CATEGORIES = ('tools', 'providers', 'workflows')
LATEST = 'latest'
LOCK_WAIT_S = 300
MAX_METADATA = 131072
def project_subdirectory(value=''):

An empty value or dot selects the repository root. Otherwise, use a portable path.

def github_repository(value):

Accept a GitHub owner/repository slug or HTTPS repository URL, without credentials.

def github_source(value, subdirectory=None):

Split one catalog identifier into a repository URL and its project folder.

Accepts owner/repository, the Extension Center listing path owner/repository/folder, an HTTPS GitHub repository URL with an optional folder, and a listing URL such as https://vis.blockether.com/extensions/owner/repository/folder. If subdirectory is empty, the identifier sets the folder. If both name a folder, the two folders must agree.

def manifest_metadata(text, vis_version=None, python_version=None):

Parse and validate manifest metadata without importing publisher code.

Arguments:
  • text: Contents of pyproject.toml, at most 128 KiB when UTF-8 encoded.
  • vis_version: If supplied, require the declared vis-agent dependency to accept this version.
  • python_version: If supplied, check the requires-python constraint.
Returns:

A metadata dictionary containing normalized name and version, description, category, Python requirement, dependencies, source paths and skills. Each skill is a path and a settings flag; False keeps the skill out of settings.

Raises:
  • ValueError: Required metadata, dependency constraints or portable paths are invalid, or a supplied runtime version is incompatible.
def inspect_source(directory, vis_version=None, python_version=None):

Inspect a local project without importing or executing its Python code.

Arguments:
  • directory: Existing folder containing pyproject.toml and extension.py.
  • vis_version: Optional Vis version to check against its SDK requirement.
  • python_version: Optional Python version to check for compatibility.
Returns:

Validated metadata, including source information. Managed installations keep their GitHub identity. They do not become anonymous local paths.

Raises:
  • OSError: A path is missing or unreadable.
  • ValueError: The manifest or project layout is invalid or incompatible.
def versions(source, subdirectory=None, directory=None):

List approved releases for a catalog identifier, including the installed version.

A source may name its project folder, as owner/repository/folder or the matching GitHub or Extension Center URL. With no folder, use the sole installed project from this repository in the selected scope, or the repository root when it is not installed.

def install( source, directory, trust=False, subdirectory='', revision=None, vis_version=None, version=None, save=False):

Install an approved version, an explicit SHA, or a linked local project.

Without a selector, install uses the latest approved stable release, never a moving branch. A GitHub source can include its project folder, as owner/repository/folder. Release selection does not import publisher code. Dependencies are prepared on reload.

Save admits the source as sync-owned and returns its declaration and a rollback token. The host writes the configuration and then discards the token on success.

def update( source, directory, trust=False, version=None, vis_version=None, subdirectory=None):

Update a managed repository slug or URL. Name a folder if several are installed.

def rollback( source, directory, trust=False, version=None, vis_version=None, subdirectory=None):

Restore a managed repository slug or URL's previous pinned source or an older release.

Versions still on disk are validated and activated again, and local edits stay. Missing versions are fetched at their pinned revision. Dependencies are resolved on /reload.

def rollback_saved_install(directory, name, save_state):

Undo this saved admission after configuration failed, never a later installation.

The host returns the opaque token from install(save=True). Source checkouts and Git snapshots stay on disk. Unrelated sync records and externally changed links are not removed.

def sync( configured, directory, trust=False, refresh=False, prune=False, dry_run=False, vis_version=None):

Reconcile one YAML scope. Reuse pins until refresh, and prune only owned links.

A latest version follows the newest approved stable release on every sync. Receipts and pointers are atomic. Old Git snapshots and local source stay on disk. A failed package is reported, and its previous source and other packages stay. Dry-run makes no writes, imports or network calls. After source admission, the host prepares dependencies with upstream uv's own readiness and cache checks.