wiki-plugin-termflow

A generic workflow-gating plugin for Federated Wiki. A page often lists steps that must happen in order — install a tool before you configure it. TermFlow turns those steps into a guided workflow: later steps stay locked (shown as a plain, un-runnable item) until their prerequisite is met, and the whole page can be run as one guarded step-through.

It is the companion to wiki-plugin-terminal: Terminal supplies the runnable steps and the shell that evaluates guards; TermFlow orders and gates them. The engine is generic, so other item types can participate by registering an adapter (see below).

The item

A termflow item's text is one runnable bash script — the single source of truth. A preamble holds a # ── guards ── block of bash functions; one block per step follows, keyed to the source item's id, with an optional guard:

#!/usr/bin/env bash
# wiki-workflow: Codex

# ── guards ──
have_codex() { command -v codex >/dev/null 2>&1; }

# ── step 7d0192ae… ──
brew install codex

# ── step 9bc9a58f… needs: have_codex ──
if have_codex; then
  codex --version && which codex
fi

• needs: <fn> names a guard function. A step is unlocked iff the function exits 0 — the same function gates the step in the page and guards it when the script is run standalone.
• tty marks an interactive step; the step-through pauses for it rather than running it non-interactively.
• Press generate to (re)build the script from the page's runnable items, run workflow to step through honouring guards, copy to take the script.

The engine contract

TermFlow exposes registries on window.workflow; participant plugins register adapters (idempotently, at load):

| Registry | Signature | Purpose | |---|---|---| | evaluators[kind] | (expr, ctx) => Promise<bool> | evaluate a guard; ships shell, done | | runners[type] | (ctx) => Promise<{ok,exit,output}> | run a step of an item type | | scriptOf[type] | (item) => string | extract a step's body for generate | | setLock/getLock | (pageKey, id[, state]) | lock dispatch (fires a workflow-lock event) |

wiki-plugin-terminal registers runners.terminal, scriptOf.terminal, and listens for workflow-lock to render its locked state.

Build

npm install
npm run build      # runs tests, then bundles src/client → client/termflow.js

Local-first only: the live engine activates on localhost/.localhost hosts, or on a page served by the local mirror farm (the wiki-security-author client sets window.isLocalMirror), where the terminal service is reachable; elsewhere the item is display-only. On an https mirror page the service base follows the page protocol (https://terminal.localhost / wss://) to avoid mixed-content blocking.