wikiploy 1.3.4 → 1.4.1

package/.vscode/launch.json

@@ -7,20 +7,20 @@
 		{
 			"type": "node",
 			"request": "launch",
-			"name": "Deploy test.js",
+			"name": "Run current JS",
 			"skipFiles": [
 				"<node_internals>/**"
 			],
-			"program": "${workspaceFolder}\\src\\Wiki_bot_test.js"
+			"program": "${workspaceFolder}\\${file}"
 		},
 		{
 			"type": "node",
 			"request": "launch",
-			"name": "Run current JS",
+			"name": "ploy-lite test.js",
 			"skipFiles": [
 				"<node_internals>/**"
 			],
-			"program": "${workspaceFolder}\\${file}"
-		}
+			"program": "${workspaceFolder}\\src\\ploy_test_lite.js"
+		},
 	]
 }

package/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+	"search.exclude": {
+		"package-lock.json": true,
+	},
+    "editor.detectIndentation": false,
+    "editor.useTabStops": true,
+    "editor.insertSpaces": false,
+}

package/DEV.md

@@ -16,7 +16,7 @@ Run first `npm i`.
 You might want to run `npm up` to update some scripts too.
 
 Recomended global modules/tools:
-```
+```bash
 npm install -g eslint
 npm install -g mocha
 ```
@@ -36,13 +36,14 @@ You can also run (and debug) each test case directly from a test file. You might
 ## Publishing
 
 Step. 1. Check.
-```
+```bash
+npm up
 npm test
 ```
 Step. 2. Change version in the package.
 
 Step. 3. Final commands.
-```
+```bash
 npm up
 npm test
 npm publish

package/README.md

@@ -10,23 +10,54 @@ Wikiploy
 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.
 
-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 full
+
+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
+
+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.
+
+**WikiployLite** is less memory heavy as it doesn't use a browser (and doesn't use `Puppeteer`). You do need to setup a bot password though (on [[Special:BotPasswords]]). It's not as hard as it might seem as you can do this on any Wikimedia wiki and it will work for all WMF wikis. You don't need a bot account for this to work.
+
+Botpass configuration:
+* Setup on e.g.: https://test.wikipedia.org/wiki/Special:BotPasswords
+* Rights you should setup (if you can): `assets\Bot passwords - Test Wikipedia.png`.
+* Example config file in: `assets\bot.config.public.js`.
+
+**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} from 'wikiploy';
+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);
 
-const ployBot = new Wikiploy();
+// 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 'v2.7.0: adding new test mode';
+	return `v${version}: adding new test mode`;
 }
 
