warg.toml

[macovedj]

At this point there are four CLI tools I'm aware of that use or plan to use warg clients (cargo-component, wit, wac, wow), but no consistent config file for warg packages, leaving it up to these tool chains to decide what goes in their respective .toml/kdl files.

I'm proposing warg.toml, though the name/format could be changed. I do think that there are some known issues that could be made better by having consistency though.

Primarily, wit package names influence how their interfaces are imported/used, yet warg package are not influenced by these package names. Specifically, at the top of wit files, it is required that there be declared namespace:name(@x.x.x)?. We should enforce across warg consumers that this matches what is specified in warg.toml.

This is an issue for consistency in names as well as versions. First of all, nothing prevents publishing foo:bar as anything:else when using the warg client, which can break package resolution, as resolution can use package name content rather than warg records. Also, if the package name content is foo:bar@x.x.x then imports are required to follow the form

use foo:bar/interface@x.x.x.{items},

but publishing using the version info with the package name foo:bar requires

use foo:bar/interface.{items}

instead, and nothing requires that x.x.x matches what the package is actually published as.

So it seems that at a minimum we should be including fields for namespace, name, and version.

Something to be considered is what flavor of enforcement is best for library importers to be able to tell from a published version whether their imports should or should not included semver. In the initial iteration I'm leaning towards always requiring that the wit package name have semver present that matches what is in the warg.toml, but am curious what others think.

It's also been mentioned several times that we namespace configuration that isn't global, that could be captured on a project level. This seems like a great place for that to live too, as any warg consumer will need to leverage it. Namely, we can have

some-namespace = <registry-domain>
another-namespace = <registry-domain>

and the warg client would place greater precedence on mappings in warg.toml than what is configured globally.

Of course there's lots of room for other general metadata to be specified here as well (author, website, etc).

I originally opened an issue in cargo-component when thinking about how to handle resolution failures when package names/versions don't match how they're published, but figured this probably needs a solution for all tools that leverage warg.

[lann]

Based on discussion in https://github.com/bytecodealliance/wasm-pkg-tools/discussions/3 I think we would call this wit.toml and manage registry config separately, but the questions around version config are still relevant.

[macovedj]

In the case of wa.dev I'm planning on enforcing wit package declarations to include versions on publish, so any use statement would require a version be explicit. IIIRC Luke had expressed an interest in specifying the version in the config to alleviate authors from having to include the version everywhere, which I believe would require that when wit files are "built" into a binary (like wit build does) that we would have to swap in a versioned type name for the unversioned. Would have to look into the level of work, which I think depends on how the binaries are currently being encoded. Was thinking this might make sense to prioritize after wit moves to this repo, if that is happening relatively soon.