blockether.vis.extension_package

Extension manifest validation and trusted source installation APIs.

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

CATEGORIES = ('tools', 'providers', 'workflows')

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 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 skill paths.

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 retain their GitHub identity rather than becoming anonymous local paths.

Raises:

OSError: A path is missing or unreadable.
ValueError: The manifest or project layout is invalid or incompatible.

CATALOG = 'https://vis.blockether.com'

def versions(source, subdirectory=None, directory=None):

List approved releases for a repository slug or URL, including its installed version.

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.

No selector means the latest approved stable release, never a moving branch. Release selection does not import publisher code. Dependency preparation is on reload. Save admits the source as sync-owned and returns its declaration and a rollback token; the host writes configuration, 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; select a folder when 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.

Retained versions are validated and reactivated, preserving local edits. 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 are retained. Unrelated sync records and externally changed links survive.

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.

Receipts and pointers are atomic. Old Git snapshots and local source are retained. A failed package is reported without removing its previous source or other packages. Dry-run performs no writes, imports or network calls. Dependencies are prepared by the host after source admission, using upstream uv's own readiness/cache checks.