Merge pull request #215 from kinode-dao/develop

Develop

src/SUMMARY.md

@@ -12,6 +12,7 @@
     - [Capability-Based Security](./process/capabilities.md)
     - [Startup, Spindown, and Crashes](./process/startup.md)
     - [Extensions](./process/extensions.md)
+    - [WIT APIs](./process/wit-apis.md)
   - [Networking Protocol](./networking_protocol.md)
   - [Public Key Infrastructure](./pki.md)
   - [HTTP Server & Client](./http_server_and_client.md)
@@ -35,6 +36,7 @@
   - [`connect`](./kit/connect.md)
   - [`reset-cache`](./kit/reset-cache.md)
   - [`boot-real-node`](./kit/boot-real-node.md)
+  - [`view-api`](./kit/view-api.md)
 - [My First Kinode Application](./build-and-deploy-an-app.md)
   - [Environment Setup](./my_first_app/chapter_1.md)
   - [Sending and Responding to a Message](./my_first_app/chapter_2.md)

src/kit-dev-toolkit.md

@@ -18,3 +18,4 @@
 * [`kit connect`](./kit/connect.md)
 * [`kit reset-cache`](./kit/reset-cache.md)
 * [`kit boot-real-node`](./kit/boot-real-node.md)
+* [`kit view-api`](./kit/view-api.md)

src/kit/view-api.md

@@ -0,0 +1,59 @@
+# `kit view-api`
+
+`kit view-api` fetches the list of APIs or a specific API for the given package.
+`view-api` relies on a node to do so, e.g.
+
+```
+kit view-api --port 8080
+```
+
+lists all the APIs of packages downloaded by the Kinode running at port 8080.
+
+## Example Usage
+
+```
+# Fetch and display the API for the given package
+kit view-api app_store:sys-v0
+```
+
+## Discussion
+
+Currently broken!
+TODO: fix & document
+
+## Arguments
+
+```
+$ kit view-api --help
+Fetch the list of APIs or a specific API
+
+Usage: kit view-api [OPTIONS] [PACKAGE_ID]
+
+Arguments:
+  [PACKAGE_ID]  Get API of this package (default: list all APIs)
+
+Options:
+  -p, --port <NODE_PORT>  Node port: for use on localhost (overridden by URL) [default: 8080]
+  -u, --url <URL>         Node URL (overrides NODE_PORT)
+  -h, --help              Print help
+```
+
+### Positional arg: `PACKAGE_ID`
+
+Get the API of this package.
+By default, list the names of all APIs.
+
+### `--port`
+
+short: `-p`
+
+For nodes running on localhost, the port of the node; defaults to `8080`.
+`--port` is overridden by `--url` if both are supplied.
+
+### `--url`
+
+short: `-u`
+
+The URL the node is hosted at.
+Can be either localhost or remote.
+`--url` overrides `--port` if both are supplied.

src/my_first_app/chapter_1.md

