Use this tool to upload changes to your Produnto packages to a temporary sandbox on a wiki. They can then be tested before you commit and release them.

Installation

Node.js version 18 or later is required.

To install the package globally from npm, use

$ npm install -g produnto-sandbox
$ produnto-sandbox configure

For a git checkout, run these commands in the source directory:

$ npm install
$ npx produnto-sandbox configure

If you're using a private test wiki, run produnto-sandbox register-consumer to launch a browser window providing a form for consumer registration. All fields should be pre-filled, except for the confirmation checkbox. When you submit the form, MediaWiki will provide the client ID to use during configuration. The secret token is not used and can be discarded.

Usage

produnto-sandbox watch uploads a directory as a package, and then watches it for changes, regularly uploading those changes to the wiki.

produnto-sandbox watch [...options...] /path/to/somepackage

By default, the final part of the path is used as the package name. To configure a different package name, use the syntax <name>:<path>:

produnto-sandbox watch mypackage:/path/to/package

Multiple packages can be uploaded:

produnto-sandbox watch package1:/path/to/package1 package2:/path/to/package2

The maximum total size of uploaded files is 8 MiB. Uploaded files that exactly match files that have already been released are not included in this limit.

To terminate the session, press ctrl-C. This will delete the sandbox from the wiki.

Command line options

• --help: Show help.
• --config=<path>: Override the path of the configuration file.
• --name=<name>: Set the sandbox name.
• --login: Ignore the saved session, force a new login.
• --debug: Show debugging information, especially request/response headers.

Authentication and security

produnto-sandbox watch launches a browser session to authenticate on the wiki using OAuth. Credentials are saved in a temporary file. It temporarily runs a webserver on localhost to provide an OAuth callback URL.

As such, it may be difficult to run this script inside a container. You would need to configure a suitable browser launcher, and forward localhost port 1828 from the system the browser runs on to the container the script runs on.

Activation

To activate the sandbox, visit Special:ProduntoSandbox on the wiki. While produnto-sandbox watch is running, there should be a box on the special page with the CLI session name. Click the "activate" button. Previewing any page will then use the uploaded sandbox versions of the files.

Depending on which preview UI you use, a warning may be shown when you preview the page, confirming that the sandbox package was used.

WARNING: Preview rendering will not match page view rendering while a sandbox is active.

Configuration

You can use produnto-sandbox configure to change configuration settings.

Options:

• --interactive, -i: Ask questions for initial setup.
• --ignore <pattern>: Add a pattern to the list of ignore rules. Do not upload files matching this pattern to the server.
• --unignore <pattern>: Remove a pattern from the list of ignore rules.
• --localhost-port <port>: Set the localhost port. This must match the OAuth consumer registration.
• --script-url <url>: Set the wiki script path URL, e.g. https://www.mediawiki.org/w
• --client-id <id>: Set the OAuth client ID or consumer key.
• --sandbox-name <name>: Set the sandbox name.
• --data-dir <path>: Set the directory in which to store session files.
• --insecure-https on|off: Disable HTTPS certificate validation. This is only for use with a local test server, do not use it for a public wiki.

produnto-sandbox searches for config.json in the following paths:

• ~/.config/produnto-sandbox/config.json
• /etc/produnto-sandbox/config.json
• The source directory

If you run produnto-sandbox watch and there is no configuration file, it will ask questions on the terminal and write a configuration file.

The file is a JSON object with properties ignore, localhostPort, scriptUrl, clientId, name, dataDir and insecureHttps as described above.