Merge pull request #5 from permaweb/twilson63/feat-add-aos-getting-4

feat: add aos tutorial and soem reference info #4

languages/strings/en.json

@@ -2,27 +2,18 @@
   "label": "English",
   "display": "English",
   "lang": "en",
-
   "title": "Cooking With ao",
   "description": "The decentralized computer with infinite threads.",
-
   "edit": "Edit",
   "language": "Language",
   "docs": "Docs",
-
   "getting-started": "Getting Started",
   "getting-started-aos": "aos",
-  "getting-started-ao-dev-cli": "ao Developer CLI",
-
   "concepts": "Concepts",
-  "concepts-environment": "ao Environment",
-  "concepts-ao-lib": "ao Lib",
-  "concepts-architecture": "ao Architecture",
-  "concepts-specs": "ao Specifications",
-
+  "concepts-architecture": "Architecture",
+  "concepts-specs": "Specifications",
   "guides": "Guides",
   "guides-how-do-i": "How Do I?",
-
   "references": "References",
   "references-lua": "Lua",
   "references-wasm": "Web Assembly"

src/concepts/specs.md

@@ -0,0 +1,9 @@
+# ao Specs
+
+### What is `ao`?
+
+The `ao` computer is the [actor oriented](https://en.wikipedia.org/wiki/Actor_model) machine that emerges from the network of nodes that adhere to its core data protocol, running on the [Arweave](https://arweave.org) network. This document gives a brief introduction to the protocol and its functionality, as well as its technical details, such that builders can create new implementations and services that integrate with it.
+
+The `ao` computer is a single, unified computing environment (a [Single System Image](https://en.wikipedia.org/wiki/Single_system_image)), hosted on a heterogenous set of nodes in a distributed network. `ao` is designed to offer an environment in which an arbitrary number of paralell processes can be resident, coordinating through an open message passing layer. This message passing standard connects the machine's indepedently operating processes together into a 'web' -- in the same way that websites operate on independent servers but are conjoined into a cohesive, unified experience via hyperlinks.
+
+[Learn More](https://ao.g8way.io/specs)

src/getting-started/aos.md

@@ -0,0 +1,144 @@
+# aOS
+
+> NOTE: This project experimental, not recommended for production use.
+
+## Requirements
+
+- [NodeJS](https://nodejs.org) version 20+
+
+## Getting Started
+
+```sh
+npm i -g https://sh_ao.g8way.io && aos
+```
+
+> NOTE: after the first time you run `aos` it installs it to your local machine, so the next time you want to run `aos`, just type `aos` + [enter]
+
+## About
+
+aos is a command-line app that connects to your `aOS` Process on the ao Permaweb Computer Grid. The ao Computer Grid, is like the internet, but for compute. Each Process on the Grid can receive messages and send messages. This cli will allow you to pass LUA expressions to your Process, and those expressions get evaluated and return output to your system.
+
+## Examples
+
+When you boot up the aOS, you can use https://lua.org to run expressions on your `aOS` Process.
+
+First try "Hello aOS" - the return keyword sets the output variable that is passed to the output on the screen.
+
+```lua
+"Hello aOS"
+```
+
+You should get `Hello aOS`
+
+> What is happening here? Your input, is getting wrapped in an signed `ao` message and submitted to a messenger unit, which then forwards it to a Scheduler Unit, then the app, calls a compute unit to evaluate the `ao` Message with your Process. This generates output to be returned for display.
+
+Lets try another expression:
+
+```lua
+1 + 41
+```
+
+You should get `42` the answer to the universe 😛
+
+So, thats cool, you can send expressions to the `ao` Permaweb Computer to your Process, and you get returned a response.
+
+You `aOS` process also has memory, so you can set `variables`
+
+```lua
+a = "Hello aOS"
+```
+
+Then type `return a` and you should get `Hello aOS`, neat
+
+You can also create functions:
+
+```lua
+sayHi = function (name) return "Hello " .. name end
+return sayHi("Sam")
+```
+
+You should get `Hello Sam`
+
+Woohoo! 🚀
+
+We can also pass messages to other `aOS` Processes!
+
+```lua
+send({ Target = "ohc9mIsNs3CFmMu7luiazRDLCFpiFJCfGVomJNMNHdU", Tags = { body = "ping" } })
+```
+
+Check the number of items in your `inbox`:
+
+```
+#inbox
+```
+
+Check the body Tag of the last message in your inbox:
+
+```
+inbox[#inbox].Data
+```
+
+> Should be `pong`
+
+Or you can check your messages ( by a `list()`)
+
+```lua
+list()
+```
+
+```
+1:
+ Target: ohc9mIsNs3CFmMu7luiazRDLCFpiFJCfGVomJNMNHdU
+ ...
+ Tags:
+  From-Process: ohc9mIsNs3CFmMu7luiazRDLCFpiFJCfGVomJNMNHdU
+  Type: Message
+  body: pong
+  Variant: ao.TN.1
+  Data-Protocol: ao
+```
+
+### handlers
+
+With `aOS` you can add handlers to handle incoming messages, in this example, we will create a handler for "ping" - "pong".
+
+In the `aOS`, type `.editor`
+
+```lua
+handlers.add(
+  "pingpong",
+  handlers.utils.hasMatchingData("ping"),
+  handlers.utils.reply("pong")
+)
+```
+
+Then type `.done`
+
+> This will submit a handler to listen for messages that have a `body` tag with a value of `ping` then send back a message `pong`.
+
+Once added you can ping yourself!
+
+```lua
+send({Target = ao.id, Data = "ping" })
+```
+
+And check your inbox, you should have gotten a `pong` message.
+
+this utility function finds the `body` Tag of the last message in the inbox and returns the `value`
+
+```lua
+inbox[#inbox].Data
+```
+
+You should see `pong`
+
+:tada:
+
+For more information about `handlers` check out the handlers [docs](process/handlers.md)
+
+## Summary
+
+Hopefully, you are able to see the power of aOS in this demo, access to compute from anywhere in the world.
+
+Welcome to the `ao` Permaweb Computer Grid! We are just getting started! 🐰

src/references/lua.md

@@ -0,0 +1,44 @@
+# Meet Lua
+
+### Understanding Lua
+
+- **Background**: Lua is a lightweight, high-level, multi-paradigm programming language designed primarily for embedded systems and clients. It's known for its efficiency, simplicity, and flexibility.
+- **Key Features**: Lua offers powerful data description constructs, dynamic typing, efficient memory management, and good support for object-oriented programming.
+
+### Setting Up
+
+1. **Installation**: Visit [Lua's official website](http://www.lua.org/download.html) to download and install Lua.
+2. **Environment**: You can use a simple text editor and command line, or an IDE like ZeroBrane Studio or Eclipse with a Lua plugin.
+
+### Basic Syntax and Concepts (in aOS)
+
+- **Hello World**:
+  ```lua
+  "Hello, World!"
+  ```
+- **Variables and Types**: Lua is dynamically typed. Basic types include `nil`, `boolean`, `number`, `string`, `function`, `userdata`, `thread`, and `table`.
+- **Control Structures**: Includes `if`, `while`, `repeat...until`, and `for`.
+- **Functions**: First-class citizens in Lua, supporting closures and higher-order functions.
+- **Tables**: The only data structuring mechanism in Lua, which can be used to represent arrays, sets, records, etc.
+
+### Hands-On Practice
+
+- **Experiment with Lua's Interactive Mode**: Run `aos` in your terminal and start experimenting with Lua commands.
+- **Write Simple Scripts**: Create `.lua` files and run them using the Lua interpreter. Use `.load file.lua` feature to upload lua code on your `aOS` process.
+
+### Resources
+
+- **Official Documentation**: [Lua 5.3 Reference Manual](https://www.lua.org/manual/5.3/)
+- **Online Tutorials**: Websites like [Learn Lua](https://www.learn-lua.org/) are great for interactive learning.
+- **Books**: "Programming in Lua" (first edition available [online](http://www.lua.org/pil/contents.html)) is a comprehensive resource.
+- **Community**: Join forums or communities like [Lua Users](http://lua-users.org/) for support and discussions.
+
+### Best Practices
+
+- **Keep It Simple**: Lua is designed to be simple and flexible. Embrace this philosophy in your code.
+- **Performance**: Learn about Lua's garbage collection and efficient use of tables.
+- **Integration**: Consider how Lua can be embedded into other applications, particularly C/C++ projects.
+
+### Conclusion
+
+Lua is a powerful language, especially in the context of embedded systems and game development. Its simplicity and efficiency make it a great choice for specific use cases. Enjoy your journey into Lua programming!

src/references/wasm.md

@@ -0,0 +1,5 @@
+# Meet Web Assembly
+
+WebAssembly (often abbreviated as Wasm) is a modern binary instruction format providing a portable compilation target for high-level languages like C, C++, and Rust. It enables deployment on the web for client and server applications, offering a high level of performance and efficiency. WebAssembly is designed to maintain the security and sandboxing features of web browsers, making it a suitable choice for web-based applications. It's a key technology for web developers, allowing them to write code in multiple languages and compile it into bytecode that runs in the browser at near-native speed.
+
+The significance of WebAssembly lies in its ability to bridge the gap between web and native applications. It allows complex applications and games, previously limited to desktop environments, to run in the browser with comparable performance. This opens up new possibilities for web development, including the creation of high-performance web apps, games, and even the porting of existing desktop applications to the web. WebAssembly operates alongside JavaScript, complementing it by enabling performance-critical components to be written in languages better suited for such tasks, thereby enhancing the capabilities and performance of web applications.

yarn.lock

@@ -2916,8 +2916,3 @@ zip-stream@^4.1.0:
     archiver-utils "^3.0.4"
     compress-commons "^4.1.2"
     readable-stream "^3.6.0"
-
-zod@^3.22.4:
-  version "3.22.4"
-  resolved "https://registry.npmjs.org/zod/-/zod-3.22.4.tgz"
-  integrity sha512-iC+8Io04lddc+mVqQ9AZ7OQ2MrUKGN+oIQyq1vemgt46jwCwLfhq7/pwnBnNXXXZb8VTVLKwp9EDkx+ryxIWmg==