streamline dev flow

3 files changed, 112 insertions, 0 deletions

diff --git a/documentation/DEPLOY.md b/documentation/DEPLOY.md
new file mode 100644
index 0000000..344165c
--- /dev/null
+++ b/documentation/DEPLOY.md
@@ -0,0 +1,14 @@
+# Live Deployment Installation
+
+1. [Clone](https://help.github.com/articles/cloning-a-repository/) the repository: `git clone https://github.com/hack-chat/main.git`
+1. Change the directory: `cd main/server`
+1. Install server dependencies: `npm install`
+1. Configure the server: `npm run config` (you may also migrate a `config` directory into `./main/server` if you previously configured the server elsewhere)
+1. Migrate the contents of `./main/client` into any suitable directory of your webserver
+1. (OPTIONAL) Cleanup; you may delete `main/clientSource` and `main/documentation`
+
+    You can now run start the server software with a process manager like [PM2](https://github.com/Unitech/pm2) (e.g., `pm2 start server/main.js --name HackChat`). If you plan on using SSL to serve the client; you will need to use a reverse proxy, as TLS is not natively supported by the hack.chat server software (this may change in future releases).
+
+# Advanced
+
+(TODO)
diff --git a/documentation/DOCUMENTATION.md b/documentation/DOCUMENTATION.md
new file mode 100644
index 0000000..b070dfa
--- /dev/null
+++ b/documentation/DOCUMENTATION.md
@@ -0,0 +1,46 @@
+You can programmatically access hack.chat using the following commands via a websocket. A list of wrappers written for accessing hack.chat can be found [here](https://github.com/hack-chat/3rd-party-software-list#libraries).
+
+The commands are to be sent through a websocket to the URL `wss://hack.chat/chat-ws` (everything sent and received are JSON). If you are sending messages locally or to another domain, replace 'hack.chat' with the respective domain. If you're running your own instance of hack.chat, you can retain backwards-compatibility in order to ensure that software created for the main server will work on yours too.
+
+All commands sent must be JSON objects with the command specified in the `"cmd"` key. For example:
+```json
+{
+    "cmd": "join",
+    "channel": "programming",
+    "nick": "john#doe"
+}
+```
+
+hack.chat has three permission levels. When you access a command, hack.chat automatically knows your permission level from your trip code. The lowest permission level is `user`. `mod` is above `user`, so it can access `user` commands in addition to `mod` commands. `admin` is similarly above `mod`.
+
+# `user`
+
+|Command|Parameters|Explanation|
+|-------|----------|-----------|
+|`changenick`|`nick`|Changes the current connection's nickname.|
+|`chat`|`text`|This broadcasts `text` to the channel the user is connected to.|
+|`disconnect`||An event handler or forced disconnect.|
+|`invite`|`nick`|Generates a pseudo-unique channel name and passes it to both the calling user and `nick`.|
+|`join`|`channel`, `nick`|Places the calling socket into the target channel with the target nick and broadcasts the event to the channel.|
+|`morestats`||Sends back the current server's stats to the calling client.|
+|`move`|`channel`|This will change the current channel to `channel`.|
+|`stats`||Sends back legacy server stats to the calling client. Use `morestats` when possible.|
+|`help`|`category` or `command`|Gives documentation programmatically. If `category` (the permission level, such as `mod`) is sent, a list of commands available to that permission level will be sent back (as a `string` and not an `array`). This list only includes what is unique to that category and not every command a user with that permission level could perform. If `command` (e.g., `chat`) is sent, a description of the command will be sent back.|
+
+# `mod`
+
+|Command|Parameters|Explanation|
+|-------|----------|-----------|
+|`ban`|`nick`|Disconnects the target nickname in the same channel as the calling socket and adds it to the rate limiter.|
+|`kick`|`nick`|Silently forces target client(s) into another channel. `nick` may be `string` or `array` of `string`s.|
+|`unban`|`ip` or `hash`|Removes the target ip from the rate limiter.|
+
+# `admin`
+
+|Command|Parameters|Explanation|
+|-------|----------|-----------|
+|`addmod`|`nick`|Adds the target trip to the config as a mod and upgrades the socket type.|
+|`listusers`||Outputs all current channels and sockets in those channels.|
+|`reload`||(Re)loads any new commands into memory and outputs errors, if any.|
+|`saveconfig`||Saves the current config.|
+|`shout`|`text`|Displays the passed text to each client connected.|
diff --git a/documentation/templateCommand.js b/documentation/templateCommand.js
new file mode 100644
index 0000000..1a4f3d2
--- /dev/null
+++ b/documentation/templateCommand.js
@@ -0,0 +1,52 @@
+/*
+  Description: This is a template module that should not be user in a production
+               enviroment
+*/
+
+// you can require() modules here
+
+// this function will only be only in the scope of the module
+const createReply = (echoInput) => {
+  if (echoInput.length > 100)
+    echoInput = 'HOW ABOUT NO?';
+
+  return `You want me to echo: ${echoInput}?`
+};
+
+/*
+  `exports.run()` is required and will always be passed (core, server, socket, data)
+
+  be sure it's async too
+  this is the main function that will run when called
+*/
+exports.run = async (core, server, socket, data) => {
+
+  server.reply({
+    cmd: 'info',
+    text: `SHOWCASE MODULE: ${core.showcase} - ${createReply(data.echo)}`
+  }, socket);
+
+};
+
+/*
+  `exports.init()` is optional, and will only be run when the module is loaded into memory
+  it will always be passed a reference to the global core class
+  note: this will fire again if a reload is issued, keep that in mind
+*/
+exports.init = (core) => {
+  if (typeof core.showcase === 'undefined') {
+    core.showcase = 'init is a handy place to put global data by assigning it to `core`';
+  }
+}
+
+// optional, if `data.echo` is missing `exports.run()` will never be called & the user will be alerted
+// remember; this will only verify that the data is not undefined, not the type of data
+exports.requiredData = ['echo'];
+
+// optional parameters are marked, all others are required
+exports.info = {
+  name: 'showcase', // actual command name
+  aliases: ['templateModule'], // optional, an array of other names this module can be executed by
+  usage: 'showcase {echo}', // used for help output, can be ommited if no parameters are required
+  description: 'Simple command module template & info' // used for help output
+};