1 files changed, 118 insertions, 0 deletions
diff --git a/pkgs/yossh/doc/lua_doc.md b/pkgs/yossh/doc/lua_doc.md
new file mode 100644
index 0000000..b029f56
--- /dev/null
+++ b/pkgs/yossh/doc/lua_doc.md
@@ -0,0 +1,118 @@
+# Lua Documentation
+Lua API documentation for Yoshi
+
+## `yoshi.hosts`
+- Description: List of defined ssh hosts. Each entry must be a function that returns an `sshCommand` when called.
+- Type: table of `function(): sshCommand`
+- Example:
+```lua
+yoshi.hosts["webserver"] = function()
+  -- this is just a random example to show why you might want yoshi.hosts[host] to be a function
+  if os.getenv("IM_FEELING") == "sad" then
+    return yoshi.ssh{HostName = "sad.webserver.local"}
+  else
+    return yoshi.ssh{HostName = "happy.webserver.local"}
+  end
+end
+```
+
+## `yoshi.ssh`
+- Description: Constructs an `sshCommand`
+- Type: `function(table): sshCommand`
+- Example:
+```lua
+yoshi.ssh{
+  HostName = "webserver.local",
+  Port = 2227,
+  ProxyJump = "bastion"
+}
+```
+
+## `yoshi.sshCommand.User`
+- Description: Specifies the target user in the ssh connection. Analogous to the `User` key in `ssh_config`
+- Type: string or nil
+- Example: `yoshi`, `collin123`
+
+## `yoshi.sshCommand.HostName`
+- Description: Specifies the target host in the ssh connection. The only required element to `yoshi.sshCommand`. Analogous to the `HostName` key in `ssh_config`
+- Type: string
+- Example: `192.168.0.27`, `github.com`, `140.82.114.3`
+
+## `yoshi.sshCommand.Port`
+- Description: Specifies the target port in the ssh connection. Defaults to `22` if unspecified. Analagous to the `Port` key in `ssh_config`
+- Type: integer, `0 <= i <= 65535`
+- Examples: `22`, `2222`, `2225`
+
+## `yoshi.sshCommand.RemoteCommand`
+- Description: Specifies a command to run on the target host instead of the default shell. Analagous to the `RemoteCommand` key in `ssh_config`
+- Type: string
+- Examples: `whoami`, `nixos-rebuild switch --flake /etc/nixos`, `tmux new-session -A`
+
+## `yoshi.sshCommand.SessionType`
+- Description: Specifies the type of ssh session. "none" means that no shell access is provded. Analogous to the `SessionType` key in `ssh_config`
+- Type: "subsystem", "none", or "default"
+- Examples: `"none"`
+
+## `yoshi.sshCommand.LocalForward`
+- Description: Specifies a port on the target host to forward to the local host in the format `{local_port, target_port}`. If no local port is specified, will assume host port and local port are the same. Analagous to the `LocalForward` key in `ssh_config` or the `-L` flag on the command line
+- Type: `table[2] of integer` or integer, `0 <= i <= 65535`
+- Examples: `8010`, `{8010, 80}`
+
+## `yoshi.sshCommand.DynamicForward`
+- Description: Specifies a port on the local host to serve as a SOCKS5 proxy, forwarding all traffic through the target host. Analagous to the `DynamicForward` key in `ssh_config` or the `-D` option on the command line
+- Type: integer, `0 <= i <= 65535`
+- Examples: `9090`
+
+## `yoshi.sshCommand.ProxyJump`
+- Description: Specifies a host to act as a gateway to the target host if not directly accessable by the local host. It will inherit `User`, `Port`, and `HostName` options from `yoshi.hosts[host]` if it exists. Analagous to the `ProxyJump` key in `ssh_config` or the `-J` flag on the command line
+- Type: string in the form `user@host:port`
+- Example: `box`, `yoshi@box`, `box:27`, `yoshi@box:27`
+- Full Example:
+```lua
+yoshi.hosts["bastion"] = sshCommand.ssh{
+  HostName = "bastion.mywebsite.com",
+  Port = 23,
+}
+
+yoshi.hosts["server"] = sshCommand.ssh{
+  HostName = "192.168.0.2",
+  ProxyJump = "myuser@bastion"
+}
+
+assert_eq(
+  yoshi.getHost("server"):toCommand(),
+  "ssh -J myuser@bastion.mywebsite.com:23 server"
+)
+```
+
+## `yoshi.sshCommand:toCommand`
+- Description: Formats `self` as a valid `ssh` command to be run in the terminal.
+- Type: `sshCommand:function(): string`
+- Example:
+```lua
+os.execute(yoshi.getHost("io"):toCommand())
+```
+
+## `yoshi.getHost`
+- Description: Looks up and evaluates `yoshi.hosts[hostname]`, returning the resulting `sshCommand`. Raises an error if the host is not found or the host function returns nil.
+- Type: `function(string): sshCommand`
+- Example:
+```lua
+yoshi.hosts["webserver"] = function()
+  return yoshi.ssh{
+    HostName = "webserver.local",
+    Port = 22,
+    ProxyJump = "bastion"
+  }
+end
+
+os.execute(yoshi.getHost("webserver"):toCommand())
+```
+
+## `yoshi.run`
+- Description: Executes the ssh command associated with the given target host as provided by `arg`, a list of commandline arguments. If no arguments are provided, prints a help page. The first argument is a path of the form `[jumphost/.../]host`, where any leading path segments are used as explicit proxy jump hops. Subsequent arguments may include ssh flags such as `-D`, `-L`, `-N`, or `-- command`.
+- Type: `function(table of string, table of any)`
+- Example:
+```lua
+yoshi.run(arg, {dry_run = true}) -- arg is the global name for the lua program's commandline arguments
+```