diff --git a/src/apis/terminal.md b/src/apis/terminal.md index 92dcf216..2a45f0fc 100644 --- a/src/apis/terminal.md +++ b/src/apis/terminal.md @@ -1,4 +1,7 @@ # Terminal API +It is extremely rare for an app to have direct access to the terminal api. +Normally, the terminal will be used to call scripts, which will have access to the process in question. +For documentation on using, writing, publishing, and composing scripts, see the [terminal use documentation](../terminal.md), or for a quick start, the [script cookbook](../cookbook/writing_scripts.md). The Kinode terminal is broken up into two segments: a Wasm app, called `terminal:terminal:sys`, and a runtime module called `terminal:distro:sys`. The Wasm app is the central area where terminal logic and authority live. @@ -21,7 +24,7 @@ For example, `hi:terminal:sys` can be shortened to just `hi` as in: `hi default- The other most commonly used script is `m:terminal:sys`, or just `m` - which stands for `Message`. `m` let's you send a request to any node or application like so: ```bash -m john.os@proc:pkg:pub {"foo":"bar"} +m john.os@proc:pkg:pub '{"foo":"bar"}' ``` Note that if your process has the ability to message the `terminal` app, then that process can call any script - of which there may be many on a machine, so we cannot possibly write all of them down in this document. diff --git a/src/cookbook/writing_scripts.md b/src/cookbook/writing_scripts.md index 188d9af4..fd36a360 100644 --- a/src/cookbook/writing_scripts.md +++ b/src/cookbook/writing_scripts.md @@ -7,9 +7,9 @@ When writing a script, you cannot control the `OnExit` behavior like you can wit - Scripts are registered in the `scripts.json` file instead of the `manifest.json` file ## Writing a Script -Let's look at the simplest possible script: `echo`, which takes in an argument, and prints it out again: +Consider the simplest possible script: `echo`, which takes in an argument, and prints it out again: ```rust -use kinode_process_lib::{await_next_request_body, call_init, println, Address}; +use kinode_process_lib::{await_next_request_body, call_init, println, Address, Response}; wit_bindgen::generate!({ path: "wit", @@ -27,22 +27,24 @@ fn init(_our: Address) { return; }; - println!( - "{}", - String::from_utf8(args).unwrap_or("echo: error".into()) - ); + let _ = Response::new().body(args).send(); } ``` -From writing applications, this should look very familiar - the imports, `wit_bindge::generate!`, `call_init!`, `init(our: Address)`, etc. are all exactly the same. +From writing applications, this should look very familiar - the imports, `wit_bindgen::generate!`, `call_init!`, `init(our: Address)`, etc. are all exactly the same. The first unique thing about scripts is that we will have no `loop` where we `await_message`. Instead, our initial arguments will come from a single message from the terminal - which we get by calling `await_next_message_body()`. Next, all we do is `String`ify the message body, and print it out. Arbitrary logic can be put below `await_next_message_body` - just like an app, you can fire-off a number of requests, choose to await their responses, handle errors, etc. just like normal. +In this case, `echo` sends a `Response` containing the arguments passed in. +The `Response` enables composition of scripts via [piping](../terminal.md#piping-and-composing-scripts), so that the output of `echo` can serve as the input to the next program. +Not every script needs to end with a `Response`. +It would be valid to simply `println` the `args` and terminate, but this would mean that the script has no "return value" to compose with other scripts via pipes. + ## Publishing a Script -Unlike processes accociated with a long-running application, which will be put into the `manifest.json`, scripts must be registered in a separate `scripts.json` file. -While very similar, there are a few important differences; let's take a look at an example that could live in your packages `pkg/scripts.json` file: +Unlike processes associated with a long-running application, which will be put into the `manifest.json`, scripts must be registered in a separate `scripts.json` file. +While very similar, there are a few important differences; here's an example that could live in your packages `pkg/scripts.json` file: ```json { "echo.wasm": { @@ -58,7 +60,7 @@ This `scripts.json` file corresponds to a package which publishes a single scrip The keys of this object are the process paths inside of the `pkg/` folder. The name of the script will be the file path, with `.wasm` taken off. The object that `echo.wasm` points to is very similar to `manifest.json`, with a few things removed, and `root` has been added: -- `root` means that all the capabilities held by the `terminal:terminal:sys` are passed to this script. This is rarely needed. +- `root` means that all the capabilities held by the `terminal:terminal:sys` are passed to this script (this is powerful, and rarely needed) - `public`: same as `manfiest.json` - corresponds to whether or not other processes can message `echo.wasm` without the messsaging cap - `requestNetworking`: same as `manfiest.json` - corresponds to whether or not this script will need to send messaages over the network - `requestCapabilities`: same as `manifest.json` - a list of capabilities that will be granted to this script on startup (NOTE if you have `root`, there is no reason to populate `requestCapabilities` as well) diff --git a/src/terminal.md b/src/terminal.md index 897f2e8b..d6554784 100644 --- a/src/terminal.md +++ b/src/terminal.md @@ -1,9 +1,9 @@ # Terminal -## Basic Usage and Utilities +## Commands All commands in the terminal are calling scripts - a special kind of process. -KinodeOS comes pre-loaded with a number of scripts useful for debugging and everyday use. +Kinode OS comes pre-loaded with a number of scripts useful for debugging and everyday use. These scripts are fully named `