Merge pull request #186 from jurij-jukic/section-4

Section 4. and 4.X. Kit

src/kit-dev-toolkit.md

@@ -1,6 +1,6 @@
 # kit
 
-`kit` is a tool**kit** to make development on Kinode OS ergonomic.
+[`kit`](https://github.com/kinode-dao/kit) is a CLI tool**kit** to make development on Kinode OS ergonomic.
 
 ## Table of Contents
 

src/kit/boot-fake-node.md

@@ -19,7 +19,7 @@ For example, to start two fake nodes, `fake.os` and `fake2.os`:
 kit boot-fake-node
 
 # In a new terminal
-kit boot-fake-node -h /tmp/kinode-fake-node-2 -p 8081 -f fake2.os
+kit boot-fake-node --home /tmp/kinode-fake-node-2 -p 8081 --fake-node-name fake2.os
 
 # Send a message from fake2.os to fake.os
 # In the terminal of fake2.os:
@@ -34,16 +34,17 @@ Fake nodes make development easier.
 A fake node is not connected to the network, but otherwise behaves the same as a live node.
 Fake nodes are connected to each other on your local machine through a network router that passes messages between them.
 Fake nodes also clean up after themselves, so you don't have to worry about state from a previous iterations messing up the current one.
+If you wish to persist the state of a fake node between boots, you can do so with `--persist`.
 Thus, fake nodes are an excellent testing ground during development for fast iteration.
 
 There are some cases where fake nodes are not appropriate.
-The weakness of fake nodes is also their strength: they are not connected to the live network.
-Though this lack of connectivity makes them easy to spin up and throw away, the downside is no access to services on the network, like remote LLMs.
+The weakness of fake nodes is also their strength: they are not connected to the live Kinode network.
+Though this lack of connectivity makes them easy to spin up and throw away, the downside is no access to services on the network which live Kinodes may provide.
 
 ## Arguments
 
 ```
-$ kit f --help
+$ kit boot-fake-node --help
 Boot a fake node for development
 
 Usage: kit boot-fake-node [OPTIONS]
@@ -63,8 +64,6 @@ Options:
           The port to run the network router on (or to connect to) [default: 9001]
       --rpc <RPC_ENDPOINT>
           Ethereum RPC endpoint (wss://)
-      --testnet
-          If set, use Sepolia testnet
       --persist
           If set, do not delete node home after exit
       --password <PASSWORD>
@@ -79,7 +78,9 @@ Options:
 
 ### `--runtime-path`
 
-Pass to run a local binary or build a local Kinode core repo and use the resulting binary, e.g.
+short: `-r`
+
+Pass to boot a fake node from a local binary or build a local Kinode core repo and use the resulting binary, e.g.
 
 ```
 kit boot-fake-node --runtime-path ~/git/kinode
@@ -91,19 +92,27 @@ Overrides `--version`.
 
 ### `--version`
 
-Fetch and run a specific version of the binary; defaults to most recent version (here, `0.5.0`).
+short: `-v`
+
+Fetch and run a specific version of the binary; defaults to most recent version.
 Overridden by `--runtime-path`.
 
 ### `--port`
 
+short: `-p`
+
 Run the fake node on this port; defaults to `8080`.
 
 ### `--home`
 
+short: `-h`
+
 Path to place fake node home directory at; defaults to `/tmp/kinode-fake-node`.
 
 ### `--fake-node-name`
 
+short: `-f`
+
 The name of the fake node; defaults to `fake.os`.
 
 ### `--network-router-port`
@@ -115,22 +124,31 @@ Additional fake nodes must point to the same port to connect to the fake node ne
 
 The Ethereum RPC endpoint to use, if desired.
 
-### `--testnet`
-
-Connect to the Sepolia testnet rather than the Optimism mainnet.
-
 ### `--persist`
 
 Persist the node home directory after exit, rather than cleaning it up.
 
+Example usage:
+
+``` bash
+kit boot-fake-node --persist --home ./my-fake-node
+```
+
+After shutting down the node, to run it again:
+
+```bash
+kit boot-fake-node --home ./my-fake-node
+```
+
 ### `--password`
 
-The password of the fake node; defaults to `secret`.
+The password of the fake node; defaults to "`secret`".
 
 ### `--release`
 
 If `--runtime-path` is given, build the runtime for release; default is debug.
+The tradeoffs between the release and default version are described [here](https://doc.rust-lang.org/book/ch01-03-hello-cargo.html?highlight=release#building-for-release).
 
 ### `--verbosity`
 
-Set the verbosity of the node; higher is more verbose; default is `0`.
+Set the verbosity of the node; higher is more verbose; default is `0`, max is `3`.

src/kit/build.md

@@ -12,7 +12,7 @@ or
 kit build
 ```
 
-`kit build` builds each process in the package and places the `.wasm` binaries into the `pkg/` directory for installation.
+`kit build` builds each process in the package and places the `.wasm` binaries into the `pkg/` directory for installation with [`kit start-package`](./start-package.md).
 It automatically detects what language each process is, and builds it appropriately (from amongst the supported `rust`, `python`, and `javascript`).
 
 ## Discussion
@@ -23,15 +23,34 @@ Currently, `rs`, `py`, and `js` are supported, corresponding to processes writte
 Note that a package may have more than one process and those processes need not be written in the same language.
 
 After compiling each process, it places the output `.wasm` binaries within the `pkg/` directory at the top-level of the given package directory.
-The `pkg/` directory is the one that is zipped and injected into the node by [`kit start-package`](./start-package.md).
-Thus, after `build`ing, the package is ready for `start-package`.
+Here is an example of what a package directory will look like after using `kit build`:
 
-`kit build` also builds the UI if found in `ui/`.
-There must exist a `ui/package.json` file with `scripts` defined like:
 ```
-"build": "tsc && vite build",
-"copy": "mkdir -p ../pkg/ui && rm -rf ../pkg/ui/* && cp -r dist/* ../pkg/ui/",
-"build:copy": "npm run build && npm run copy",
+rustchat
+├── Cargo.lock
+├── Cargo.toml
+├── metadata.json
+├── pkg
+│   ├── manifest.json
+│   ├── rustchat.wasm
+│   ├── scripts.json
+│   └── send.wasm
+├── rustchat
+│   └── ...
+└── send
+    └── ...
+```
+
+The `pkg/` directory can then be zipped and injected into the node with [`kit start-package`](./start-package.md).
+
+`kit build` also builds the UI if it is found in `pkg/ui/`.
+There must exist a `ui/package.json` file with a `scripts` object containing the following arguments:
+```json
+"scripts": {
+  "build": "tsc && vite build",
+  "copy": "mkdir -p ../pkg/ui && rm -rf ../pkg/ui/* && cp -r dist/* ../pkg/ui/",
+  "build:copy": "npm run build && npm run copy",
+}
 ```
 
 Additional UI dev info can be found [here](../apis/frontend_development.md).
@@ -40,7 +59,7 @@ To both `build` and `start-package` in one command, use `kit build-start-package
 ## Arguments
 
 ```
-$ kit b --help
+$ kit build --help
 Build a Kinode package
 
 Usage: kit build [OPTIONS] [DIR]
@@ -49,25 +68,36 @@ Arguments:
   [DIR]  The package directory to build [default: /home/nick/git/kit]
 
 Options:
-      --ui-only          If set, build ONLY the web UI for the process
-  -q, --quiet            If set, do not print build stdout/stderr
-  -s, --skip-deps-check  If set, do not check for dependencies
-  -h, --help             Print help
+      --no-ui                If set, do NOT build the web UI for the process; no-op if passed with UI_ONLY
+      --ui-only              If set, build ONLY the web UI for the process
+  -s, --skip-deps-check      If set, do not check for dependencies
+      --features <FEATURES>  Pass these comma-delimited feature flags to Rust cargo builds
+  -h, --help                 Print help
 ```
 
 ### Optional positional arg: `DIR`
 
 The package directory to build; defaults to the current working directory.
 
+### `--no-ui`
+
+Do not build the web UI for the process.
+Does nothing if passed with `--ui-only`.
+
 ### `--ui-only`
 
 Build ONLY the UI for a package with a UI.
 Otherwise, for a package with a UI, both the package and the UI will be built.
 
-### `--quiet`
-
-Don't print the build stdout/stderr.
-
 ### `--skip-deps-check`
 
+short: `-s`
+
 Don't check for dependencies.
+
+### `--features`
+
+Build the package with the given [cargo features](https://doc.rust-lang.org/cargo/reference/features.html).
+
+Features can be used like shown [here](https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options).
+Currently the only feature supported system-wide is `simulation-mode`.

src/kit/dev-ui.md

@@ -15,7 +15,7 @@ kit dev-ui
 ## Arguments
 
 ```
-$ kit d --help
+$ kit dev-ui --help
 Start the web UI development server with hot reloading (same as `cd ui && npm i && npm start`)
 
 Usage: kit dev-ui [OPTIONS] [DIR]
@@ -36,15 +36,21 @@ The UI-enabled package directory to serve; defaults to current working directory
 
 ### `--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.
 
 ### `--skip-deps-check`
 
+short: `-s`
+
 Don't check for dependencies.

src/kit/inject-message.md

@@ -22,7 +22,7 @@ To instead "fire and forget" a message and exit immediately, use the [`--non-blo
 ## Arguments
 
 ```
-$ kit i --help
+$ kit inject-message --help
 Inject a message to a running Kinode
 
 Usage: kit inject-message [OPTIONS] <PROCESS> <BODY_JSON>
@@ -50,31 +50,40 @@ The message body.
 
 ### `--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.
 
 ### `--node`
 
+short: `-n`
+
 Node to target (i.e. the node portion of the address).
-E.g.
 
-```bash
+E.g., the following, sent to the port running `fake.os`, will be forwarded from `fake.os`'s HTTP server to `fake2@foo:foo:template.os`:
+
+``` bash
 kit inject-message foo:foo:template.os '{"Send": {"target": "fake.os", "message": "wow, it works!"}}' --node fake2.os
 ```
 
-sent to the port running `fake.os` will forward the message from `fake.os`s HTTP server to `fake2@foo:foo:template.os`.
-
 ### `--blob`
 
+short: `-b`
+
 Path to file to include as `lazy_load_blob`.
 
 ### `--non-block`
 
+short: `-l`
+
 Don't block waiting for a Response from target process.
 Instead, inject the message and immediately return.

src/kit/install.md

@@ -2,7 +2,7 @@
 
 
 These documents describe some ways you can use these tools, but do not attempt to be completely exhaustive.
-You are encouraged to make use of the `--help` flag, which can be used for the top-level `kit`:
+You are encouraged to make use of the `--help` flag, which can be used for the top-level `kit` command:
 
 ```
 $ kit --help
@@ -14,7 +14,7 @@ Commands:
   boot-fake-node       Boot a fake node for development [aliases: f]
   build                Build a Kinode package [aliases: b]
   build-start-package  Build and start a Kinode package [aliases: bs]
-  dev-ui               Start the web UI development server with hot reloading (same as `cd ui && npm i && npm run dev` [aliases: d]
+  dev-ui               Start the web UI development server with hot reloading (same as `cd ui && npm i && npm run dev`) [aliases: d]
   inject-message       Inject a message to a running Kinode [aliases: i]
   new                  Create a Kinode template package [aliases: n]
   remove-package       Remove a running package from a node [aliases: r]
@@ -56,12 +56,19 @@ You can find the source for `kit` at [https://github.com/kinode-dao/kit](https:/
 
 ## Logging
 
-Logs are printed to the screen and stored, by default, at `/tmp/kinode-kit-cache/logs/log.log`.
+Logs are printed to the terminal and stored, by default, at `/tmp/kinode-kit-cache/logs/log.log`.
 The default logging level is `info`.
+Other logging levels are: `debug`, `warning` and `error`.
 
 These defaults can be changed by setting environment variables:
 
 Environment Variable | Description
 -------------------- | -----------
 `KIT_LOG_PATH`       | Set log path (default `/tmp/kinode-kit-cache/logs/log.log`).
 `RUST_LOG`           | Set log level (default `info`).
+
+For example, in Bash:
+
+```bash
+export RUST_LOG=info
+```