wiki-plugin-pod 1.0.0 → 1.2.2

package/src/pod/commands.js

@@ -2,13 +2,14 @@
 //
 // This module is the single source for what a pod item's text may say. The
 // client imports it to parse item text; the plugin's API declaration names it so
-// the farm reads the identical table. There is no second copy to drift, which is
-// the same move that put the plugin's thinking in a module and left only the
-// serving in its server.
+// the farm reads the identical table. There is no second copy to drift.
 //
-// The item text convention is fedwiki-wide: UPPERCASE first word is a command,
-// lowercase is data, and a single trailing colon is optional. See the Fedwiki
-// DSL Skill.
+// The PARSER is not here, and neither is an import of it. The FARM loads this
+// module server-side to read the table, so it must be data and nothing else —
+// an import of @fortyfoxes/wiki-dsl here would need that package installed on
+// every farm, and a vocabulary that fails to load is dropped from the farm's
+// merged document entirely. The parser is bound in ./vocabulary.js, which only
+// the browser and the tests load.
 //
 // A DSL is a superset of an API, never a mirror of one — so every command
 // declares which KIND it is, and only some kinds cross to HTTP:
@@ -33,11 +34,16 @@ export const FALLBACK = ['sisters']
 
 export const COMMANDS = {
   // ---- parameter: these become values of the `kinds` parameter -------------
+  //
+  // `heading` is what the drawn group is called. `{site}` is the site the item
+  // is on, because that is what a pod is relative to and the one thing a reader
+  // landing cold cannot work out.
   SISTERS: {
     kind: 'parameter',
     parameter: 'kinds',
     value: 'sisters',
     label: 'Sisters',
+    heading: 'Sisters of {site}',
     description: 'sibling sites sharing the parent domain',
   },
   PARENT: {
@@ -45,6 +51,7 @@ export const COMMANDS = {
     parameter: 'kinds',
     value: 'parent',
     label: 'Parent',
+    heading: 'Parent of {site}',
     description: 'the parent-domain site itself',
   },
   CHILDREN: {
@@ -52,6 +59,7 @@ export const COMMANDS = {
     parameter: 'kinds',
     value: 'children',
     label: 'Children',
+    heading: 'Children of {site}',
     description: 'direct sub-domains of this site',
   },
   DESCENDANTS: {
@@ -59,6 +67,7 @@ export const COMMANDS = {
     parameter: 'kinds',
     value: 'descendants',
     label: 'Descendants',
+    heading: 'Descendants of {site}',
     description: 'all sub-domains, any depth',
   },
   FARM: {
@@ -66,6 +75,7 @@ export const COMMANDS = {
     parameter: 'kinds',
     value: 'farm',
     label: 'Farm',
+    heading: 'The rest of the farm',
     description: 'every wiki in the farm',
   },
 
@@ -81,6 +91,7 @@ export const COMMANDS = {
     kind: 'client-data',
     value: 'neighbourhood',
     label: 'Neighbourhood',
+    heading: 'Your neighbourhood',
     description: 'the sites currently in your neighborhood',
     why: 'reads the neighbourhood the browser has already assembled, which no server can see',
   },
@@ -89,113 +100,49 @@ export const COMMANDS = {
     kind: 'client-data',
     value: 'snapshot',
     label: 'Snapshot',
+    heading: 'Your neighbourhood',
     description: 'freeze the current neighborhood',
     why: 'same browser-only source as NEIGHBOURHOOD',
   },
-  TWIN: {
-    kind: 'client-data',
-    description: "show only members holding a page with this page's slug",
-    why: "matches against each neighbour's own sitemap, fetched from the browser",
-  },
-  WATCH: {
-    kind: 'client-data',
-    description: 'stricter TWIN — only members whose copy is a fork of this page',
-    why: "reads each candidate's page journal, one fetch per neighbour, from the browser",
-  },
 
   // ---- presentation: never leaves the client -------------------------------
-  ROSTER: {
+  //
+  // FORCE is a behaviour switch rather than a drawing choice, but `presentation`
+  // is the closest of the kinds the farm's vocabulary check accepts, and the
+  // thing that matters is true of it: it never crosses to a server.
+  FORCE: {
     kind: 'presentation',
-    description: 'draw the gather compactly, mirroring a normal roster item',
+    argument: 'yes|no',
+    default: false,
+    description: 'register the gathered sites as neighbours when the page loads',
   },
   TITLE: {
     kind: 'presentation',
     argument: 'yes|no',
     default: true,
-    description: 'whether the ROSTER title shows',
+    description: 'whether each group shows its heading',
   },
-}
-
-/** Values a trailing TITLE argument may take to mean "no". */
-const FALSEY = ['no', 'false', 'off', '0', 'hide', 'none']
-
-/** Follow an alias to the command it spells. */
-export const resolve = name => {
-  const entry = COMMANDS[name]
-  return entry && entry.kind === 'alias' ? COMMANDS[entry.alias] : entry
-}
-
-/** The canonical name a command resolves to, for reporting. */
-export const canonical = name => {
-  const entry = COMMANDS[name]
-  return entry && entry.kind === 'alias' ? entry.alias : name
-}
-
-/**
- * The keyword a line begins with, normalised. UPPERCASE is canonical but input
- * case is forgiven, and one trailing colon is optional — never required.
- */
-export const keywordOf = line =>
-  String(line || '')
-    .trim()
-    .split(/\s+/)[0]
-    .replace(/:$/, '')
-    .toUpperCase()
-
-/** Every value a parameter may take, in declaration order. The API's enum. */
-export const valuesFor = parameter =>
-  Object.values(COMMANDS)
-    .filter(c => c.kind === 'parameter' && c.parameter === parameter && c.value)
-    .map(c => c.value)
 
-/** Kinds gathered in the browser rather than asked of a server. */
-export const clientValues = () =>
-  Object.values(COMMANDS)
-    .filter(c => c.kind === 'client-data' && c.value)
-    .map(c => c.value)
-
-/** Display names, derived so a label is written once beside its command. */
-export const labels = () => {
-  const out = {}
-  for (const c of Object.values(COMMANDS)) if (c.value && c.label) out[c.value] = c.label
-  return out
-}
-
-/**
- * Item text to an ordered, de-duplicated list of gathered kinds.
- *
- * Macros expand in place, aliases resolve, unrecognised lines are ignored as
- * data rather than treated as an error. Default when nothing is recognised:
- * sisters.
- */
-export const parseKinds = (text, { fallback = ['sisters'] } = {}) => {
-  const kinds = []
-  const take = name => {
-    const entry = resolve(name)
-    if (!entry) return
-    if (entry.kind === 'macro') return entry.expands.forEach(take)
-    if (!entry.value) return
-    if (!kinds.includes(entry.value)) kinds.push(entry.value)
-  }
-  for (const line of String(text || '').split('\n')) {
-    if (!line.trim()) continue
-    take(keywordOf(line))
-  }
-  return kinds.length ? kinds : [...fallback]
-}
-
-/** Whether a bare command appears on a line of its own. */
-export const hasCommand = (text, name) =>
-  String(text || '')
-    .split('\n')
-    .some(line => canonical(keywordOf(line)) === name)
-
-/** TITLE yes|no — shown unless explicitly turned off. */
-export const parseTitle = text => {
-  for (const raw of String(text || '').split('\n')) {
-    const parts = raw.trim().split(/\s+/)
-    if (canonical(keywordOf(raw)) !== 'TITLE') continue
-    return !FALSEY.includes((parts[1] || '').toLowerCase().replace(/:$/, ''))
-  }
-  return COMMANDS.TITLE.default
+  // ---- retired: kept so pages that say them still parse ---------------------
+  //
+  // A word removed from this table is a word the parser reports as a mistake, so
+  // retiring one by deleting it would put a false "not a pod command" warning on
+  // every page that still says it. These stay, as presentation (the kind the
+  // farm's check allows for a word that never crosses), carrying what became of
+  // them.
+  ROSTER: {
+    kind: 'presentation',
+    retired: 'the default — every pod is drawn as a roster of flags',
+    description: 'no longer needed: rosters are how a pod is drawn',
+  },
+  TWIN: {
+    kind: 'presentation',
+    retired: 'wiki-plugin-twin',
+    description: 'moved: which pod members hold a page with this page’s slug',
+  },
+  WATCH: {
+    kind: 'presentation',
+    retired: 'wiki-plugin-twin',
+    description: 'moved: which pod members have forked this page',
+  },
 }

package/src/pod/kinship.js

@@ -0,0 +1,39 @@
+// kinship.js — who stands as pod to whom, as arithmetic on names.
+//
+// Kinship needs no disk: given the names a farm holds, every pod is a predicate
+// over strings. So selection lives here, imported by both readers — the browser,
+// which asks the farm only what sites exist, and the API handler, which answers
+// server-side for an agent that cannot run our client. That is why the plugin's
+// server shrank to one directory read and no opinions.
+
+/** The domain a site hangs from — '' for a farm root such as `localhost`. */
+export const parentOf = origin => origin.split('.').slice(1).join('.')
+
+/** Every pod, as predicates over site names, relative to the site asking. */
+export const selectorsFor = origin => {
+  const parentDomain = parentOf(origin)
+  const domainOf = name => name.split('.').slice(1).join('.')
+  return {
+    sisters: name => name !== origin && domainOf(name) === parentDomain,
+    parent: name => parentDomain !== '' && name === parentDomain,
+    children: name => domainOf(name) === origin,
+    descendants: name => name !== origin && name.endsWith('.' + origin),
+    farm: name => name !== origin,
+  }
+}
+
+/**
+ * Sort site names into the requested pods — names in, names out. Unknown kinds
+ * are dropped rather than refused, the same forgiveness the item text shows.
+ * Every pod is a neighbourhood, so the asker is never among its own results.
+ */
+export const gather = (sites, { origin, kinds }) => {
+  const selectors = selectorsFor(origin)
+  const wanted = (Array.isArray(kinds) ? kinds : String(kinds || 'sisters').split(','))
+    .map(k => String(k).trim())
+    .filter(k => selectors[k])
+
+  const groups = {}
+  for (const kind of wanted) groups[kind] = sites.filter(selectors[kind]).sort((a, b) => a.localeCompare(b))
+  return groups
+}

package/src/pod/roll.js

@@ -1,81 +1,50 @@
-// roll.js — what the pod plugin knows how to do, as plain functions.
+// roll.js — the one thing kinship cannot work out for itself: what is here.
 //
-// No request, no response, no argv, nothing from a web framework. Everything it
-// needs arrives as ordinary values, so the same function answers the plugin's
-// own route and the farm's mounted operation without either knowing about the
-// other. Lifted out of server/server.js unchanged; that file is now a thin
-// caller of this one.
+// Node-only, never imported by the client. The selectors, the sorting and the
+// page counts have all left: selection moved to ../pod/kinship.js, and the
+// counts went away because the client never read them — it takes them from each
+// neighbour's own sitemap, so the farm was reading a directory per site on
+// every render for nothing.
 //
-// Node-only (it reads the farm directory), and deliberately NOT imported by the
-// client — the client shares only the vocabulary in ./commands.js.
+// A directory is a wiki when it holds pages — the same test wiki-plugin-farm
+// and wiki-plugin-hitchhiker use. This plugin used to test for
+// `status/sitemap.json`, which is written on first view rather than on
+// creation, so a farm's newest sites were invisible to it alone.
 
 import fs from 'node:fs/promises'
 import path from 'node:path'
 
-/** Every pod this module can gather, as predicates over farm directory names. */
-export const selectorsFor = ({ origin, parentDomain }) => {
-  const domainOf = name => name.split('.').slice(1).join('.')
-  return {
-    sisters: name => name !== origin && domainOf(name) === parentDomain,
-    parent: name => parentDomain !== '' && name === parentDomain,
-    children: name => domainOf(name) === origin,
-    descendants: name => name !== origin && name.endsWith('.' + origin),
-    farm: name => name !== origin,
-  }
-}
-
-/** A directory is a wiki when it carries a readable sitemap. */
-const isWiki = (farmRoot, name) =>
-  fs
-    .access(path.join(farmRoot, name, 'status', 'sitemap.json'), fs.constants.R_OK)
-    .then(() => true)
-    .catch(() => false)
-
-const pageCount = (farmRoot, name) =>
-  fs
-    .readdir(path.join(farmRoot, name, 'pages'))
-    .then(entries => entries.length)
-    .catch(() => 0)
-
-/** The parent domain of a site name — '' for a farm root such as `localhost`. */
-export const parentOf = origin => origin.split('.').slice(1).join('.')
-
-/**
- * Gather the requested pods of the site being asked.
- *
- * `origin` and `farmRoot` are the context: the answer genuinely depends on WHERE
- * the question was asked, which is why they are arguments rather than something
- * this module reaches for. Unknown kinds are dropped rather than refused, and
- * the default is sisters — the same forgiveness the item text shows.
- */
-export const roll = async ({ kinds, origin, farmRoot }) => {
-  const parentDomain = parentOf(origin)
-  const selectors = selectorsFor({ origin, parentDomain })
-
-  const wanted = (Array.isArray(kinds) ? kinds : String(kinds || 'sisters').split(','))
-    .map(k => String(k).trim())
-    .filter(k => selectors[k])
+import { gather, parentOf } from './kinship.js'
 
+/** The sites of this farm — every directory holding pages. */
+export const sitesOf = async farmRoot => {
   let entries
   try {
     entries = await fs.readdir(farmRoot, { withFileTypes: true })
   } catch {
-    return { origin, parentDomain, groups: {} }
+    return []
   }
-
   const dirs = entries.filter(e => e.isDirectory()).map(e => e.name)
-  const flags = await Promise.all(dirs.map(name => isWiki(farmRoot, name)))
-  const wikis = dirs.filter((_, i) => flags[i])
+  const holdsPages = await Promise.all(
+    dirs.map(name =>
+      fs
+        .access(path.join(farmRoot, name, 'pages'), fs.constants.R_OK)
+        .then(() => true)
+        .catch(() => false),
+    ),
+  )
+  return dirs.filter((_, i) => holdsPages[i]).sort()
+}
 
-  const groups = {}
-  for (const kind of wanted) {
-    const names = wikis.filter(selectors[kind])
-    const group = await Promise.all(
-      names.map(async name => ({ site: name, pages: await pageCount(farmRoot, name) })),
-    )
-    group.sort((a, b) => a.site.localeCompare(b.site))
-    groups[kind] = group
-  }
+/**
+ * Gather the requested pods of the site being asked. `origin` and `farmRoot` are
+ * context: the answer depends on WHERE the question was put, which is why they
+ * are arguments rather than something this module reaches for.
+ */
+export const roll = async ({ kinds, origin, farmRoot }) => ({
+  origin,
+  parentDomain: parentOf(origin),
+  groups: gather(await sitesOf(farmRoot), { origin, kinds }),
+})
 
-  return { origin, parentDomain, groups }
-}
+export { parentOf }

package/src/pod/vocabulary.js

@@ -0,0 +1,20 @@
+// vocabulary.js — the table, read.
+//
+// ./commands.js is data with no imports, because the farm loads it server-side
+// and a vocabulary that cannot be imported is dropped from the farm's document.
+// Everything that READS that table lives here instead: @fortyfoxes/wiki-dsl,
+// bundled into the client at build time and shared with every other plugin whose
+// item text is a small language.
+
+import { dsl } from '@fortyfoxes/wiki-dsl'
+
+import { COMMANDS, FALLBACK } from './commands.js'
+
+export const { parseKinds, hasCommand, argumentOf, problems, valuesFor, fieldByValue, canonical, resolve, suggest } =
+  dsl(COMMANDS, { fallback: FALLBACK })
+
+/** What a retired command became, or undefined for a live one. */
+export const retirementOf = word => COMMANDS[word]?.retired
+
+export { COMMANDS, FALLBACK }
+export { VOCABULARY_VERSION, ITEM_TYPE } from './commands.js'

package/server/package.json

@@ -1,3 +0,0 @@
-{
-  "type": "commonjs"
-}

package/server/server.js

@@ -1,47 +0,0 @@
-// pod plugin — server-side component.
-//
-// A thin caller now. Everything it used to know how to do lives in
-// ../src/pod/roll.js as plain functions; this file only turns a request into
-// arguments and a result into JSON. The route it serves is unchanged, so the
-// shipped client keeps calling the address it always called — the migration
-// adds a second way in without disturbing the first.
-//
-// Started on the `running-serv` event with { argv, app }.
-//
-// NOTE: authored as CommonJS on purpose. wiki-server loads a plugin's
-// server/server.js with require() (older releases) or import() (newer); CJS
-// is the only format that works under BOTH, on every Node version. An ESM
-// server.js throws ERR_REQUIRE_ESM on the require() loader (Node < 22.12),
-// and the wiki swallows that error, so the plugin's routes silently vanish.
-// The sibling server/package.json ({"type":"commonjs"}) makes Node treat this
-// file as CJS even though the plugin's root package.json is "type":"module",
-// so the rest of the plugin (src/, tests, build) can stay ESM.
-//
-// The shared module is ESM, and is reached by dynamic import() rather than
-// require(). Dynamic import works from CommonJS on every Node that runs the
-// wiki, while require() of an ES module only works from Node 22.12 — so this is
-// the one form that needs no version to be true.
-
-const path = require('node:path')
-
-const startServer = ({ argv, app }) => {
-  // argv.status = {farmRoot}/{thisDomain}/status
-  const farmRoot = path.dirname(path.dirname(argv.status))
-  const origin = path.basename(path.dirname(argv.status)) // e.g. demoscene.localhost
-
-  // Imported once, awaited per request. Kept as the promise so a slow or failed
-  // load cannot delay the route being registered.
-  const thinking = import('../src/pod/roll.js')
-
-  app.get('/plugin/pod/roll', async (req, res) => {
-    try {
-      const { roll } = await thinking
-      res.json(await roll({ kinds: req.query.kinds || 'sisters', origin, farmRoot }))
-    } catch (e) {
-      console.log('pod plugin: roll failed —', e?.stack || e)
-      res.status(500).json({ error: e.message })
-    }
-  })
-}
-
-module.exports = { startServer }