-// run asynchronusly to be able to wait for results
+// run asynchronously to be able to wait for results
 (async () => {
 	const configs = [];
 	configs.push(new DeployConfig({
@@ -40,7 +71,7 @@ ployBot.summary = () => {
 });
 ```
 
-Note that `~` will be `User:SomeName` so the user space of currenlty logged in user.
+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/).
@@ -65,4 +96,5 @@ configs.push(new DeployConfig({
 ## External links
 * [Wikiploy rollout example (repo)](https://github.com/Eccenux/wikiploy-rollout-example/)
 * [Wikiploy on npm](https://www.npmjs.com/package/wikiploy)
+* [Wikiploy on en.wiki](https://en.wikipedia.org/wiki/Wikipedia:Wikiploy)
 * [Wikiploy on pl.wiki](https://pl.wikipedia.org/wiki/Wikipedia:Wikiploy)

package/assets/bot.config.public.js

@@ -0,0 +1,13 @@
+/**
+	Bot with edit&create rights.
+	
+	You can create the bot account on any wiki. E.g. on the test wiki:
+	https://test.wikipedia.org/wiki/Special:BotPasswords
+
+	The username will be something like `MyName@Wikiploy` where `Wikiploy` would be a bot name
+	(you can choose any bot name but "Wikiploy" would be a good choice to separate it from other things).
+	
+	The password will be something like `12345abcdefpqrst123456abcdef`.
+ */
+export const username = '...@...';
+export const password = '...';

package/assets/test.css

@@ -5,4 +5,4 @@
 .something {
 	display: block;
 }
-/* puppeteer 20.8.x */
+/* puppeteer 20.8.x xor mwn 1.11.x */

package/assets/test.js

@@ -1,3 +1,3 @@
 // test.js
 console.log('test');
-// puppeteer 20.8.x
+// puppeteer 20.8.x xor mwn 1.11.x

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wikiploy",
-	"version": "1.3.4",
+	"version": "1.4.1",
 	"description": "User scripts and gadgets deployment for MediaWiki (Wikipedia).",
 	"main": "src/index.js",
 	"type": "module",
@@ -25,11 +25,12 @@
 	},
 	"homepage": "https://github.com/Eccenux/Wikiploy#readme",
 	"dependencies": {
+		"mwn": "1.11.x",
 		"puppeteer": "20.8.x"
 	},
 	"devDependencies": {
 		"chai": "4.x",
-		"mocha": "10.x",
-		"eslint": "8.x"
+		"eslint": "8.x",
+		"mocha": "10.x"
 	}
 }

package/src/DeployConfig.js

@@ -53,7 +53,7 @@ export default class DeployConfig {
 
 	/** info. */
 	info() {
-		return `deploy "${this.src}" to "${this.dst}"`;
+		return `deploy "${this.src}" to "${this.dst}"` + (!this.site.length ? '' :  ` (to ${this.site})`);
 	}
 
 }

package/src/Wikiploy.js

@@ -1,5 +1,6 @@
 import puppeteer, { Browser } from 'puppeteer'; // v13+
 
+import WikiployBase from './WikiployBase .js';
 import WikiOps from './WikiOps.js';
 import PageCache from './PageCache.js';
 // eslint-disable-next-line no-unused-vars
@@ -18,18 +19,18 @@ function sleep(sleepMs) {
 
 /**
  * MediaWiki deployment automation.
+ * Deploy scripts with a browser (puppetter).
  * 
- * @property _browser {Browser} The user's email
+ * @property _browser {Browser} Browser connection.
  */
-export default class Wikiploy {
+export default class Wikiploy extends WikiployBase {
 	constructor() {
+		super();
+
 		this.cache = new PageCache();
-		/** Disable save. */
-		this.mock = false;
+
 		/** Wait before close [ms] (or you can set a breakpoint to check stuff). */
 		this.mockSleep = 0;
-		/** Default wiki site (domain). */
-		this.site = 'pl.wikipedia.org';
 
 		/** @private Browser connection. */
 		this._browser = false;
@@ -42,10 +43,12 @@ export default class Wikiploy {
 	}
 
 	/**
-	 * Deploy scripts.
+	 * Deploy scripts with a browser (puppetter).
 	 * @param {DeployConfig[]} configs 
 	 */
 	async deploy(configs) {
+		console.log('[Wikiploy] deploy %d configs (default site: %s)...\n', configs.length, this.site);
+
 		const bot = this._bot;
 		const browser = await this.init();
 		const page = await bot.openTab(browser);
@@ -102,7 +105,7 @@ export default class Wikiploy {
 	async prepareUser(config, page) {
 		const bot = this._bot;
 
-		let site = config.site;
+		const site = this.getSite(config);
 		// from cache
 		if (site in this._users) {
 			let changed = config.setUser(this._users[site]);
@@ -127,31 +130,6 @@ export default class Wikiploy {
 		return changed;
 	}
 
-	/**
-	 * Prepare edit summary.
-	 * 
-	 * @param {DeployConfig} config Config.
-	 * @returns {String} Edit summary.
-	 * @private
-	 */
-	prepareSummary(config) {
-		let summary = typeof config.summary === 'function' ? config.summary() : this.summary(config);
-		return `#Wikiploy ${summary}`;
-	}
-
-	/**
-	 * Custom summary.
-	 * 
-	 * This can be e.g. version number and short, text summary.
-	 * You can use config to add e.g. file name too (which is default).
-	 * 
-	 * @param {DeployConfig} config Deployment configuration object.
-	 * @returns {String} Summary added to saved edits.
-	 */
-	summary(config) {
-		return config.src;
-	}
-
 	/**
 	 * Prepare base URL.
 	 * 
@@ -160,7 +138,7 @@ export default class Wikiploy {
 	 * @private
 	 */
 	baseUrl(config) {
-		const site = config.site.length ? config.site : this.site;
+		const site = this.getSite(config);
 		const origin = `https://${site}`;
 		const baseUrl = `${origin}/w/index.php`;
 		return baseUrl;

package/src/WikiployBase .js

@@ -0,0 +1,54 @@
+// eslint-disable-next-line no-unused-vars
+import DeployConfig from './DeployConfig.js';
+
+/**
+ * Generic Wikiploy.
+ */
+export default class WikiployBase {
+	constructor() {
+		/** Disable save. */
+		this.mock = false;
+		/** Default wiki site (domain). */
+		this.site = 'pl.wikipedia.org';
+	}
+
+	/**
+	 * Deploy many...
+	 * @param {DeployConfig[]} configs 
+	 */
+	async deploy(configs) {
+		console.log(`done %d`, configs.length);
+		throw 'Not implemented';
+	}
+
+	/**
+	 * Prepare edit summary.
+	 * 
+	 * @param {DeployConfig} config Config.
+	 * @returns {String} Edit summary.
+	 * @private
+	 */
+	prepareSummary(config) {
+		let summary = typeof config.summary === 'function' ? config.summary() : this.summary(config);
+		return `#Wikiploy ${summary}`;
+	}
+
+	/** @private Get site for a config. */
+	getSite(config) {
+		let site = config.site.length ? config.site : this.site;
+		return site;
+	}
+
+	/**
+	 * Custom summary.
+	 * 
+	 * This can be e.g. version number and short, text summary.
+	 * You can use config to add e.g. file name too (which is default).
+	 * 
+	 * @param {DeployConfig} config Deployment configuration object.
+	 * @returns {String} Summary added to saved edits.
+	 */
+	summary(config) {
+		return config.src;
+	}
+}

package/src/WikiployLite.js

@@ -0,0 +1,112 @@
+import { mwn as Mwn } from 'mwn';
+
+import WikiployBase from './WikiployBase .js';
+// eslint-disable-next-line no-unused-vars
+import DeployConfig from './DeployConfig.js';
+
+import { promises as fs } from "fs";	// node v11+
+
+import * as verlib from './version.js';
+const version = await verlib.readVersion('./package.json');
+
+/**
+ * MediaWiki deployment automation.
+ * 
+ * Deploy scripts with the Bot API.
+ * https://test.wikipedia.org/wiki/Special:BotPasswords
+ */
+export default class WikiployLite extends WikiployBase {
+	constructor(botpass) {
+		super();
+
+		/** [[Special:BotPasswords]] data. */
+		this.botpass = {
+			username: botpass.username,
+			password: botpass.password,
+		};
+	
+		/** @private Bots cache. */
+		this._bots = {};
+	}
+
+	/**
+	 * Deploy with bot password.
+	 * @param {DeployConfig[]} configs 
+	 */
+	async deploy(configs) {
+		console.log('[Wikiploy] deploy %d configs (default site: %s)...\n', configs.length, this.site);
+		// main loop
+		for (const config of configs) {
+			await this.save(config);
+		}
+		console.log(`done`);
+	}
+
+	/**
+	 * Init/get bot for given config.
+	 * @private
+	 * @param {DeployConfig} config Config.
+	 */
+	async getBot(config) {
+		const site = this.getSite(config);
+		// from cache
+		if (site in this._bots) {
+			return this._bots[site];
+		}
+		const apiUrl = `https://${site}/w/api.php`;
+		const bot = await Mwn.init({
+			apiUrl: apiUrl,
+			username: this.botpass.username,
+			password: this.botpass.password,
+			// UA required for WMF wikis: https://meta.wikimedia.org/wiki/User-Agent_policy
+			userAgent: `Wikiploy ${version} ([[:en:Wikipedia:Wikiploy|Wikiploy]])`,
+		});
+		this._bots[site] = bot;
+		return bot;
+	}
+
+	/**
+	 * Deploy script.
+	 * @param {DeployConfig} config Config.
+	 */
+	async save(config) {
+		console.log('[Wikiploy]', config.info());
+		const bot = await this.getBot(config);
+		// prepare user
+		if (config.needsUser()) {
+			await this.prepareUser(config);
+		}
+		// page
+		const pageTitle = config.dst;
+		// content of the file
+		const contents = await fs.readFile(config.src, 'utf8');
+		// edit description
+		const summary = this.prepareSummary(config);
+
+		// save
+		if (!this.mock) {
+			await bot.save(pageTitle, contents, summary);
+			console.log('saved');
+		} else {
+			console.warn('mock on "%s", inserting %d bytes, summary: %s', pageTitle, contents.length, summary);
+		}
+	}
+
+	/**
+	 * Prepare user in config.
+	 * 
+	 * Note! Modifies the config.
+	 * 
+	 * @param {DeployConfig} config Config.
+	 * @private
+	 */
+	async prepareUser(config) {
+		// read
+		let userName = this.botpass.username.replace(/@.+/, '');
+
+		// finalize
+		let changed = config.setUser(userName);
+		return changed;
+	}
+
+}

package/src/index.js

@@ -1,7 +1,11 @@
 import DeployConfig from './DeployConfig.js';
 import Wikiploy from './Wikiploy.js';
+import WikiployLite from './WikiployLite.js';
+import * as verlib from './version.js';
 
 export {
 	DeployConfig,
+	verlib,
+	WikiployLite,
 	Wikiploy
 };

package/src/ploy_test_botapi.js

@@ -0,0 +1,40 @@
+// import DeployConfig from './DeployConfig.js';
+// import Wikiploy from './Wikiploy.js';
+
+import { mwn as Mwn } from 'mwn';
+
+import * as ver from './version.js';
+
+// https://test.wikipedia.org/wiki/Special:BotPasswords
+// Note that username should contain `@`.
+import * as botpass from './bot.config.js';
+
+const version = await ver.readVersion('./package.json');
+
+
+console.log('Test:', version);
+
+// auth
+const bot = await Mwn.init({
+	apiUrl: 'https://pl.wikipedia.org/w/api.php',
+	username: botpass.username,
+	password: botpass.password,
+	// UA required for WMF wikis: https://meta.wikimedia.org/wiki/User-Agent_policy
+	userAgent: `Wikiploy ${version} ([[:en:Wikipedia:Wikiploy|Wikiploy]])`,
+});
+
+/**
+ * Mwn info:
+ * https://mwn.toolforge.org/docs/editing-pages
+ * (note that docs seem a bit outdated)
+ * 
+ * bot.save() tests:
+ * <li>Works for editing and creating pages.
+ * <li>Ignores empty edit.
+ */
+const pageTitle = 'Wikipedysta:Nux/test-mwnapi--test.js';
+const content = 'yadda(xy);';
+const summary = `Test ([[:en:Wikipedia:Wikiploy|Wikiploy]] ${version})`;
+await bot.save(pageTitle, content, summary);
+
+console.log('Done:', version);

package/src/ploy_test_lite.js

@@ -0,0 +1,41 @@
+import DeployConfig from './DeployConfig.js';
+import WikiployLite from './WikiployLite.js';
+
+// https://test.wikipedia.org/wiki/Special:BotPasswords
+// Note that username should contain `@`.
+import * as botpass from './bot.config.js';
+
+const ployBot = new WikiployLite(botpass);
+// mock
+// ployBot.mock = true;
+// ployBot.mockSleep = 5_000;
+
+(async () => {
+	const configs = [];
+	configs.push(new DeployConfig({
+		src: 'assets/test.js',
+		dst: '~/test-wikiploylite--test.js',
+	}));
+	configs.push(new DeployConfig({
+		src: 'assets/test.js',
+		dst: '~/test-wikiploylite--test.js',
+		site: 'en.wikipedia.org',
+	}));
+	configs.push(new DeployConfig({
+		src: 'assets/test.css',
+		dst: '~/test-wikiploylite--test.css',
+	}));
+	configs.push(new DeployConfig({
+		src: 'assets/test.css',
+		dst: '~/test-wikiploylite--test.css',
+		site: 'en.wikipedia.org',
+	}));
+	await ployBot.deploy(configs);
+
+	// check bots
+	let bots = Object.keys(ployBot._bots);
+	console.log('Bots: %d', bots.length, bots);
+})().catch(err => {
+	console.error(err);
+	process.exit(1);
+});

package/src/version.js

@@ -0,0 +1,12 @@
+import fsa from 'fs/promises'
+
+/** Read version from JSON file (like package.json). */
+export async function readVersion (config) {
+	const data = JSON.parse(await fsa.readFile(config, 'utf8'));
+	return data.version;
+}
+
+/** Replace version placeholders. */
+export function applyVersion (content, version) {
+	return content.replace(/\{version\}/g, version);
+}