{"id":15134760,"url":"https://github.com/pogodaanton/shtorm","last_synced_at":"2025-09-29T03:30:51.243Z","repository":{"id":39525574,"uuid":"179813675","full_name":"Pogodaanton/shtorm","owner":"Pogodaanton","description":"The semi-automatic scriptable wiki-bot runner","archived":true,"fork":false,"pushed_at":"2022-09-28T13:11:07.000Z","size":6953,"stargazers_count":0,"open_issues_count":48,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-11T23:35:08.834Z","etag":null,"topics":["fandom-wiki","mediawiki","mediawiki-api","mediawiki-bot","nodemw","wiki","wikia-api","wikipedia"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Pogodaanton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-06T09:30:22.000Z","updated_at":"2023-01-27T20:35:16.000Z","dependencies_parsed_at":"2022-09-16T01:25:14.009Z","dependency_job_id":null,"html_url":"https://github.com/Pogodaanton/shtorm","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Pogodaanton/shtorm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pogodaanton%2Fshtorm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pogodaanton%2Fshtorm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pogodaanton%2Fshtorm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pogodaanton%2Fshtorm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Pogodaanton","download_url":"https://codeload.github.com/Pogodaanton/shtorm/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pogodaanton%2Fshtorm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277462533,"owners_count":25822032,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-29T02:00:09.175Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fandom-wiki","mediawiki","mediawiki-api","mediawiki-bot","nodemw","wiki","wikia-api","wikipedia"],"created_at":"2024-09-26T05:24:13.701Z","updated_at":"2025-09-29T03:30:50.813Z","avatar_url":"https://github.com/Pogodaanton.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚡️ Shtorm - The semi-automatic scriptable wiki-bot runner\n\nWiki-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.\n\n_Shtorm tries to solve the shortfalls of both methods, by providing a GUI, and the respective API, for monitoring your running bot scripts._\n\n## Script-Client-Communication\n\nThe JavaScript API allows scripts to communicate with the client in the following ways:\n\n- 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)_\n- Generate diffing and editing prompts _(e.g.: Checking changes the script made to an article)_\n- Show the progress of pending tasks through the in-built progress bar\n\n## Efficiency-First\n\nThe JavaScript API allows you to generate **diffing or editing prompts**, as well as a **progress-bar** for visually indicating the status of pending tasks.\nFurthermore, scripts can expose multiple public variables, thus allowing users to **run the same script with different start values**.\n\n## Multi-User-Capable\n\nSince 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.\n\n\u003e 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.\n\n# Table of Contents\n\n- [About](#⚡️-Shtorm---The-semi-automatic-scriptable-wiki-bot)\n- [Demo Images](#Demo-Images)\n- [Usage](#Usage)\n  - [Server](#Server)\n  - [Client](#Client)\n  - [Scripting API](#Scripting-API)\n    - [Environment and Custom Modules](#Environment-and-custom-modules)\n    - [Supported Languages](#Supported-languages)\n    - [Fundamentals in a Shtorm Script](#Fundamentals-in-a-Shtorm-script)\n    - [Globals](#Globals)\n- [Installation](#Installation)\n  - [Create Config Files](#Create-config-files)\n  - [Build and Deploy](#Build-and-deploy)\n  - [Troubleshooting](#Troubleshooting)\n- [Contributing](#Contributing)\n- [License](#License)\n\n# Demo Images\n\n![Shtorm's main dashboard](https://github.com/Pogodaanton/shtorm/blob/master/demo.png?raw=true)\n\n# Usage\n\n\u003e For the installation instructions, head over to [Installation](#Installation)\n\n## Server\n\nThere are two essential directories for the server: A folder containing each executable script and a folder for the server database.\nThus, the following arguments can be added when starting the server:\n\n```sh\n$ shtorm-server [scriptsDirPath] [databaseDirPath]\n```\n\n## Client\n\nThe first user will always be called \"Admin\" with the password \"password\".\nChange this data **on first login** by heading over to \"Users\" and selecting \"Admin\".\n\n- You can add and edit users in the section \"Users\"\n- Add and edit bot configurations in the section \"Bot Configs\"\n- Add and edit projects on the homepage\n- Open or stop running tasks by pressing the clipboard icon in the upper right corner\n\n## Scripting API\n\nThe 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.\n\n\u003e For an example script take a look [here](https://github.com/Pogodaanton/shtorm/blob/master/packages/shtorm-server/scripts/example.js)\n\n### Environment and Custom Modules\n\nWhen a script is used, it is run in a [VM2](https://github.com/patriksimek/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**.\n\n### Supported Languages\n\nCurrently, Shtorm only accepts JavaScript files. It is possible to add TypeScript support by compiling the files manually before using them in Shtorm.\n\n### Fundamentals in a Shtorm Script\n\nYou have to export an object with two entries: `default` and `scriptOptions`.\n\n```TypeScript\nmodule.exports = {\n  default: () =\u003e new Promise((resolve, reject) =\u003e {}),\n  scriptOptions: [\n    { type: string, name: string, value: string | number },\n  ]\n}\n```\n\n**`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.\n\n**`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](#Globals).\n\n### Globals\n\nEach script file has the following global variables when run:\n\n**`bot`**: [Nodemw](https://github.com/macbre/nodemw) preconfigured bot instance. Append \"Async\" to each asynchronous function if you want to recieve a promisified version of the function.\n\n**`options`**: Object with public variables you defined in [`scriptOptions`](#Fundamentals-of-a-Shtorm-script). The entries are named after the `name` value in a scriptOptions object.\n\n**`updateClient`**: A function that updates specific GUI elements in the client. It returns a resolve-only promise if you request a dialog.\n\n```TypeScript\ntype updateClient = ({\n  /**\n   * Value of progress indicator read as percentage.\n   * 0 = indeterminate\n   */\n  progress?: number,\n  /**\n   * Title describing what's happening currently\n   */\n  progressMessage?: string,\n  /**\n   * An object which opens a dialog requiring user-input when defined\n   */\n  dialog?: {\n    /**\n     * Code: Single code editor the user may edit\n     * Diff: Diff view with right-side editor marked as user-editable\n     * Prompt: Dialog with a custom message and OK/Cancel buttons\n     */\n    type: \"code\" | \"diff\" | \"prompt\",\n    /**\n     * Title of the dialog or prompt message\n     */\n    msg: string,\n    /**\n     * Predefined input\n     */\n    code: string,\n    /**\n     * Language parameter for the code editor's syntax highlighter \n     */\n    language: string = \"xml\",\n    /**\n     * Used in conjunction with `type: \"diff\"`.\n     * Predefined input in the right-side editor\n     */\n    diffCode?: string,\n  }\n}) =\u003e Promise\u003cstring | undefined | null\u003e;\n```\n\n# Installation\n\nShtorm is using [Lerna](https://lerna.js.org/) to manage its two main components - the server and the client.\nYou can find them in their respective folders inside of `packages`.\n\n## Requirements\n\n- Node.js (v10.15.3)\n- yarn (optional; preferred)\n\n## Download Shtorm\n\n```bash\n$ git clone https://github.com/Pogodaanton/shtorm.git \u0026\u0026 cd shtorm\n```\n\n## Install Dependencies\n\n```bash\n$ yarn\n$ cd packages/shtorm-client \u0026\u0026 yarn\n$ cd ../shtorm-server \u0026\u0026 yarn\n$ cd ../../\n```\n\n## Create Config Files\n\nYou 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.\n\n## Build and Deploy\n\n```bash\n$ yarn build\n```\n\nYou will be able to find the newly generated items in `packages/shtorm-[server, client]/build`.\n\n### Shtorm-Server\n\nShtorm-server generates OS specific executables which start a web-server on the port specified in config.json.\n\n\u003e Make sure to tunnel the port to an existing [NGINX](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) or [Apache](https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension) 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**\n\n### Shtorm-Client\n\nThe contents of this build directory can be directly uploaded to a static server of any kind.\n\n## Troubleshooting\n\n- Note that the code has not been tested on Windows yet\n- Make sure to use the right node.js version (v10.15.3). [NVM](https://github.com/nvm-sh/nvm) might save your day...\n- `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 removing `node_modules` in the directory `shtorm-client` and reinstall the dependencies.\n\n\u003e Feel free to create an [issue](https://github.com/Pogodaanton/shtorm/issues) if these advices couldn't solve your installation troubles.\n\n# Contributing\n\n\u003e Looking for the [script development guide](#Scripting-API)?\n\nFollow the general installation instructions [above](#Installation) and start the local development system afterwards instead of generating a production build.\n\n```bash\n$ yarn start\n```\n\nImprovements to the codebase are gladly welcomed. Please make sure to **always link an issue to your pull request**.\n\n# License\n\nGPL-3.0 - See [LICENSE](https://github.com/Pogodaanton/shtorm/blob/master/LICENSE) for more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpogodaanton%2Fshtorm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpogodaanton%2Fshtorm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpogodaanton%2Fshtorm/lists"}