Prepare CLI for move into mainline

packages/cli/docs/src/SUMMARY.md

@@ -0,0 +1,18 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Installation](./installation.md)
+- [Create a Project](./creating.md)
+- [Configure Project](./configure.md)
+- [Commands](./cmd/README.md)
+  - [Build](./cmd/build.md)
+  - [Serve](./cmd/serve.md)
+  - [Clean](./cmd/clean.md)
+  - [Translate](./cmd/translate.md)
+- [Plugin Development](./plugin/README.md)
+  - [API.Log](./plugin/interface/log.md)
+  - [API.Command](./plugin/interface/command.md)
+  - [API.OS](./plugin/interface/os.md)
+  - [API.Directories](./plugin/interface/dirs.md)
+  - [API.Network](./plugin/interface/network.md)
+  - [API.Path](./plugin/interface/path.md)

packages/cli/docs/src/cmd/README.md

@@ -0,0 +1,26 @@
+# Commands
+
+In this chapter we will introduce all `dioxus-cli` commands.
+
+> You can also use `dioxus --help` to get cli help info.
+
+```
+dioxus 
+Build, bundle, & ship your Dioxus app
+
+USAGE:
+    dioxus [OPTIONS] <SUBCOMMAND>
+
+OPTIONS:
+    -h, --help    Print help information
+    -v            Enable verbose logging
+
+SUBCOMMANDS:
+    build        Build the Dioxus application and all of its assets
+    clean        Clean output artifacts
+    config       Dioxus config file controls
+    create       Init a new project for Dioxus
+    help         Print this message or the help of the given subcommand(s)
+    serve        Build, watch & serve the Rust WASM app and all of its assets
+    translate    Translate some html file into a Dioxus component
+```

packages/cli/docs/src/cmd/build.md

@@ -0,0 +1,47 @@
+# Build
+
+The `dioxus build` command can help you `pack & build` a dioxus project.
+
+```
+dioxus-build 
+Build the Rust WASM app and all of its assets
+
+USAGE:
+    dioxus build [OPTIONS]
+
+OPTIONS:
+        --example <EXAMPLE>      [default: ""]
+        --platform <PLATFORM>    [default: "default_platform"]
+        --release                [default: false]
+```
+
+You can use this command to build a project:
+
+```
+dioxus build --release
+```
+
+## Target platform
+
+Use the `platform` option to choose your target platform:
+
+```
+# for desktop project
+dioxus build --platform desktop
+```
+
+`platform` currently only supports `desktop` & `web`.
+
+```
+# for web project
+dioxus build --platform web
+```
+
+## Build Example
+
+You can use the `example` option to select a example to build:
+
+```
+# build the `test` example
+dioxus build --exmaple test
+```

packages/cli/docs/src/cmd/clean.md

@@ -0,0 +1,18 @@
+# Clean
+
+`dioxus clean` will clear the build artifacts (the out_dir and the cargo cache)
+
+```
+dioxus-clean 
+Clean build artifacts
+
+USAGE:
+    dioxus clean
+```
+
+# Example
+
+```
+dioxus clean
+```
+

packages/cli/docs/src/cmd/serve.md

