wikiploy 1.7.2 → 1.8.0

package/README.building your project.md

@@ -0,0 +1,137 @@
+# Building your project
+
+There are various ways to build scripts. You can use browserify, webpack, TypeScript compiler etc... or even don't build at all. This is all fine, but not all solution are equally well suite for the wiki world and choosing the right solution takes time.
+
+So here is a recommended project setup to save you some time :)
+
+Some of this is based on a real script. So if you want you can take a look at [wikibot-jsbot-core](https://github.com/Eccenux/wikibot-jsbot-core). Also you might want to take a look at a template repository for Wikiploy: [wikiploy-rollout-example](https://github.com/Eccenux/wikiploy-rollout-example). 
+
+## Recommended setup for building scripts
+
+Example `.gitignore` for your project:
+```
+/node_modules
+*.lnk
+*.priv.*
+bot.config.js
+```
+
+Your `package.json` (crucial part being `scripts`):
+```js
+{
+	"name": "wiki-gadget-yourname",
+	"type": "commonjs",
+	"scripts": {
+		"test": "mocha",
+		"build": "browserify src/main.js -o yourname.js",
+		"deploy": "node wikiploy.mjs",
+		"rollout": "npm run build && npm run deploy"
+	},
+	"devDependencies": {
+		"browserify": "17.x",
+		"chai": "4.x",
+		"eslint": "8.x",
+		"mocha": "10.x"
+	},
+	"dependencies": {
+		"wikiploy": "1.x"
+	}
+}
+```
+
+Your `main.js` could look something like this:
+```js
+var { MyGadget } = require("./MyGadget");
+
+// bot instance
+var gadget = new MyGadget();
+
+$(function(){
+	gadget.init();
+})
+```
+
+## Visual Studio Code setup
+
+[VSC](https://code.visualstudio.com/) is a free editor that over years became almost like an IDE.
+
+VSCode helper to install a set of extensions `.vscode/extensions.json`:
+```
+{
+	"recommendations": [
+		"gsppvo.vscode-commandbar",
+		"hbenl.vscode-test-explorer",
+		"hbenl.vscode-mocha-test-adapter"
+	]
+}
+```
+
+VSC settings `.vscode/settings.json`:
+```
+{
+	"search.exclude": {
+		"package-lock.json": true,
+	},
+    "editor.detectIndentation": false,
+    "editor.useTabStops": true,
+    "editor.insertSpaces": false,
+}
+```
+
+## Basic script and dst
+
+Your minimal `wikiploy.mjs`:
+```js
+import {DeployConfig, WikiployLite, userPrompt} from 'wikiploy';
+
+import * as botpass from './bot.config.js';
+const ployBot = new WikiployLite(botpass);
+
+// default site for DeployConfig
+ployBot.site = "en.wikipedia.org";
+
+// run asynchronously to be able to wait for results
+(async () => {
+	// Note! The `userPrompt` requires an interactive terminal.
+	// In VSC you can use tasks to get an interactive terminal and still run wikiploy from your commandbar.
+	const summary = await userPrompt('Summary of changes (empty for default summary):');
+	if (typeof summary === 'string' && summary.length) {
+		ployBot.summary = () => {
+			return summary;
+		}
+	}
+
+	// push out file(s) to wiki
+	const configs = [];
+	configs.push(new DeployConfig({
+		src: 'test.js',
+		dst: '~/test-wikiploy--test.js',
+		nowiki: true,
+	}));
+	await ployBot.deploy(configs);
+})().catch(err => {
+	console.error(err);
+	process.exit(1);
+});
+```
+
+Note that `~` will be `User:SomeName` so the user space of a currently logged in user (you user space).
+You can omit `dst` and it will default to `dst: '~/${src}'`.
+
+More about this basic code and `dst` in the [Wikiploy rollout example](https://github.com/Eccenux/wikiploy-rollout-example/).
+
+## Exporting stuff 
+
+Your `main.js` could look something like this:
+```js
+var { MyGadget } = require("./MyGadget");
+
+// bot instance
+var gadget = new MyGadget();
+
+$(function(){
+	gadget.init();
+})
+```
+
+Note that browserify will wrap your code with a function automatically. So you don't have to worry about leaking variables to global scope.

package/README.md

@@ -1,33 +1,40 @@
 Wikiploy
 ==========================
 
-## Polski opis
+Wikiploy is a one-click solution to deploy JS and CSS to Wikipedia.  
 
-[Wikipedia:Wikiploy](https://pl.wikipedia.org/wiki/Wikipedia:Wikiploy)
+After initial setup you can quickly build and deploy your user scripts and gadgets. Thought this was designed to work with Wikipedia you should be able to deploy to any [MediaWiki](https://www.mediawiki.org/) based wiki. You can even deploy to multiple websites with one-click (to whatever you have access to).
 
-## English description
+See also:
 
-User scripts and gadgets deployment for wikis (Wikipedia or more generally MediaWiki based wiki).
-Rollout your JS, CSS etc from your git repository to as many MW wikis as you need.
+- [README: building your project](README.building your project.md) recommendation on how to build JS and CSS for your gadgets.
+- [Wikipedia:Wikiploy on pl.wiki](https://pl.wikipedia.org/wiki/Wikipedia:Wikiploy) for Polish description.
+- (more links on the bottom)
 
-## New options
+## New capabilities
 
 ### nowiki (v1.7)
 
-Note! It is recomended that you use `nowiki: true` for all JS files. The `nowiki` property is a new option in `DeployConfig` since Wikiploy v1.7.
+Note! It is recommended that you use `nowiki: true` for all JS files. The `nowiki` property is a new option in `DeployConfig` since Wikiploy v1.7.
 
 JavaScript page is still a wiki page... Kind of. It can be added to a category or link to other pages. To avoid this use the nowiki option.
 
 Don't add this option to CSS though. It won't work correctly.
 
-### Wikiploy full
+### userPrompt (v1.8)
+
+Prompt for summary so that you don't forget to change it. This is a bit more tricky to setup, but can still work as a one-click build (see [README: building your project](README.building your project.md)).     
+
+## Wikiploy types
+
+### Wikiploy full (deprecated)
 
 This is using [Puppeteer](https://pptr.dev/) to control [Chrome Canary](https://www.google.com/chrome/canary/) or similar. You just open Chrome with remote debug enabled and run a script. The idea is that you are logged in in Chrome and so all edits are still your edits. You can keep the Canary running in the background when you are changing and deploying more stuff. 
 
 Wikiploy will also work with other Chromium based browser. [Instructions for enabling remote debug in MS Edge](https://learn.microsoft.com/en-us/microsoft-edge/devtools-protocol-chromium/).
 Note that to completely close Edge you might need use settings: Continue running in background when Microsoft Edge is closed (pl. *Kontynuuj działanie aplikacji i rozszerzeń w tle po zamknięciu przeglądarki Microsoft Edge*).
 
-### WikiployLite
+### WikiployLite (recommended)
 
 The `WikiployLite` class is using a bot API to deploy scripts. You can use standard `Wikiploy` and `WikiployLite` interchangeably. The `DeployConfig` is the same. WikiployLite is recommended as long as you can use it.
 
@@ -40,52 +47,6 @@ Botpass configuration:
 
 **Warning!** Never, ever publish your bot password. If you do spill your password, reset/remove the password ASAP (on Special:BotPasswords).
 
-Example `.gitignore` for your project:
-```
-/node_modules
-*.lnk
-*.priv.*
-bot.config.js
-``` 
-
-## Basic script and dst
-```js
-import {DeployConfig, Wikiploy, WikiployLite, verlib} from 'wikiploy';
-
-// full
-//const ployBot = new Wikiploy();
-// lite
-import * as botpass from './bot.config.js';
-const ployBot = new WikiployLite(botpass);
-
-// extra if you want to read your version from the package.json
-const version = await verlib.readVersion('./package.json');
-
-// custom summary
-ployBot.summary = () => {
-	//return 'v2.7.0: adding new test mode';
-	return `v${version}: adding new test mode`;
-}
-
-// run asynchronously to be able to wait for results
-(async () => {
-	const configs = [];
-	configs.push(new DeployConfig({
-		src: 'test.js',
-		dst: '~/test-wikiploy--test.js',
-		nowiki: true,
-	}));
-	await ployBot.deploy(configs);
-})().catch(err => {
-	console.error(err);
-	process.exit(1);
-});
-```
-
-Note that `~` will be `User:SomeName` so the user space of a currently logged in user (you user space).
-You can omit `dst` and it will default to `dst: '~/${src}'`.
-
-More about this basic code and `dst` in the [Wikiploy rollout example](https://github.com/Eccenux/wikiploy-rollout-example/).
 
 ## Different wiki sites
 Wikiploy defaults to deployments on `pl.wikipedia.org`.

package/assets/test.css

@@ -5,4 +5,4 @@
 .tavern {
 	display: block;
 }
-/* puppeteer 21.5.2 xor mwn 2.0.1 */
+/* puppeteer 21.6.1 xor mwn 2.0.2 */

package/assets/test.js

@@ -7,4 +7,4 @@
  */
 // test.js
 console.log('test');
-/* puppeteer 21.5.2 xor mwn 2.0.1 */
+/* puppeteer 21.6.1 xor mwn 2.0.2 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wikiploy",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "description": "User scripts and gadgets deployment for MediaWiki (Wikipedia).",
   "main": "src/index.js",
   "type": "module",
@@ -27,7 +27,7 @@
   "homepage": "https://github.com/Eccenux/Wikiploy#readme",
   "dependencies": {
     "mwn": "2.0.x",
-    "puppeteer": "21.5.x"
+    "puppeteer": "21.6.x"
   },
   "devDependencies": {
     "bump-version": "0.5.0",

package/src/index.js

@@ -2,10 +2,12 @@ import DeployConfig from './DeployConfig.js';
 import Wikiploy from './Wikiploy.js';
 import WikiployLite from './WikiployLite.js';
 import * as verlib from './version.js';
+import { userPrompt } from './userPrompt.js';
 
 export {
 	DeployConfig,
 	verlib,
+	userPrompt,
 	WikiployLite,
 	Wikiploy
 };

package/src/userPrompt.js

@@ -0,0 +1,16 @@
+import readline from 'node:readline';
+import { stdin as input, stdout as output } from 'node:process';
+
+const userPrompt = (prompt) => {
+	const rl = readline.createInterface({ input, output });
+
+	return new Promise((resolve) => {
+		rl.question(prompt, (summary) => {
+			rl.close();
+
+			resolve(summary);
+		});
+	});
+};
+
+export { userPrompt };