wiki-plugin-pod 1.0.0 → 1.2.3

package/src/client/pod.js

@@ -1,326 +1,172 @@
 // wiki-plugin-pod — gather configurable pods of related wiki sites.
 //
-// Augments the Present plugin: instead of only listing sister sites, the item
-// text is a list of keywords choosing WHICH pods of sites to gather and
-// show. Each gathered site is registered as a neighbor so its pages join your
-// search and lineage. Reads the in-browser neighbourhood for the client-side
-// pods, and a small server route for the disk-derived ones.
+// The item text chooses WHICH pods of sites to gather — sisters, parent,
+// children, descendants, the farm, the neighbourhood — and draws them as a
+// roster of flags. Say FORCE and the gathered sites also join your neighbourhood
+// on load, so their pages join your search and lineage; without it the roster's
+// own » does that when you ask, which is how any other roster behaves.
 //
-// Recognised keywords (one per line, in item.text):
-//   sisters        sibling sites sharing the parent domain   (server)
-//   parent         the parent-domain site itself             (server)
-//   children       direct sub-domains of this site           (server)
-//   descendants    all sub-domains, any depth                (server)
-//   farm           every wiki in the farm                    (server)
-//   neighbourhood  the sites currently in your neighborhood  (client)
-//   snapshot       freeze the current neighborhood           (client, v0.1 == neighbourhood)
+// The commands an author may write are NOT listed here. They live in
+// ../pod/commands.js, which the plugin's API declaration also names, so what an
+// author may type and what the mounted operation accepts come from one table.
+// Restating that table in a comment is how the two drift apart; read the table.
 //
-// Actions (not site-kinds):
-//   ROSTER         draw the gathered pod compactly, mirroring a normal roster
-//                  item — a left-aligned "<commands> Rosters" title over flowing
-//                  `img.remote` flags in the grey box, instead of the wide
-//                  tables. A ❄ corner icon saves it as a roster ghost page.
-//   TITLE yes|no   whether the ROSTER title shows (default yes). TITLE no hides
-//                  it, leaving even padding around the flags.
-//   TWIN           show a roster of the pod members that hold a page with
-//                  THIS page's slug — existence-only, exactly like the
-//                  wiki-client Twins strip: a slug match in the neighbour's
-//                  sitemap, no journal or lineage check.
-//   WATCH          stricter TWIN: show only the members whose copy is actually a
-//                  fork of this page — its journal carries a `fork` event — i.e.
-//                  who is watching (tracking) your page. Fetches each candidate.
+// Where each pod comes from: this plugin ships NO server. It declares a
+// specification and a module of plain functions (api/, src/pod/), and the Farm
+// Plugin mounts them — so the disk-derived pods are read from that mount,
+// /system/api/pod/roll.json, the same address an agent uses. NEIGHBOURHOOD and
+// SNAPSHOT never leave the browser at all, being the neighbourhood the client
+// has already assembled.
 //
-// TWIN and WATCH render like a roster item (flowing flags, the (sub)domain in the
-// hover tooltip); each flag links to that member's copy of the page. ROSTER is
-// the same compact style for the whole (unfiltered) gather. The wider table (no
-// display command) carries a small ❄ icon that saves the roster page too, so
-// there is no separate FREEZE command.
-
-// The vocabulary is not defined here. It lives in ../pod/commands.js, which
-// the plugin's API declaration also names — so what an author may type and what
-// the mounted operation accepts come from one table and cannot drift apart.
-import { valuesFor, clientValues, labels, parseKinds, hasCommand, parseTitle } from '../pod/commands.js'
+// How it draws: it doesn't. A gather IS a roster — a heading over the members'
+// flags — and wiki-plugin-roster already draws one, on every wiki there is. So
+// pod builds the roster text and hands it to that plugin. The text it builds is
+// also exactly what the ❄ icon saves as a page, so the drawn thing and the saved
+// thing are one string rather than two code paths that must agree.
+import { valuesFor, fieldByValue, parseKinds, problems, hasCommand, argumentOf, retirementOf } from '../pod/vocabulary.js'
 
 const SERVER_KINDS = valuesFor('kinds')