@@ -0,0 +1,61 @@
+# Serve
+
+The `dioxus serve` can start a dev server with hot-reloading
+
+```
+dioxus-serve 
+Build, watch & serve the Rust WASM app and all of its assets
+
+USAGE:
+    dioxus serve [OPTIONS]
+
+OPTIONS:
+        --example <EXAMPLE>      [default: ""]
+        --platform <PLATFORM>    [default: "default_platform"]
+        --release                [default: false]
+        --hot-reload             [default: false]ß
+```
+
+You can use this command to build project and start a dev server:
+
+```
+dioxus serve
+```
+
+## Serve Example
+
+You can use the `example` option to serve a example:
+
+```
+# serve the `test` example
+dioxus serve --exmaple test
+```
+
+## Open Browser
+
+You can add the `--open` option to open system default browser when server startup:
+
+```
+dioxus serve --open
+```
+
+## RSX Hot Reloading
+
+You can add the `--hot-reload` flag to enable [rsx hot reloading](https://dioxuslabs.com/docs/0.3/guide/en/getting_started/hot_reload.html). This will allow you to reload some rsx changes without a full recompile:
+
+```
+dioxus serve --open
+```
+
+## Cross Origin Policy
+
+You can add the `cross-origin-policy` option to change cross-origin header to:
+
+```
+  Cross-Origin-Opener-Policy: same-origin
+  Cross-Origin-Embedder-Policy: require-corp
+```
+
+```
+dioxus serve --corss-origin-policy
+```

packages/cli/docs/src/cmd/translate.md

@@ -0,0 +1,68 @@
+# Translate
+
+`dioxus translate` can translate some `html` file into a Dioxus compoent
+
+```
+dioxus-translate 
+Translate some source file into a Dioxus component
+
+USAGE:
+    dioxus translate [OPTIONS] [OUTPUT]
+
+ARGS:
+    <OUTPUT>    Output file, defaults to stdout if not present
+
+OPTIONS:
+    -c, --component      Activate debug mode
+    -f, --file <FILE>    Input file
+```
+
+## Translate HTML to stdout
+
+You can use the `file` option to set path to the `html` file to translate:
+
+```
+dioxus transtale --file ./index.html
+```
+
+## Output rsx to a file
+
+You can pass a file to the traslate command to set the path to write the output of the command to:
+
+```
+dioxus translate --file ./index.html component.rsx
+```
+
+## Output rsx to a file
+
+Setting the `component` option will create a compoent from the HTML:
+
+```
+dioxus translate --file ./index.html --component
+```
+
+## Example
+
+This HTML:
+```html
+<div>
+    <h1> Hello World </h1>
+    <a href="https://dioxuslabs.com/">Link</a>
+</div>
+```
+
+Translates into this Dioxus component:
+
+```rust
+fn component(cx: Scope) -> Element {
+    cx.render(rsx! {
+        div {
+            h1 { "Hello World" },
+            a {
+                href: "https://dioxuslabs.com/",
+                "Link"
+            }
+        }
+    })
+}
+```

packages/cli/docs/src/configure.md

@@ -0,0 +1,208 @@
+# Configure Project
+
+
+This chapter will introduce you to how to configure the CLI with your `Dioxus.toml` file
+
+Be aware that if the config file is present in the folder, some fields must be filled out, or the CLI tool will abort. The mandatory [table headers](https://toml.io/en/v1.0.0#table) and keys will have a '✍' sign beside it.
+
+## Structure
+
+The CLI uses a `Dioxus.toml` file in the root of your crate to define some configuration for your `dioxus` project.
+
+### Application ✍
+
+General application confiration:
+
+```
+[application]
+# configuration
+```
+1. ***name*** ✍ - project name & title
+2. ***default_platform*** ✍ - which platform target for this project.
+
+   ```
+   name = "my-project"
+   ```
+2. ***default_platform*** - The platform this project targets
+   ```ß
+   # current supported platforms: web, desktop
+   # default: web
+   default_platform = "web"
+   ```
+   if you change this to `desktop`, the `dioxus build` will default building a desktop app
+3. ***out_dir*** - The directory to place the build artifacts from `dioxus build` or `dioxus service` into. This is also where the `assets` directory will be copied to
+    ```
+    out_dir = "dist"
+    ```
+4. ***asset_dir*** - The directory with your static assets. The CLI will automatically copy these assets into the ***out_dir*** after a build/serve.
+   ```
+   asset_dir = "public"
+   ```
+5. ***sub_package*** - The sub package in the workspace to build by default
+   ```
+   sub_package = "my-crate"
+   ```
+
+### Web.App ✍
+
+Configeration specific to web applications:
+
+```
+[web.app]
+# configuration
+```
+
+1. ***title*** - The title of the web page
+   ```
+   # HTML title tag content
+   title = "dioxus app | ⛺"
+   ```
+2. ***base_path*** - The base path to build the appliation for serving at. This can be useful when serving your application in a subdirectory under a domain. For example when building a site to be served on github pages.
+   ```
+   # The application will be served at domain.com/my_application/, so we need to modify the base_path to the path where the application will be served
+   base_path = "my_application"
+   ```
+
+### Web.Watcher ✍
+
+Configeration related to the development server:
+
+```
+[web.watcher]
+# configuration
+```
+
+1. ***reload_html*** - If this is true, the cli will rebuild the index.html file every time the application is rebuilt
+   ```
+   reload_html = true
+   ```
+2. ***watch_path*** - The files & directories to moniter for changes
+   ```
+   watch_path = ["src", "public"]
+   ```
+3. ***index_on_404*** - If enabled, Dioxus CLI will serve the root page when a route is not found. *This is needed when serving an application that uses the router*
+   ```
+   index_on_404 = true
+   ```
+
+### Web.Resource ✍
+
+Configeration related to static resources your application uses:
+```
+[web.resource]
+# configuration
+```
+
+1. ***style*** - The styles (`.css` files) to include in your application
+   ```
+   style = [
+      # include from public_dir.
+      "./assets/style.css",
+      # or some asset from online cdn.
+      "https://cdn.jsdelivr.net/npm/bootstrap/dist/css/bootstrap.css"
+   ]
+   ```
+2. ***script*** - The additional scripts (`.js` files) to include in your application
+    ```
+    style = [
+        # include from public_dir.
+        "./assets/index.js",
+        # or some asset from online cdn.
+        "https://cdn.jsdelivr.net/npm/bootstrap/dist/js/bootstrap.js"
+    ]
+   ```
+
+### Web.Resource.Dev ✍
+
+Configeration related to static resources your application uses in development:
+```
+[web.resource.dev]
+# configuration
+```
+
+1. ***style*** - The styles (`.css` files) to include in your application
+   ```
+   style = [
+      # include from public_dir.
+      "./assets/style.css",
+      # or some asset from online cdn.
+      "https://cdn.jsdelivr.net/npm/bootstrap/dist/css/bootstrap.css"
+   ]
+   ```
+2. ***script*** - The additional scripts (`.js` files) to include in your application
+    ```
+    style = [
+        # include from public_dir.
+        "./assets/index.js",
+        # or some asset from online cdn.
+        "https://cdn.jsdelivr.net/npm/bootstrap/dist/js/bootstrap.js"
+    ]
+   ```
+
+### Web.Proxy
+
+Configeration related to any proxies your application requires durring development. Proxies will forward requests to a new service
+
+```
+[web.proxy]
+# configuration
+```
+
+1. ***backend*** - The URL to the server to proxy. The CLI will forward any requests under the backend relative route to the backend instead of returning 404
+   ```
+   backend = "http://localhost:8000/api/"
+   ```
+   This will cause any requests made to the dev server with prefix /api/ to be redirected to the backend server at http://localhost:8000. The path and query parameters will be passed on as-is (path rewriting is not currently supported).
+
+## Config example
+
+```toml
+[application]
+
+# App (Project) Name
+name = "{{project-name}}"
+
+# The Dioxus platform to default to
+default_platform = "web"
+
+# `build` & `serve` output path
+out_dir = "dist"
+
+# the static resource path
+asset_dir = "public"
+
+[web.app]
+
+# HTML title tag content
+title = "dioxus | ⛺"
+
+[web.watcher]
+
+# when watcher is triggered, regenerate the `index.html`
+reload_html = true
+
+# which files or dirs will be monitored
+watch_path = ["src", "public"]
+
+# include `assets` in web platform
+[web.resource]
+
+# CSS style file
+style = []
+
+# Javascript code file
+script = []
+
+[web.resource.dev]
+
+# serve: [dev-server] only
+
+# CSS style file
+style = []
+
+# Javascript code file
+script = []
+
+[[web.proxy]]
+backend = "http://localhost:8000/api/"
+```

packages/cli/docs/src/creating.md

@@ -0,0 +1,39 @@
+# Create a Project
+
+Once you have the Dioxus CLI tool installed, you can use it to create dioxus project.
+
+## Initializing a default project
+
+First, run the `dioxus create` command to create a new project ready to be used with Dioxus and the Dioxus CLI:
+
+```
+dioxus create hello-dioxus
+```
+
+> It will clone a default template from github template: [DioxusLabs/dioxus-template](https://github.com/DioxusLabs/dioxus-template)
+> This default template is use for `web` platform application.
+>
+> You can choose to create your project from a different template by passing the `template` argument:
+> ```
+> dioxus init hello-dioxus --template=gh:dioxuslabs/dioxus-template
+> ```
+
+Next, move the current directory into your new project:
+
+```
+cd hello-dioxus
+```
+
+> Make sure `wasm32 target` is installed before running the Web project.
+> You can install the wasm target for rust using rustup:
+> ```
+> rustup target add wasm32-unknown-unknown
+> ```
+
+Finally, create serve your project with the Dioxus CLI:
+
+```
+dioxus serve
+```
+
+By default, the CLI serve your site at: [`http://127.0.0.1:8080/`](http://127.0.0.1:8080/)

packages/cli/docs/src/installation.md

@@ -0,0 +1,22 @@
+# Installation
+
+Choose any one of the methods below to install the Dioxus CLI:
+
+## Install from latest git version
+
+To get the most up to date bug fixes and features of the Dioxus CLI, you can install the development version from git.
+
+```
+cargo install --git https://github.com/Dioxuslabs/cli
+```
+
+This will automatically download `Dioxus-CLI` source from github master branch,
+and install it in Cargo's global binary directory (`~/.cargo/bin/` by default).
+
+## Install from `crates.io` version
+
+The published version of the Dioxus CLI is updated less often, but should be more stable than the git version of the Dioxus CLI.
+
+```
+cargo install dioxus-cli
+```

packages/cli/docs/src/introduction.md

@@ -0,0 +1,21 @@
+# Introduction
+
+📦✨ **Dioxus-Cli** is a tool to help get dioxus projects off the ground.
+
+![dioxus-logo](https://dioxuslabs.com/guide/images/dioxuslogo_full.png)
+
+It includes `dev server`, `hot reload` and some `quick command` to help you use dioxus.
+
+## Features
+
+- [x] `html` to `rsx` conversion tool
+- [x] hot reload for `web` platform
+- [x] create dioxus project from `git` repo
+- [x] build & pack dioxus project
+- [ ] autoformat dioxus `rsx` code
+
+## Contributors
+
+Contributors to this guide:
+
+- [mrxiaozhuox](https://github.com/mrxiaozhuox)

packages/cli/docs/src/plugin/README.md

@@ -0,0 +1,79 @@
+# CLI Plugin Development
+
+> For Cli 0.2.0 we will add `plugin-develop` support.
+
+Before the 0.2.0 we use `dioxus tool` to use & install some plugin, but we think that is not good for extend cli program, some people want tailwind support, some people want sass support, we can't add all this thing in to the cli source code and we don't have time to maintain a lot of tools that user request, so maybe user make plugin by themself is a good choice.
+
+### Why Lua ?
+
+We choose `Lua: 5.4` to be the plugin develop language, because cli plugin is not complex, just like a workflow, and user & developer can write some easy code for their plugin. We have **vendored** lua in cli program, and user don't need install lua runtime in their computer, and the lua parser & runtime doesn't take up much disk memory.
+
+### Event Management
+
+The plugin library have pre-define some important event you can control:
+
+- `build.on_start`
+- `build.on_finished`
+- `serve.on_start`
+- `serve.on_rebuild`
+- `serve.on_shutdown`
+
+### Plugin Template
+
+```lua
+package.path = library_dir .. "/?.lua"
+
+local plugin = require("plugin")
+local manager = require("manager")
+
+-- deconstruct api functions
+local log = plugin.log
+
+-- plugin information
+manager.name = "Hello Dixous Plugin"
+manager.repository = "https://github.com/mrxiaozhuox/hello-dioxus-plugin"
+manager.author = "YuKun Liu <mrxzx.info@gmail.com>"
+manager.version = "0.0.1"
+
+-- init manager info to plugin api
+plugin.init(manager)
+
+manager.on_init = function ()
+    -- when the first time plugin been load, this function will be execute.
+    -- system will create a `dcp.json` file to verify init state.
+    log.info("[plugin] Start to init plugin: " .. manager.name)
+end
+
+---@param info BuildInfo
+manager.build.on_start = function (info)
+    -- before the build work start, system will execute this function.
+    log.info("[plugin] Build starting: " .. info.name)
+end
+
+---@param info BuildInfo
+manager.build.on_finish = function (info)
+    -- when the build work is done, system will execute this function.
+    log.info("[plugin] Build finished: " .. info.name)
+end
+
+---@param info ServeStartInfo
+manager.serve.on_start = function (info)
+    -- this function will after clean & print to run, so you can print some thing.
+    log.info("[plugin] Serve start: " .. info.name)
+end
+
+---@param info ServeRebuildInfo
+manager.serve.on_rebuild = function (info)
+    -- this function will after clean & print to run, so you can print some thing.
+    local files = plugin.tool.dump(info.changed_files)
+    log.info("[plugin] Serve rebuild: '" .. files .. "'")
+end
+
+manager.serve.on_shutdown = function ()
+    log.info("[plugin] Serve shutdown")
+end
+
+manager.serve.interval = 1000
+
+return manager
+```

packages/cli/docs/src/plugin/interface/command.md

@@ -0,0 +1,21 @@
+# Command Functions
+
+> you can use command functions to execute some code & script
+
+Type Define:
+```
+Stdio: "Inherit" | "Piped" | "Null"
+```
+
+### `exec(commands: [string], stdout: Stdio, stderr: Stdio)`
+
+you can use this function to run some command on the current system.
+
+```lua
+local cmd = plugin.command
+
+manager.test = function ()
+    cmd.exec({"git", "clone", "https://github.com/DioxusLabs/cli-plugin-library"})
+end
+```
+> Warning: This function don't have exception catch.

packages/cli/docs/src/plugin/interface/dirs.md

@@ -0,0 +1,35 @@
+# Dirs Functions
+
+> you can use Dirs functions to get some directory path
+
+
+### plugin_dir() -> string
+
+You can get current plugin **root** directory path
+
+```lua
+local path = plugin.dirs.plugin_dir()
+-- example: ~/Development/DioxusCli/plugin/test-plugin/
+```
+
+### bin_dir() -> string
+
+You can get plugin **bin** direcotry path
+
+Sometime you need install some binary file like `tailwind-cli` & `sass-cli` to help your plugin work, then you should put binary file in this directory.
+
+```lua
+local path = plugin.dirs.bin_dir()
+-- example: ~/Development/DioxusCli/plugin/test-plugin/bin/
+```
+
+### temp_dir() -> string
+
+You can get plugin **temp** direcotry path
+
+Just put some temporary file in this directory.
+
+```lua
+local path = plugin.dirs.bin_dir()
+-- example: ~/Development/DioxusCli/plugin/test-plugin/temp/
+```

packages/cli/docs/src/plugin/interface/log.md

@@ -0,0 +1,48 @@
+# Log Functions
+
+> You can use log function to print some useful log info
+
+### Trace(info: string)
+
+Print trace log info
+
+```lua
+local log = plugin.log
+log.trace("trace information")
+```
+
+### Debug(info: string)
+
+Print debug log info
+
+```lua
+local log = plugin.log
+log.debug("debug information")
+```
+
+### Info(info: string)
+
+Print info log info
+
+```lua
+local log = plugin.log
+log.info("info information")
+```
+
+### Warn(info: string)
+
+Print warning log info
+
+```lua
+local log = plugin.log
+log.warn("warn information")
+```
+
+### Error(info: string)
+
+Print error log info
+
+```lua
+local log = plugin.log
+log.error("error information")
+```

packages/cli/docs/src/plugin/interface/network.md

@@ -0,0 +1,34 @@
+# Network Functions
+
+> you can use Network functions to download & read some data from internet
+
+### download_file(url: string, path: string) -> boolean
+
+This function can help you download some file from url, and it will return a *boolean* value to check the download status. (true: success | false: fail)
+
+You need pass a target url and a local path (where you want to save this file)
+
+```lua
+-- this file will download to plugin temp directory
+local status = plugin.network.download_file(
+    "http://xxx.com/xxx.zip",
+    plugin.dirs.temp_dir()
+)
+if status != true then
+    log.error("Download Failed")
+end
+```
+
+### clone_repo(url: string, path: string) -> boolean
+
+This function can help you use `git clone` command (this system must have been installed git)
+
+```lua
+local status = plugin.network.clone_repo(
+    "http://github.com/mrxiaozhuox/dioxus-starter",
+    plugin.dirs.bin_dir()
+)
+if status != true then
+    log.error("Clone Failed")
+end
+```

packages/cli/docs/src/plugin/interface/os.md

@@ -0,0 +1,11 @@
+# OS Functions
+
+> you can use OS functions to get some system information
+
+### current_platform() -> string ("windows" | "macos" | "linux")
+
+This function can help you get system & platform type:
+
+```lua
+local platform = plugin.os.current_platform()
+```

packages/cli/docs/src/plugin/interface/path.md

@@ -0,0 +1,35 @@
+# Path Functions
+
+> you can use path functions to operate valid path string
+
+### join(path: string, extra: string) -> string
+
+This function can help you extend a path, you can extend any path, dirname or filename.
+
+```lua
+local current_path = "~/hello/dioxus"
+local new_path = plugin.path.join(current_path, "world")
+-- new_path = "~/hello/dioxus/world"
+```
+
+### parent(path: string) -> string
+
+This function will return `path` parent-path string, back to the parent.
+
+```lua
+local current_path = "~/hello/dioxus"
+local new_path = plugin.path.parent(current_path)
+-- new_path = "~/hello/"
+```
+
+### exists(path: string) -> boolean
+
+This function can check some path (dir & file) is exists.
+
+### is_file(path: string) -> boolean
+
+This function can check some path is a exist file.
+
+### is_dir(path: string) -> boolean
+
+This function can check some path is a exist dir.