@@ -56,43 +56,68 @@ By default, the `kit new` command creates a simple, one-process package, a chat
 Other templates, including a Python template and a UI-enabled template can be used by passing [different flags to `kit new`](../kit/new.html#discussion).
 The default template looks like:
 
-```bash
+```
 $ tree my_chat_app
 my_chat_app
-    ├── Cargo.toml
-    ├── metadata.json
-    ├── my_chat_app
-    │   ├── Cargo.toml
-    │   └── src
-    │       └── lib.rs
-    ├── pkg
-    │   ├── manifest.json
-    │   └── scripts.json
-    └── send
-        ├── Cargo.toml
-        └── src
-            └── lib.rs
+├── api
+│   └── my_chat_app:template.os-v0.wit
+├── Cargo.toml
+├── metadata.json
+├── my_chat_app
+│   ├── Cargo.toml
+│   └── src
+│       └── lib.rs
+├── pkg
+│   ├── manifest.json
+│   └── scripts.json
+├── send
+│   ├── Cargo.toml
+│   └── src
+│       └── lib.rs
+└── test
+    ├── my_chat_app_test
+    │   ├── api
+    │   │   ├── my_chat_app:template.os-v0.wit
+    │   │   ├── my_chat_app_test:template.os-v0.wit
+    │   │   └── tester:sys-v0.wit
+    │   ├── Cargo.toml
+    │   ├── metadata.json
+    │   ├── my_chat_app_test
+    │   │   ├── Cargo.toml
+    │   │   └── src
+    │   │       ├── lib.rs
+    │   │       └── tester_lib.rs
+    │   └── pkg
+    │       └── manifest.json
+    └── tests.toml
 ```
 
 The `my_chat_app/` package here contains two processes:
 - `my_chat_app/` — containing the main application code, and
 - `send/` — containing a [script](../cookbook/writing_scripts.html).
 
 Rust process directories, like the ones here, contain:
-- `src/` - source files where the code for the process lives, and
-- `Cargo.toml` - the standard Rust file specifying dependencies, etc., for that process.
+- `src/` — source files where the code for the process lives, and
+- `Cargo.toml` — the standard Rust file specifying dependencies, etc., for that process.
 
 Another standard Rust `Cargo.toml` file, a [virtual manifest](https://doc.rust-lang.org/cargo/reference/workspaces.html#virtual-workspace) is also included in `my_chat_app/` root.
 
 Also within the package directory is a `pkg/` directory.
 The `pkg/` dirctory contains two files:
-- `manifest.json` - specifes information the Kinode needs to run the package, and
-- `scripts.json` - specifies details needed to run [scripts](../cookbook/writing_scripts.html).
+- `manifest.json` — required: specifes information the Kinode needs to run the package, and
+- `scripts.json` — optional: specifies details needed to run [scripts](../cookbook/writing_scripts.html).
 
 The `pkg/` directory is also where `.wasm` binaries will be deposited by [`kit build`](#building-the-package).
 The files in the `pkg/` directory are injected into the Kinode with [`kit start-package`](#starting-the-package).
 
-Lastly, `metadata.json` contains app metadata which is used in the Kinode [App Store](./chapter_5.html)
+The `metadata.json` is a required file that contains app metadata which is used in the Kinode [App Store](./chapter_5.html)
+
+The `api/` directory contains the [WIT API](../process/wit-apis.md) for the `my_chat_app` package, see more discussion [below](#api).
+
+Lastly, the `test/` directory contains tests for the `my_chat_app` package.
+The `tests.toml` file specifies the configuration of the tests.
+The `my_chat_app_test/` direcotry is itself a package: the test for `my_chat_app`.
+For more discussion of tests see [`kit run-tests`](../kit/run-tests.md), or see usage, [below](#testing-the-package).
 
 Though not included in this template, packages with a frontend have a `ui/` directory as well.
 For an example, look at the result of:
@@ -117,7 +142,6 @@ $ cat my_chat_app/pkg/manifest.json
         "request_networking": true,
         "request_capabilities": [
             "http_server:distro:sys",
-            "net:distro:sys"
         ],
         "grant_capabilities": [],
         "public": true
@@ -162,14 +186,20 @@ $ cat my_chat_app/metadata.json
         "mirrors": [],
         "code_hashes": {
             "0.1.0": ""
-        }
+        },
+        "wit_version": 0,
+        "dependencies": []
     },
     "external_url": "",
     "animation_url": ""
 }
 ```
-Here, the `publisher` is some default value, but for a real package, this field should contain the KNS ID of the publishing node.
+Here, the `publisher` is the default value (`"template.os"`), but for a real package, this field should contain the KNS ID of the publishing node.
 The `publisher` can also be set with a `kit new --publisher` flag.
+The `wit_version` is an optional field.
+If elided, the package will use [`kinode.wit` `0.7.0`](https://github.com/kinode-dao/kinode-wit/blob/aa2c8b11c9171b949d1991c32f58591c0e881f85/kinode.wit).
+If included with a value of `0`, it will use [`kinode.wit` `0.8.0`](https://github.com/kinode-dao/kinode-wit/blob/758fac1fb144f89c2a486778c62cbea2fb5840ac/kinode.wit).
+The `dependencies` field is also optional; see discussion in [WIT APIs](../process/wit-apis.md).
 The rest of these fields are not required for development, but become important when publishing a package with the [`app_store`](https://github.com/kinode-dao/kinode/tree/main/kinode/packages/app_store).
 
 As an aside: each process has a unique `ProcessId`, used to address messages to that process, that looks like
@@ -180,6 +210,13 @@ As an aside: each process has a unique `ProcessId`, used to address messages to
 
 You can read more about `ProcessId`s [here](../process/processes.md#overview).
 
+### `api/`
+
+The `api/` directory is an optional directory where packages can declare their public API.
+Other packages can then mark a package as a dependency in their `metadata.json` and
+
+For further reading, see discussion in [WIT APIs](../process/wit-apis.md), and [`kit view-api`](../kit/view-api.md).
+
 ## Building the Package
 
 To build the package, use the [`kit build`](../kit/build.md#) tool.
@@ -319,3 +356,19 @@ kit inject-message my_chat_app:my_chat_app:template.os '{"Send": {"target": "fak
 kit inject-message my_chat_app:my_chat_app:template.os '{"Send": {"target": "fake.dev", "message": "replying from fake2.dev using first method..."}}' --node fake2.dev
 kit inject-message my_chat_app:my_chat_app:template.os '{"Send": {"target": "fake.dev", "message": "and second!"}}' -p 8081
 ```
+
+## Testing the Package
+
+To run the `my_chat_app/` tests, close all fake nodes and then run
+
+```bash
+kit run-tests my_chat_app
+```
+
+or, if already in the `my_chat_app/` package directory:
+
+```bash
+kit run-tests
+```
+
+For more details, see [`kit run-tests`](../kit/run-tests.md).

src/process/wit-apis.md

@@ -0,0 +1,20 @@
+# WIT APIs
+
+Kinode OS runs processes that are WebAssembly components, as discussed [elsewhere](./processes.md#wasm-and-kinode).
+Two key advantages of WebAssembly components are
+
+1. The declaration of types and functions using the cross-language Wasm Interface Type (WIT) language
+2. The composibility of components.
+See discussion [here](https://component-model.bytecodealliance.org/design/why-component-model.html).
+
+Kinode processes make use of these two advantages.
+Processes within a package — a group of processes, also referred to as an app — may define an API in WIT format.
+Each process defines a [WIT interface](https://component-model.bytecodealliance.org/design/wit.html#interfaces); the package defines a [WIT world](https://component-model.bytecodealliance.org/design/wit.html#interfaces).
+The API is published alongside the package.
+Other packages may then import and depend upon that API, and thus communicate with the processes in that package.
+The publication of the API also allows for easy inspection by developers or by machines, e.g., LLM agents.
+
+More than types can be published.
+Because components are composable, packages may publish, along with the types in their API, library functions that may be of use in interacting with that package.
+When set as as a dependency, these functions will be composed into new packages.
+Libraries unassociated with packages can also be published and composed.