-const CLIENT_KINDS = clientValues()
-const LABEL = labels()
+const HEADING = fieldByValue('heading')
 
-const expand = text =>
+const escapeHtml = text =>
   (text || '')
     .replace(/&/g, '&amp;')
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
-    .replace(/\*(.+?)\*/g, '<i>$1</i>')
-
-const elapsed = ms => {
-  const s = Math.floor(ms / 1000)
-  const f = 1.9
-  let out = 'a minute ago'
-  if (s > f * 60) out = `${Math.round(s / 60)} minutes ago`
-  if (s > f * 3600) out = `${Math.round(s / 3600)} hours ago`
-  if (s > f * 86400) out = `${Math.round(s / 86400)} days ago`
-  if (s > f * 604800) out = `${Math.round(s / 604800)} weeks ago`
-  if (s > f * 2592000) out = `${Math.round(s / 2592000)} months ago`
-  if (s > f * 31536000) out = `${Math.round(s / 31536000)} years ago`
-  return out
-}
 
-const freshness = sitemap => {
-  if (!sitemap) return ''
-  const dates = sitemap.map(p => p.date).filter(d => typeof d === 'number')
-  return dates.length ? elapsed(Date.now() - Math.max(...dates)) : ''
+// A mistyped command (CHIKDREN for CHILDREN) is parsed as data, so the item
+// falls back to sisters and draws a pod nobody asked for. Say so above the
+// gather, since nothing else on the panel would show a trace of it.
+const problemsHtml = found =>
+  found.length
+    ? `<p class=pod-problem style="color:#a00;font-size:80%;text-align:center;margin:0 0 6px">` +
+      found
+        .map(p =>
+          p.suggestion
+            ? `${escapeHtml(p.word)} — did you mean <b>${p.suggestion}</b>?`
+            : `${escapeHtml(p.word)} — not a pod command`,
+        )
+        .join('<br>') +
+      `</p>`
+    : ''
+
+// A command that has moved says where it went, rather than silently doing
+// nothing on a page that still asks for it.
+const retiredHtml = text => {
+  const moved = ['TWIN', 'WATCH', 'ROSTER']
+    .filter(word => hasCommand(text, word))
+    .map(word => [word, retirementOf(word)])
+  return moved.length
+    ? `<p class=pod-retired style="color:#666;font-size:80%;text-align:center;margin:0 0 6px">` +
+      moved.map(([word, became]) => `${word} — now ${escapeHtml(became)}`).join('<br>') +
+      `</p>`
+    : ''
 }
 
 const portSuffix = () => ([80, '80', '', null].includes(location.port) ? '' : `:${location.port}`)
 
-// parseKinds, hasCommand and parseTitle come from the shared vocabulary above.
-// ROSTER, TWIN and WATCH are bare keywords on their own line, so they never
-// pollute the gathered kinds: ROSTER draws the whole gather compactly (with a
-// button to save it as a roster page); TWIN and WATCH switch the panel to a
-// roster of the pod members that hold this page (TWIN by slug, WATCH by an
-// actual fork event in the copy's journal).
-const hasAction = hasCommand
-
-// Display name for a site row. Descendants of the viewing site keep their
-// whole relative name (david.pod.peoplepowered.money seen from
-// peoplepowered.money → "david.pod"); everything else shows its first label.
-const shortName = site =>
-  site.endsWith('.' + location.hostname)
-    ? site.slice(0, -(location.hostname.length + 1))
-    : site.split('.')[0]
-
-const rowHtml = (site, pages, sitemap) => {
-  const suffix = portSuffix()
-  const short = shortName(site)
-  const img =
-    `<img class=remote title="${site}${suffix}" src="//${site}${suffix}/favicon.png" ` +
-    `data-site="${site}${suffix}" data-slug=welcome-visitors>`
-  return (
-    `<tr><td align=right>${short} ${img}` +
-    `<td data-site="${site}${suffix}">${pages} pages ${freshness(sitemap)}`
-  )
-}
-
-const groupHtml = (kind, rows) =>
-  `<p class=caption><b>${LABEL[kind]}</b></p>` +
-  `<table width=100% class=pod-${kind}>${rows.join('\n')}</table>`
-
 export const emit = (div, item) => {
   const suffix = portSuffix()
   const kinds = parseKinds(item.text)
-  const watch = hasAction(item.text, 'WATCH')
-  const twin = hasAction(item.text, 'TWIN')
-  const roster = watch || twin // both render as a (filtered) roster of member flags
-  const rosterCmd = hasAction(item.text, 'ROSTER') // compact display of the whole gather
-  const showTitle = parseTitle(item.text) // TITLE yes/no — show the ROSTER title
-  // Title for the ROSTER caption and the saved roster page — the commands
-  // present, e.g. "SISTERS Rosters" / "PARENT SISTERS Rosters".
-  const rostersTitle = `${kinds.map(k => k.toUpperCase()).join(' ')} Rosters`
-  // slug of the page hosting this item — what TWIN/WATCH match against, the way
-  // Twins matches the viewing page's slug across the neighbourhood. The page
-  // div's id IS the slug (possibly with a _rev… suffix on a historical view);
-  // .data('key') is the lineup key, NOT the slug, so don't use it here.
-  const slug = (div.closest('.page').attr('id') || '').split('_rev')[0]
-  // gathered pod, captured during render so saveRosters() can reuse it:
-  // kind -> ordered list of full domain names
-  const gathered = {}
-
-  // TWIN test — existence-only: does this neighbour's already-loaded sitemap hold
-  // a page with our slug? (Twins' inner test — no journal, no lineage.)
-  const hasTwin = key => {
-    const sm = wiki.neighborhood[key]?.sitemap
-    return Array.isArray(sm) && sm.some(p => p.slug === slug)
-  }
-
-  // WATCH test — is this member watching us: their copy of this page carries a
-  // `fork` event in its journal (fedwiki's term for a copy taken from ours).
-  // Needs the page JSON, so results are fetched lazily and cached (true/false
-  // once resolved, `in` even while the request is in flight). We only fetch where
-  // the sitemap already shows the slug, so it costs one request per actual twin.
-  const watchStatus = {}
-  const ensureWatchChecked = (key, onDone) => {
-    if (key in watchStatus || !hasTwin(key)) return
-    watchStatus[key] = undefined // in-flight marker
-    wiki.site(key).get(`${slug}.json`, (err, page) => {
-      watchStatus[key] =
-        !err && Array.isArray(page?.journal) && page.journal.some(a => a?.type === 'fork')
-      onDone()
-    })
-  }
-  const matches = key => (watch ? watchStatus[key] === true : hasTwin(key))
+  const showHeadings = argumentOf(item.text, 'TITLE')
+  const force = argumentOf(item.text, 'FORCE')
+  const notes = problemsHtml(problems(item.text)) + retiredHtml(item.text)
 
   if (div.closest('.page').hasClass('remote')) {
     div.html(
-      `<div class=pod style="background-color:#eee;padding:15px"><center>${expand(item.text)}` +
+      `<div class=pod style="background-color:#eee;padding:15px"><center>` +
       `<p class=caption>Pod is only available when viewed on a page's home wiki.</p></div>`,
     )
     return
   }
 
-  // The flag-display modes (ROSTER / TWIN / WATCH) carry their own caption, so
-  // skip echoing the raw command text; the table keeps its echo. ROSTER also
-  // drops the centred `.caption` line entirely — it renders its own left-aligned
-  // title inside `.groups`, mirroring a roster item, so the box padding stays
-  // even (important when TITLE is off).
-  const echo = roster || rosterCmd ? '' : `<center>${expand(item.text)}`
-  const status = rosterCmd ? '' : `<p class=caption>gathering…</p>`
-  div.html(
-    `<div class=pod style="position:relative;background-color:#eee;padding:15px">${echo}` +
-    `${status}<div class=groups>${rosterCmd ? '<i>gathering…</i>' : ''}</div></div>`,
-  )
-
-  const render = serverGroups => {
-    // Candidate pod members per kind, as neighbourhood lookup keys (with the
-    // port suffix). Server kinds are registered once here so their sitemaps load;
-    // TWIN/WATCH later filter these candidates down to the matching members.
-    const candidates = {}
-    for (const kind of kinds) {
-      if (SERVER_KINDS.includes(kind)) {
-        const roll = serverGroups[kind] || []
-        gathered[kind] = roll.map(r => r.site)
-        candidates[kind] = roll.map(r => r.site + suffix)
-        for (const key of candidates[kind]) wiki.neighborhoodObject.registerNeighbor(key)
-      } else {
-        // neighbourhood / snapshot — read the live in-browser neighbourhood
-        const sites = Object.keys(wiki.neighborhood)
-        gathered[kind] = sites
-        candidates[kind] = sites
-      }
-    }
-
-    // TWIN / WATCH render like a roster item: the matching members' flags flowing
-    // inline, deduplicated across kinds, each linking to that member's copy of
-    // THIS page. No titles are shown (every copy is the same page) — the
-    // (sub)domain lives in the hover tooltip. Sitemaps (and, for WATCH, the
-    // fetched page journals) arrive asynchronously, so this is re-run as they
-    // resolve, which is when matches reveal themselves.
-    const buildRoster = () => {
-      const seen = new Set()
-      const flags = []
+  div.html(`${notes}<div class=pod-gather><p class=caption>gathering…</p></div>`)
+
+  // The roster text: a heading, a BLANK LINE, then one domain per line, and a
+  // blank line again between groups. That is wiki-plugin-roster's own markup —
+  // categories are the lines that are not domains, and a blank line starts a new
+  // display line, which is what puts the heading on a line of its own with the
+  // flags in a row beneath it. Without the blank line roster runs them together:
+  // "Sisters of demo.localhost [flag] [flag]" on one line.
+  //
+  // This same string draws the item and, saved, becomes an ordinary roster item
+  // on a page any wiki can read.
+  const rosterText = (groups, origin) =>
+    kinds
+      .map(kind => {
+        const sites = groups[kind] || []
+        if (!sites.length) return ''
+        const heading = showHeadings ? (HEADING[kind] || kind).replace('{site}', origin) + '\n\n' : ''
+        return heading + sites.join('\n')
+      })
+      .filter(Boolean)
+      .join('\n\n')
+
+  const render = (groups, origin) => {
+    // FORCE — register the gathered sites as neighbours, so their pages join
+    // your search and lineage. Off by default: a pod is a roster, and a roster
+    // does not reach into your neighbourhood unasked. The roster's own » does it
+    // on demand instead, and the flags are drawn either way — wiki.site().flag()
+    // never consults the neighbourhood.
+    if (force) {
       for (const kind of kinds) {
-        for (const key of candidates[kind]) {
-          if (watch) ensureWatchChecked(key, paint) // lazily confirm the fork event
-          if (seen.has(key) || !matches(key)) continue
-          seen.add(key)
-          flags.push(
-            `<img class="remote" src="${wiki.site(key).flag()}" ` +
-            `title="${key}" data-site="${key}" data-slug="${slug}">`,
-          )
-        }
+        if (!SERVER_KINDS.includes(kind)) continue
+        for (const site of groups[kind] || []) wiki.neighborhoodObject.registerNeighbor(site + suffix)
       }
-      return flags
     }
 
-    // ROSTER — the whole gather as one compact roster: a single "<commands>
-    // Rosters" caption (the panel's own .caption) over all members' flags. The
-    // markup mirrors the wiki-plugin-roster item exactly: space-separated
-    // `img.remote` flags in the panel's grey box — no extra wrapper — each
-    // linking to that member's welcome page. The ❄ icon saves it as a page.
-    const buildRosterDisplay = () => {
-      const seen = new Set()
-      const flags = []
-      for (const kind of kinds) {
-        for (const key of candidates[kind]) {
-          if (seen.has(key)) continue
-          seen.add(key)
-          flags.push(
-            `<img class="remote" src="${wiki.site(key).flag()}" ` +
-            `title="${key}" data-site="${key}" data-slug="welcome-visitors">`,
-          )
-        }
-      }
-      return flags.join(' ') || '<i>none</i>'
-    }
-
-    // Non-roster: the full pod tables (favicon + name + page count + freshness).
-    const buildGroups = () => {
-      const html = []
-      for (const kind of kinds) {
-        const rows = candidates[kind].map(key => {
-          const bare = suffix && key.endsWith(suffix) ? key.slice(0, -suffix.length) : key
-          const sm = wiki.neighborhood[key]?.sitemap
-          return rowHtml(bare, sm ? sm.length : 0, sm)
-        })
-        const empty = SERVER_KINDS.includes(kind) ? '<tr><td><i>none</i>' : '<tr><td><i>empty</i>'
-        html.push(groupHtml(kind, rows.length ? rows : [empty]))
-      }
-      return html.join('\n')
-    }
-
-    const paint = () => {
-      if (roster) {
-        // TWIN / WATCH — flat, filtered flags
-        const flags = buildRoster()
-        div.find('.groups').html(flags.join(' '))
-        div.find('.caption').first().text(
-          flags.length ? '' : watch ? 'no pod watchers yet' : 'no pod twins yet',
-        )
-        return
-      }
-      if (rosterCmd) {
-        // Mirror a roster item: an optional left-aligned title, then a <br>, then
-        // the flags — all in the panel's grey box. TITLE off → flags only, even
-        // padding all round.
-        const title = showTitle ? `${rostersTitle} <br> ` : ''
-        div.find('.groups').html(title + buildRosterDisplay())
-        return
-      }
-      div.find('.groups').html(buildGroups())
-      div.find('.caption').first().text('just updated')
-    }
-    paint()
-
-    // Save the gathered pod as a roster ghost page titled after the commands
-    // (e.g. "SISTERS Rosters"), one roster item per kind. No FREEZE command any
-    // more: it's reached from the ❄ icon tucked into the corner of the ROSTER
-    // and wide-table views.
-    const saveRosters = () => {
-      const hexId = () =>
-        Math.floor(Math.random() * 0xffffffffffff).toString(16).padStart(12, '0')
-      const story = [{ type: 'markdown', id: hexId(), text: `# ${rostersTitle}` }]
-      for (const kind of kinds) {
-        const domains = gathered[kind] || []
-        story.push({
-          type: 'roster',
-          id: hexId(),
-          text: `${LABEL[kind]} Wikis\n\n${domains.join('\n') || '(none)'}`,
-        })
-      }
-      const page = wiki.newPage({ title: rostersTitle, story })
-      wiki.showResult(page, { $page: div.parents('.page') })
-    }
-
-    // Freeze affordance — a subtle ❄ icon in the panel corner, on the ROSTER and
-    // the wide-table views (TWIN / WATCH are monitoring views, so they get none).
-    if (rosterCmd || !roster) {
+    const text = rosterText(groups, origin)
+    const target = div.find('.pod-gather')
+    target.empty()
+    if (!text) return target.html('<p class=caption><i>none</i></p>')
+
+    wiki.getPlugin('roster', roster => {
+      target.empty()
+      const rosterItem = { type: 'roster', id: `${item.id}-roster`, text }
+      roster.emit(target, rosterItem)
+      // bind() too, or the » roster draws beside each row — "add these N sites
+      // to neighborhood" — is inert markup. With FORCE off that link is the only
+      // way to take the pod into your neighbourhood, so it has to work.
+      //
+      // Its other binding is a dblclick opening a text editor on this synthetic
+      // roster item, which belongs to nothing and would edit a string we
+      // generated. Drop that one; pod binds its own dblclick, on the item, to
+      // edit the pod text an author actually wrote.
+      roster.bind(target, rosterItem)
+      target.off('dblclick')
+      // Freeze — the same text, saved as a real roster item on a new page.
       const icon = $(
-        '<span class=pod-freeze-icon title="Display Rosters — save as a roster page" ' +
+        '<span class=pod-freeze-icon title="Freeze — save this gather as a roster page" ' +
         'style="position:absolute;top:6px;right:9px;cursor:pointer;font-size:14px;opacity:.55">❄</span>',
       )
-      icon.on('click', saveRosters)
-      div.find('.pod').append(icon)
-    }
-
-    // As each neighbour's sitemap loads: in TWIN/WATCH mode repaint, since a match
-    // may have just appeared (a member whose sitemap now shows our slug — and for
-    // WATCH that also kicks off the journal fetch); otherwise just backfill that
-    // member's page-count / freshness cell.
-    $('body').on('new-neighbor-done', (e, site) => {
-      if (roster) return paint()
-      const cell = div.find(`td[data-site="${site}"]`)
-      if (!cell.length) return
-      const sm = wiki.neighborhood[site]?.sitemap
-      if (sm) cell.text(`${sm.length} pages ${freshness(sm)}`)
+      icon.on('click', () => {
+        const title = kinds.map(k => (HEADING[k] || k).replace('{site}', origin)).join(', ')
+        const page = wiki.newPage({
+          title,
+          story: [{ type: 'roster', id: Math.floor(Math.random() * 0xffffffffffff).toString(16).padStart(12, '0'), text }],
+        })
+        wiki.showResult(page, { $page: div.parents('.page') })
+      })
+      div.css('position', 'relative').append(icon)
     })
   }
 
+  // Only the disk-derived pods need asking; NEIGHBOURHOOD and SNAPSHOT are
+  // already in the browser.
+  const neighbourhood = () => Object.keys(wiki.neighborhood).map(key => (suffix && key.endsWith(suffix) ? key.slice(0, -suffix.length) : key))
+  const localGroups = () => {
+    const groups = {}
+    for (const kind of kinds) if (!SERVER_KINDS.includes(kind)) groups[kind] = neighbourhood()
+    return groups
+  }
+
   const serverKinds = kinds.filter(k => SERVER_KINDS.includes(k))
   if (serverKinds.length === 0) {
-    render({})
+    render(localGroups(), location.hostname)
     return
   }
 
-  fetch(`/plugin/pod/roll?kinds=${encodeURIComponent(serverKinds.join(','))}`)
+  fetch(`/system/api/pod/roll.json?kinds=${encodeURIComponent(serverKinds.join(','))}`)
     .then(res => {
       if (!res.ok) {
         const err = new Error(`HTTP ${res.status}`)
@@ -329,15 +175,15 @@ export const emit = (div, item) => {
       }
       return res.json()
     })
-    .then(data => render(data.groups || {}))
+    .then(data => render({ ...(data.groups || {}), ...localGroups() }, data.origin || location.hostname))
     .catch(err => {
-      // A 404 means the plugin's server component never registered its route —
-      // almost always an old wiki-server / Node combination that couldn't load
-      // server/server.js (see this plugin's server notes). Say so, rather than a
-      // generic error, so the operator knows where to look.
+      // A 404 means nothing is mounted at that address: this farm has no
+      // wiki-plugin-farm, or it has not been restarted since pod was installed.
+      // Name it, rather than saying "server error", so the operator knows what
+      // to install.
       const msg =
         err && err.status === 404
-          ? 'pod server not loaded — the host wiki may need a restart or a newer wiki-server / Node'
+          ? 'pod needs wiki-plugin-farm on this wiki to mount its API — install it and restart'
           : 'server error'
       div.find('.caption').first().text(msg)
     })