Wiki-Bots are made to aid the user in editing their wiki's contents. Some of them have complex GUIs which allow you to automate some, but not all tasks. On the other hand, raw editing APIs naturally make your code prone to bugs which could ultimately mess up your articles.
Shtorm tries to solve the shortfalls of both methods, by providing a GUI, and the respective API, for monitoring your running bot scripts.
The JavaScript API allows scripts to communicate with the client in the following ways:
- Expose startup-variables to the user allowing them to make multiple presets out of the same script (e.g.: Two presets telling the script to go through two different categories)
- Generate diffing and editing prompts (e.g.: Checking changes the script made to an article)
- Show the progress of pending tasks through the in-built progress bar
The JavaScript API allows you to generate diffing or editing prompts, as well as a progress-bar for visually indicating the status of pending tasks. Furthermore, scripts can expose multiple public variables, thus allowing users to run the same script with different start values.
Since Shtorm is able to run multiple script instances simultaneously, a feature was added to grant multiple users the ability to run select tasks on their own. Thanks to the user-friendly interface one does not need programming knowledge to use the scripts.
Note that Shtorm cannot guarantee fully sanitized user-input. It is the responsibility of the script authors to implement this in their code if they need to.
For the installation instructions, head over to Installation
There are two essential directories for the server: A folder containing each executable script and a folder for the server database. Thus, the following arguments can be added when starting the server:
$ shtorm-server [scriptsDirPath] [databaseDirPath]The first user will always be called "Admin" with the password "password". Change this data on first login by heading over to "Users" and selecting "Admin".
- You can add and edit users in the section "Users"
- Add and edit bot configurations in the section "Bot Configs"
- Add and edit projects on the homepage
- Open or stop running tasks by pressing the clipboard icon in the upper right corner
The server scans the root scripts folder (the folder that is specified on server startup as an argument or in the config.json before compilation) for available .js files. It automatically interprets these files as executable scripts.
For an example script take a look here
When a script is used, it is run in a VM2 instance in a seperate node process. Shtorm allows this sandbox to read from an optional node_modules directory found in the root scripts folder. This allows you to use any NPM module in your scripts.
Currently, Shtorm only accepts JavaScript files. It is possible to add TypeScript support by compiling the files manually before using them in Shtorm.
You have to export an object with two entries: default and scriptOptions.
module.exports = {
default: () => new Promise((resolve, reject) => {}),
scriptOptions: [
{ type: string, name: string, value: string | number },
]
}default is the first function that is executed when starting the script. It is strongly advised to return a Promise to keep the asynchronous workflow of the script. Resolving this promise will terminate the running process.
scriptOptions is an array containing public variables that can be defined in the client before starting the script. The script can read these options from a global variable.
Each script file has the following global variables when run:
bot: Nodemw preconfigured bot instance. Append "Async" to each asynchronous function if you want to recieve a promisified version of the function.
options: Object with public variables you defined in scriptOptions. The entries are named after the name value in a scriptOptions object.
updateClient: A function that updates specific GUI elements in the client. It returns a resolve-only promise if you request a dialog.
type updateClient = ({
/**
* Value of progress indicator read as percentage.
* 0 = indeterminate
*/
progress?: number,
/**
* Title describing what's happening currently
*/
progressMessage?: string,
/**
* An object which opens a dialog requiring user-input when defined
*/
dialog?: {
/**
* Code: Single code editor the user may edit
* Diff: Diff view with right-side editor marked as user-editable
* Prompt: Dialog with a custom message and OK/Cancel buttons
*/
type: "code" | "diff" | "prompt",
/**
* Title of the dialog or prompt message
*/
msg: string,
/**
* Predefined input
*/
code: string,
/**
* Language parameter for the code editor's syntax highlighter
*/
language: string = "xml",
/**
* Used in conjunction with `type: "diff"`.
* Predefined input in the right-side editor
*/
diffCode?: string,
}
}) => Promise<string | undefined | null>;Shtorm is using Lerna to manage its two main components - the server and the client.
You can find them in their respective folders inside of packages.
- Node.js (v10.15.3)
- yarn (optional; preferred)
$ git clone https://github.com/Pogodaanton/shtorm.git && cd shtorm$ yarn
$ cd packages/shtorm-client && yarn
$ cd ../shtorm-server && yarn
$ cd ../../You need to create a config file in the src directory of both shtorm-server and shtorm-client. Make a copy of the included config.example.json, rename it to config.json and edit its contents.
$ yarn buildYou will be able to find the newly generated items in packages/shtorm-[server, client]/build.
Shtorm-server generates OS specific executables which start a web-server on the port specified in config.json.
Make sure to tunnel the port to an existing NGINX or Apache web-server via reverse proxying, as the server itself does not support SSL encryption. Do not under any circumstances connect to the port directly in production
The contents of this build directory can be directly uploaded to a static server of any kind.
- Note that the code has not been tested on Windows yet
- Make sure to use the right node.js version (v10.15.3). NVM might save your day...
Error: Node Sass does not yet support your current environment:often means that an error occured during the installation of node-sass or that the system it has run on has been changed since its last use. Try removingnode_modulesin the directoryshtorm-clientand reinstall the dependencies.
Feel free to create an issue if these advices couldn't solve your installation troubles.
Looking for the script development guide?
Follow the general installation instructions above and start the local development system afterwards instead of generating a production build.
$ yarn startImprovements to the codebase are gladly welcomed. Please make sure to always link an issue to your pull request.
GPL-3.0 - See LICENSE for more info.