tiddlywiki-cpl

A command line tool to search, install and batch-update plugins from the TiddlyWiki Community Plugin Library (CPL) for:

• Node.js folder wikis — the folder layout produced by the official tiddlywiki --savewikifolder command (tiddlywiki.info + tiddlers/ + plugins/ + themes/ + languages/).
• MultiWikiServer (MWS) instances — the npm init @tiddlywiki/mws data folder (package.json + store/ + cache/).
• The MWS container image layout from MultiWikiServer PR #137 — the /data layout where only /data/store is persisted.

Zero runtime dependencies. Requires Node.js 20 or newer.

Install

npm install -g tiddlywiki-cpl

This provides two equivalent commands: tw-cpl and tiddlywiki-cpl.

Quick start

Run the commands inside your wiki / MWS instance folder (or pass --root):

# find plugins
tw-cpl search codemirror

# show details
tw-cpl info Gk0Wk/CPL-Repo

# install one or more plugins
tw-cpl install linonetwo/tw-react Gk0Wk/CPL-Repo

# list what is installed here
tw-cpl list

# batch-update every installed plugin
tw-cpl update

# preview what would be updated, change nothing
tw-cpl update --check

A plugin reference can be a full title ($:/plugins/Gk0Wk/CPL-Repo), an author/name pair (Gk0Wk/CPL-Repo), or a unique name suffix (CPL-Repo).

How plugins are installed per target

The tool auto-detects the target from the current directory (override with --root <dir> and --target <type>):

| Target | Detected by | Plugin location | | ----------- | --------------------------------------------- | --------------- | | node-wiki | tiddlywiki.info exists | <wiki>/plugins/<name>/plugin.info (+ themes/, languages/ by plugin type) — the layout tiddlywiki --savewikifolder writes, auto-loaded by TiddlyWiki, no tiddlywiki.info change needed | | mws | package.json (@tiddlywiki/mws-instance) + store/ | <instance>/node_modules/tiddlywiki/plugins/<author>/<name>/ — the core plugin folders MWS rescans on startup | | mws-image | same as mws, inside the container data root | same as mws; the tool warns that only /data/store is persisted, so rebuild the image or mount the plugins directory as a volume |

For mws/mws-image, restart the server (mws listen) after installing — MWS builds its plugin cache from the tiddlywiki core folders at startup.

Plugins installed through the in-wiki plugin library UI (e.g. CPL inside the browser) are saved by TiddlyWiki's filesystem adaptor as loose plugin tiddler files inside <wiki>/tiddlers, in one of two canonical layouts (see core-server/filesystem.js and TiddlyWiki-CPL#166):

• a single $__plugins_<author>_<name>.json holding a JSON array with the plugin tiddler and no .meta file (TiddlyWiki chooses this when a field name contains : or #, e.g. the Modern.TiddlyDev#SHA256-Hashed field);
• $__plugins_<author>_<name>.json holding the raw plugin payload text plus a .json.meta sidecar with a tid-style field: value block.

tw-cpl update finds both layouts and rewrites them in place, keeping the original layout, key order, indentation and meta format. New .meta files are always written in TiddlyWiki's tid-style field block format.

Commands

tw-cpl search <query>        Search the CPL index
tw-cpl info <plugin>         Show details of one plugin
tw-cpl install <plugin...>   Install plugins into the current target
tw-cpl update [plugin...]    Batch-update installed plugins (no argument = all)
tw-cpl list                  List plugins installed in the current target
tw-cpl sources               Check reachability/latency of all known CPL sources
tw-cpl cache [--refresh]     Show or refresh the cached CPL index
tw-cpl help                  Show help

Options: --root <dir>, --target <node-wiki|mws|mws-image>, --source <name> (default netlify), --registry <url> (fully custom library, overrides --source), --refresh, --check (with update), --json. Set TW_CPL_SOURCE to change the default source permanently.

The CPL index is cached for one hour in %LOCALAPPDATA%\tiddlywiki-cpl on Windows or ~/.cache/tiddlywiki-cpl elsewhere (override with TW_CPL_CACHE).

Sources (mirrors)

The CPL repository builds its static library with GitHub Actions and publishes the same content to several places. Use tw-cpl sources to check which of them are reachable from your network and how fast they are, then switch with --source:

| Source | Where | Notes | | --------- | ------------------------------------------------- | ----- | | netlify | https://tw-cpl.netlify.app | official deployment (default) | | gh_pages| https://tiddly-gittly.github.io/TiddlyWiki-CPL | same build on GitHub Pages | | jsdelivr| https://cdn.jsdelivr.net/gh/tiddly-gittly/TiddlyWiki-CPL@cache | CDN mirror of the repo cache branch; usually the fastest choice inside China |

tw-cpl sources                          # probe all sources
tw-cpl --source jsdelivr search react   # use a specific source for one command
tw-cpl --registry https://my.example/cpl-library install foo/bar   # self-hosted library

--registry assumes the standard library/index.html + library/plugins/ layout; self-hosted mirrors of the cache branch layout are also supported via the library API (format: 'cache').

How it works

The CLI reads the static library published by TiddlyWiki-CPL (library/index.html → assetList), downloads the selected plugin payload (library/plugins/<name>.json — a plugin tiddler whose text field holds the inner tiddlers map) and decomposes it into a plugin folder: plugin.info plus one .tid/.json file per contained tiddler, exactly the format the Node.js TiddlyWiki and MWS loaders understand.

Development

npm test    # unit + integration tests (a local fixture mimics the CPL library)
npm run smoke  # live test against https://tw-cpl.netlify.app (read-only)

License

MIT