wit-interface-design
/wit-interface-design
Projektuje i sprawdza interfejsy WIT (WebAssembly Interface Types), światy i pakiety, tak aby były przenośne i ograniczone uprawnieniami.
- Autor
- cosmonic-labs ↗
- Repozytorium
- skills ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 12.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 7
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 12.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Projektuje i sprawdza interfejsy WIT (WebAssembly Interface Types), światy i pakiety, tak aby były przenośne i ograniczone uprawnieniami.
Wyzwalacze z opisu
Oryginalny opis (EN)
Design and review WIT (WebAssembly Interface Types) interfaces, worlds and packages so they are capability-scoped, async, virtualizable and portable. Use this skill whenever the user is designing or reviewing a `.wit` file, adding a function, resource or interface to a WIT package, deciding what a component should import or export, designing a plugin or provider API (for example `wasmcloud:` packages), choosing between `enum` and `variant`, modeling errors, naming interfaces or resources, versioning a WIT package, or asking "how should I model this in WIT?", even if they never say "interface d
Jak działa
- Start with the four areas
- Core rules and why
- Review checklist
- Reference files
- Related skills
Podgląd SKILL.md
--- name: wit-interface-design description: Design and review WIT (WebAssembly Interface Types) interfaces, worlds and packages so they are capability-scoped, async, virtualizable and portable. Use this skill whenever the user is designing or reviewing a `.wit` file, adding a function, resource or interface to a WIT package, deciding what a component should import or export, designing a plugin or provider API (for example `wasmcloud:` packages), choosing between `enum` and `variant`, modeling errors, naming interfaces or resources, versioning a WIT package, or asking "how should I model this in WIT?", even if they never say "interface design". For building, composing, or running components, use webassembly-component-development instead. license: Apache-2.0 --- # WIT Interface Design Design the contract first, then write the code. A good WIT API reads as a **capability grant**: someone can look at a component's imports and know exactly what it is allowed to do. The rules below are modeled on the WASI 0.3.x proposals (`wasi:cli`, `clocks`, `filesystem`, `http`, `random`, `sockets`) and `wasmcloud:secrets@2.1.0`. ## Start with the four areas Every component's contract has four parts. Settle each one before writing WIT. | Area | Question | Where it lives in WIT | |------|----------|-----------------------| | **Triggers** | What events, requests or streams start the component's work? | **Exports** | | **Responses** | What does it return, and who owns the data? | Return types, `own` vs `borrow`, `stream` / `future` | | **Side-effects** | What can it change outside itself? | **Imports**, one per capability | | **Errors** | Which failures does it deliberately return? | `result<T, E>` with a typed `E` | Every component is a reactor: each export is a reaction to something (`handle` a request, `run`, `on-message`). Design components as handlers that are given work, not scripts that fetch it. The world is the whole contract: exports say what starts it, imports say what it may do. Traps mean bugs or violated preconditions; expected failures belong in the signature. A good WIT API is strictly decoupled (names a capability, not a vendor), virtualizable, mockable (a test double is just another component implementing the interface), and portable (maps cleanly to any language: no exceptions, callbacks, pointers, OS paths, or threads). ## Core rules and why **Imports are grants.** Write "the guest may ___" for every interface (resolve names, read the system clock, `get-directories` from preopens, reveal a secret). If the sentence needs "and", split the interface. This keeps least privilege auditable from the world alone. One capability per interface, named for the capability, not the implementation. See [capability-grants.md](capability-grants.md). **One singular thing = a labeled import.** To give a guest one secret, import `db-password: wasmcloud:secrets/secret` with `get: async func() -> secret`, not `get(key: string)`. There is no key to forge, and the runtime can check the binding before instantiation. Also in [capability-grants.md](capability-grants.md). **Import WASI; never reinvent it.** Clocks, random, filesystem, sockets, name lookup, HTTP and stdio already exist. Reuse its interfaces and types (`duration`, `ip-address`) so grants stay legible and components stay interoperable. See [capability-grants.md](capability-grants.md). **Keep interfaces granular.** Split by independently grantable power (read vs write, lookup vs reveal, consumer vs producer). A guest that only needs one power shouldn't receive another. **Async by default.** Declare `async func` unless the call is time-sensitive and must be sync (`system-clock.now`). Cheap is not a reason to be sync: changing sync to async later breaks every consumer. This applies to resource methods too. **Every API must be virtualizable.** Design as if another guest component implements it, never "something the host provides". Document in terms of implementer and caller. Give the consumer and provider sides symmetric shapes (as `wasi:http` `client.send` and `handler.handle`) so components chain as middleware. See [async-and-resources.md](async-and-resources.md) and [http-derived-patterns.md](http-derived-patterns.md). **Resources are singular nouns** (`descriptor`, `secret`, `tcp-socket`). Collections are `list<secret>`. Consume-by-move for one-shot operations, and document parent/child lifetimes and mutability. **Open sets use `variant` + `other`; closed sets use `enum`.** An `enum` can never gain a case without breaking consumers, so choose it only for sets you commit to never extending (`ip-address-family`). Otherwise end a `variant` with `other(option<string>)`. See [errors-and-enums.md](errors-and-enums.md). **Typed errors.** Return `result<T, E>` where `E` names the failure modes callers can act on. A `string` payload is fine for detail; a bare `string` error is not. Model cases on an industry standard (IANA, RFC, POSIX) when one exists. See [errors-and-enums.md](errors-and-enums.md). **Version for compatibility.** `@since` on every interface; `@deprecated` instead of deleting; break only on a minor bump at `0.x` or a major bump at `1.0+`. See [versioning.md](versioning.md). **Name consistently.** Kebab-case, verb-first functions, `get-` / `set-` on resource accessors, shared types in an interface named `types`, uppercase acronyms only when required (`DNS-error`). Details, worlds, types and documentation in [conventions.md](conventions.md). ## Review checklist 1. Can you state triggers (exports), responses and ownership, side-effects (imports) and errors in one sentence each? 2. Does it reimplement something WASI already provides? Import it instead. 3. Is every function `async` (except time-sensitive ones), and could another guest implement the interface? 4. Can each import be read as "the guest may ___"? Does any interface grant more than one independent power? 5. Do open enums and errors use `variant` with a trailing `other`? Are errors typed? 6. Are all resources singular nouns, with ownership and lifetimes documented? 7. Could a single-value grant be a labeled import instead of a key parameter? 8. Is `@since` on every interface, with retired items `@deprecated` rather than removed? 9. Is every interface, type, case and function documented with `///`? ## Reference files | Topic | File | |-------|------| | Capability grants, labeled singular imports, WASI reuse table, granularity | [capability-grants.md](capability-grants.md) | | Async rule, virtualization, resources, resource methods | [async-and-resources.md](async-and-resources.md) | | `enum` vs `variant` + `other`, error design | [errors-and-enums.md](errors-and-enums.md) | | Patterns from `wasi:http@0.3.1`: symmetric interfaces, bodies, construction, parent/child | [http-derived-patterns.md](http-derived-patterns.md) | | Naming, worlds, types, documentation | [conventions.md](conventions.md) | | `@since`, `@deprecated`, breaking-change policy | [versioning.md](versioning.md) | ## Related skills - `webassembly-component-development`: building, composing and running components. - `wash`: the `wash build` / `wash dev` toolchain.
Pliki w paczce (7)
- SKILL.md 7 KB
- async-and-resources.md 4 KB
- capability-grants.md 6 KB
- conventions.md 3 KB
- errors-and-enums.md 3 KB
- http-derived-patterns.md 4 KB
- versioning.md 1 KB
Wersje
W bazie nie ma innych skilli o nazwie wit-interface-design.
Migawka bazy z 13.11.2026 · wersja paczki 5bf868b78ce6 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100wit
Opisuje język WebAssembly Interface Type (WIT): definiowanie interfejsów komponentów, pisanie plików WIT, projektowanie światów i interfejsów oraz system typów Component Model. - 100wash
Pomaga w CLI wash do budowania i uruchamiania komponentów WebAssembly i aplikacji wasmCloud, w tym definicji WIT. - 90webassembly-component-development
Buduje, składa i debuguje komponenty WebAssembly pod WASI 0.3 z natywną asynchronicznością, w tym zależności WIT i niezgodności wersji. - 100go-interface-design
Podaje wzorce projektowania interfejsów w Go: interfejsy niejawne, definicja po stronie konsumenta, weryfikacja zgodności, kompozycja i zasada przyjmuj interfejsy, zwracaj struktury. - 90api-design
Projektuje interfejsy odporne na zmiany po stronie konsumentów: model zasobów, błędy, wersjonowanie, paginacja i zgodność wsteczna. - 96add-export
Udostępnia w JavaScript nową funkcję lub klasę z pakietu Rust WebAssembly, wraz z typami TypeScript i testami.