wiki-plugin-hitchhiker

The house UX layer for the hitchhiker Federated Wiki farms. It rewilds several built-in client behaviours without forking or rebuilding client.js, and ships some farm-wide default pages. Piloted on the private farm (:4243).

It has three parts:

1. Default pages (pages/)

Files in pages/ are served on every site of the farm (wiki-server's plugin-pages fallback), unless a site has authored its own page of that slug. Currently: tools, changes-to-this-site (copied from hitchhikers.earth, journals stripped), and about-hitchhiker-plugin.

This plugin defines no authorable item type — its factory.json exists only to declare the bundled pages — its value is the pages and the served client script below.

2. Client UX override (client/wiki-ux.js)

Served at /plugins/hitchhiker/wiki-ux.js and loaded globally on every page by the wiki-security-hitchhiker bootstrap (a fork of wiki-security-friends whose client/security.js injects <script src=/plugins/hitchhiker/wiki-ux.js>; that security module is the only client hook that auto-runs on every page). The private farm's config.json sets security_type: hitchhiker.

wiki-ux.js reaches the client only through the public window.wiki / window.plugins surface. It installs:

• Factory chooser — replaces window.plugins.factory.emit with a searchable, curated, described plugin picker (keeps the original bind, so all drop.js drag-drops survive); wraps bind for extra media-URL drops.
• Page-flag click → an in-lineup page, inserted to the right of the clicked page (never wiping the lineup):
  • logged in → a Tools page: Fork (only for remote/blue or unsaved/yellow pages), 🔍 Similarity search (only if wiki-plugin-similarity is installed — opens a ghost report of similar pages), Trash (→ recycler, recoverable), Clean the journal (ghost with a stripped journal), Simplify (collapse the lineup to Welcome Visitors + the page).
  • logged out → a Navigate page: Simplify + this site's recent Changes.
  • Shift-click the flag = Simplify directly (skip the page).
• Page-flag drop target — drop a URL / link / page-flag onto a flag: the favicon shows a loud pulsing highlight; on drop it opens a ghost preview card (see the server below).

3. Server component (server/server.js, ESM) — two tiny routes, no dependencies

• GET /system/farm-domains.json → { local: [...], public: [...] } — which domains this farm serves.
• GET /system/outposts.json → { unfurl: ["http://mini.private.fish", …] } — which Outposts the browser may ask for link previews. Read from {status}/outpost.json per site (wins), else the OUTPOST_URL env (comma-separated), else []. Cached by mtime; no restart to change.

Since 0.4.0 this plugin does no unfurling. The link-preview builder — the two heavy extractor libraries, ~14 MB of heap — is wiki-plugin-unfurl, installed on one well-resourced host (an Outpost). wiki-ux.js calls that host directly from the browser (its route sets Access-Control-Allow-Origin: *; a plain GET is a simple request, no preflight), shuffling the list and trying each with a 2 s timeout. No Outpost, or none answering, means the drop report renders without a card. Nothing logs. Absence is a normal state.

The list shape is deliberate: swapping the source for a DNS-SD SRV lookup later is one function.

Install / build

# Use the farm's Node (v24) — npm under an older node in PATH will fail.
export PATH="$HOME/.nvm/versions/node/v24.18.0/bin:$PATH"
cd ~/Code/wiki-plugins/wiki-plugin-hitchhiker
npm install            # installs open-graph-scraper + @extractus/oembed-extractor

There is no build step — client/wiki-ux.js is plain hand-written JS served as-is.

Operational notes

• The server/ component and its deps must be present or the v24 pages scan can crash on a symlinked dev plugin — always npm install (Node v24) after a fresh clone or after update-wiki.
• server.js is ESM (matches wiki-plugin-similarity; loads via import() on the v24 farm). An ESM server silently 404s on older wiki-server that uses require() + Node < 22.12 — revisit for portability before publishing to an older/public farm.
• Wired into the farm via ~/bin/wiki-start (LOCAL_PLUGINS symlink + wiki-deps entry). server.js registers at startup, so restart the farm after changing it.
• Dev caching: the local wiki-server staticPathOptions is patched to maxAge:0, and the security bootstrap appends ?v=<ts> to wiki-ux.js on *.localhost, so edits appear on a normal reload. update-wiki reverts the maxAge patch.

Related

• wiki-security-hitchhiker — the friends-fork that bootstraps wiki-ux.js (to be replaced by an own-identity / trust-graph security module).
• wiki-plugin-similarity — sibling plugin whose ESM server pattern this mirrors; also powers the Similarity tool.