@lamalibre/create-lamaste 4.5.0 → 4.6.0

package/vendor/server/src/commands/plugins.js

@@ -59,6 +59,10 @@
  *                        Who holds which of its roles; give or take them away
  *   identity-sync <name> [--reconcile]
  *                        Sync its audience to its agent half now
+ *   web-surface <name> [create [--subdomain <s>] [--access-mode <m>] | move --tunnel <t> | delete [--yes]]
+ *                        The site an agent-hosted plugin owns for its web surface: what it
+ *                        declares, whether it is served, its trees; create, move a bound
+ *                        tunnel's host to it, delete it
  *
  * Every subcommand goes through the running panel (`/api/plugins/*`, admin
  * certificate): the panel owns the plugin registry (SQLite `state.db`), runs
@@ -77,6 +81,7 @@ import { panelRequest } from '../panel-api.js';
 import { emit, emitStep, emitError, emitComplete, emitLog } from '../ndjson.js';
 import { configureCmd, settingsCmd } from './plugin-settings.js';
 import { audienceCmd, entitlementsCmd, identityCmd, identitySyncCmd } from './plugin-identity.js';
+import { webSurfaceCmd } from './plugin-web-surface.js';
 import { settingsDiffLines, terminalText } from '../plugin-settings.js';
 import {
   APPROVE_HOOKS_USAGE,
@@ -85,6 +90,8 @@ import {
   identityDiffLines,
   parseApproveArgs,
   pendingUpdateReasons,
+  webSurfaceBlockLines,
+  webTreeDiffLines,
 } from '../plugin-approval.js';
 
 /** npm runs inside the panel for install and uninstall (its own limit is 120 s). */
@@ -152,6 +159,8 @@ export async function runPlugins(args, { json }) {
       return entitlementsCmd(args.slice(1), { json });
     case 'identity-sync':
       return identitySyncCmd(args.slice(1), { json });
+    case 'web-surface':
+      return webSurfaceCmd(args.slice(1), { json });
     default:
       printPluginUsage();
       process.exit(sub ? 1 : 0);
@@ -219,6 +228,14 @@ ${b('Subcommands:')}
                        Take every role away
   ${c('identity-sync <name> [--reconcile]')}
                        Sync its audience to its agent half now; --reconcile replays all of it
+  ${c('web-surface <name>')}   The site a plugin owns for its web surface: what it declares, its site,
+                       whether it is served (and why not), its trees, the bound tunnel, the offer
+  ${c('web-surface <name> create [--subdomain <label>] [--access-mode authenticated|restricted]')}
+                       Give it its site (default: the subdomain and access mode it declares)
+  ${c('web-surface <name> move --tunnel <id | subdomain | fqdn>')}
+                       Hand the host of the tunnel bound as its user surface to its site
+  ${c('web-surface <name> delete [--yes]')}
+                       Delete its site, its trees and the grants on it (typed confirmation)
 `);
 }
 
@@ -796,16 +813,25 @@ function printIdentityBlock(block, title) {
   for (const line of identityBlockLines(block)) console.log(`    ${line}`);
 }
 
+/**
+ * Print a web surface — the web tree an approval covers and the site
+ * Lamaste offers for it (the hook status's `web`).
+ */
+function printWebSurfaceBlock(web, title) {
+  console.log(chalk.bold(`  ${title}`));
+  for (const line of webSurfaceBlockLines(web)) console.log(`    ${line}`);
+}
+
 /**
  * Print what a version brings that needs approval — the approval digest
  * (what `approve-hooks` takes; none for an update that brings neither
- * relay hooks, nor an agent half Lamaste installs, nor an identity block),
- * its relay hook set, the agent half Lamaste installs and its identity
- * block.
+ * relay hooks, nor an agent half Lamaste installs, nor an identity block,
+ * nor a web surface), its relay hook set, the agent half Lamaste installs,
+ * its identity block and its web tree.
  */
-function printApprovalContents({ digest, relay, agentHalf, identity = null }) {
+function printApprovalContents({ digest, relay, agentHalf, identity = null, web = null }) {
   console.log(
-    `    approval digest: ${digest ? chalk.cyan(digest) : chalk.dim('none — no relay hooks, no agent half Lamaste installs, no identity block')}`,
+    `    approval digest: ${digest ? chalk.cyan(digest) : chalk.dim('none — no relay hooks, no agent half Lamaste installs, no identity block, no web surface')}`,
   );
   if (relay) {
     console.log('');
@@ -822,6 +848,27 @@ function printApprovalContents({ digest, relay, agentHalf, identity = null }) {
       'Identity — Lamaste sends its agent half the users entitled to these roles',
     );
   }
+  if (web?.declared) {
+    console.log('');
+    printWebSurfaceBlock(
+      web,
+      'Web surface — the relay serves this tree on the site the plugin owns',
+    );
+  }
+}
+
+/**
+ * Print how an update changes the plugin's web tree (part of the digest):
+ * the tree before and after, its file count and size.
+ */
+function printWebTreeChanges(web) {
+  const shown = webTreeDiffLines(web);
+  if (!shown) return;
+  console.log('');
+  console.log(chalk.bold(`  Web surface — this version ${shown.headline}`));
+  for (const line of shown.lines) {
+    console.log(`    ${shown.changed ? line : chalk.dim(line)}`);
+  }
 }
 
 /**
@@ -874,6 +921,7 @@ function printPendingUpdate(name, update, title) {
     agentHalf: update.agentHalf,
   });
   printIdentityChanges(update.identity);
+  printWebTreeChanges(update.web);
   const lines = settingsDiffLines(update.settings);
   if (lines.length > 0) {
     console.log('');
@@ -916,7 +964,7 @@ async function hooksCmd(name, { json }) {
   console.log('');
   if (!approval.required && !hooks.agent && !hooks.pendingUpdate) {
     console.log(
-      `  Plugin ${chalk.cyan(name)} declares no lifecycle hooks, no agent half for Lamaste to install and no identity.\n`,
+      `  Plugin ${chalk.cyan(name)} declares no lifecycle hooks, no agent half for Lamaste to install, no identity and no web surface.\n`,
     );
     return;
   }
@@ -933,6 +981,7 @@ async function hooksCmd(name, { json }) {
       relay: hooks.relay,
       agentHalf: hooks.agentHalf,
       identity: hooks.identity?.declared ? hooks.identity.block : null,
+      web: hooks.web ?? null,
     });
     console.log(
       `\n    auto-approve for later versions: ${hooks.autoApprove ? chalk.yellow('on') : 'off'}`,
@@ -947,6 +996,13 @@ async function hooksCmd(name, { json }) {
         ),
       );
     }
+    if (hooks.web?.declared) {
+      console.log(
+        chalk.dim(
+          `    Its site (served, trees, offer): lamaste-server plugins web-surface ${terminalText(name)}`,
+        ),
+      );
+    }
   }
   if (hooks.agent) {
     console.log(chalk.bold(`\n  Agent hooks (run by the agent half; no approval)`));
@@ -1262,6 +1318,7 @@ async function installPluginCmd(packageName, { json }) {
       relay: result.hooks.relay,
       agentHalf: result.hooks.agentHalf,
       identity: result.hooks.identity?.declared ? result.hooks.identity.block : null,
+      web: result.hooks.web ?? null,
     });
     if (approval.state === 'pending') {
       console.log(

package/vendor/server/src/commands/sites.js

@@ -7,6 +7,10 @@
  *   delete <id>                     Delete a site by ID
  *   aliases <id> --set <a,b|"">     Replace a custom site's redirect aliases
  *
+ * A site a plugin owns (its web surface) is marked in the list and managed
+ * through `lamaste-server plugins web-surface <plugin>`; the panel refuses
+ * to change or delete it here.
+ *
  * List reads directly from the state file.
  * Create/delete use the panel REST API (which has the full
  * nginx/certbot/directory dependency stack).
@@ -16,6 +20,7 @@ import chalk from 'chalk';
 import { readSites } from '../state.js';
 import { panelRequest } from '../panel-api.js';
 import { emit, emitError, emitComplete } from '../ndjson.js';
+import { siteOwnerTag } from '../plugin-web-surface.js';
 
 /**
  * @param {string[]} args
@@ -92,12 +97,21 @@ async function listSites({ json }) {
     const certStatus = s.certIssued ? g('cert issued') : y('no cert');
     const spaTag = s.spaMode ? d('[SPA]') : '';
     const authTag = s.autheliaProtected ? d('[protected]') : '';
+    const owner = siteOwnerTag(s);
+    const ownerTag = owner ? c(owner) : '';
 
     console.log(
-      `  ${c(s.name)}  ${d(s.fqdn)}  ${s.type}  ${dnsStatus}  ${certStatus} ${spaTag} ${authTag}`.trimEnd(),
+      `  ${c(s.name)}  ${d(s.fqdn)}  ${s.type}  ${dnsStatus}  ${certStatus} ${spaTag} ${authTag} ${ownerTag}`.trimEnd(),
     );
     console.log(`    ${d(`id: ${s.id}`)}`);
   }
+  if (sites.some((s) => siteOwnerTag(s) !== null)) {
+    console.log(
+      d(
+        '\n  A [plugin …] site is the web surface of that plugin: manage it with lamaste-server plugins web-surface <plugin>',
+      ),
+    );
+  }
   console.log('');
 }
 

package/vendor/server/src/plugin-approval.js

@@ -1,11 +1,13 @@
 /**
  * `lamaste-server plugins hooks|update|approve-hooks`: why an update waits
  * for approval, what an identity block lets a plugin learn and how an
- * update changes it, the command that approves it, and the arguments that
+ * update changes it, the web tree a version brings and how an update
+ * changes it, the command that approves it, and the arguments that
  * command takes. Pure — no output — so they are tested as they are.
  */
 
 import { terminalText } from './plugin-settings.js';
+import { bytesText, shortDigest } from './plugin-web-surface.js';
 
 const DIGEST_RE = /^[a-f0-9]{64}$/;
 const VERSION_RE = /^[0-9A-Za-z.+-]{1,64}$/;
@@ -141,6 +143,83 @@ export function identityDiffLines(diff) {
   return { headline, lines };
 }
 
+/**
+ * What the installed version's web surface brings (the hook status's
+ * `web`: `{ declared, approved, treeSha256, surface }`) as lines — the tree
+ * the approval covers, and the site Lamaste offers for it. Empty when it
+ * declares none.
+ *
+ * @param {unknown} web
+ * @returns {string[]}
+ */
+export function webSurfaceBlockLines(web) {
+  if (web === null || typeof web !== 'object' || !web.declared) return [];
+  const surface = web.surface !== null && typeof web.surface === 'object' ? web.surface : null;
+  const lines = [terminalText(`tree:     ${web.treeSha256 ?? 'unknown'}`)];
+  if (surface) {
+    lines.push(
+      terminalText(
+        `site:     offered on ${surface.defaultSubdomain} (${surface.accessMode}), the shell from ${surface.root}/ of its server package`,
+      ),
+    );
+  }
+  return lines;
+}
+
+/**
+ * How an update changes the plugin's web tree (`pendingUpdate.web`:
+ * `{ before: sha256 | null, after: { sha256, files, totalBytes } | null }`
+ * — part of the digest): a headline and its lines. Null when neither
+ * version declares a web surface.
+ *
+ * @param {unknown} web
+ * @returns {{ headline: string, lines: string[], changed: boolean } | null}
+ */
+export function webTreeDiffLines(web) {
+  if (web === null || typeof web !== 'object') return null;
+  const before = typeof web.before === 'string' ? web.before : null;
+  const after =
+    web.after !== null && typeof web.after === 'object' && typeof web.after.sha256 === 'string'
+      ? web.after
+      : null;
+  if (before === null && after === null) return null;
+  const contents = (tree) => `${tree.files} file(s), ${bytesText(tree.totalBytes)}`;
+  if (after === null) {
+    return {
+      headline:
+        'no longer declares a web surface — its site answers 503 until a version that does is approved',
+      lines: [terminalText(`tree:     ${shortDigest(before)} → none`)],
+      changed: true,
+    };
+  }
+  if (before === null) {
+    return {
+      headline: 'declares a web surface for the first time',
+      lines: [
+        terminalText(`tree:     ${after.sha256}`),
+        terminalText(`contents: ${contents(after)}`),
+      ],
+      changed: true,
+    };
+  }
+  if (before === after.sha256) {
+    return {
+      headline: 'keeps its web tree',
+      lines: [terminalText(`tree:     ${after.sha256} (${contents(after)})`)],
+      changed: false,
+    };
+  }
+  return {
+    headline: 'changes its web tree — its site serves the new shell once approved',
+    lines: [
+      terminalText(`tree:     ${shortDigest(before)} → ${shortDigest(after.sha256)}`),
+      terminalText(`new tree: ${after.sha256}`),
+      terminalText(`contents: ${contents(after)}`),
+    ],
+    changed: true,
+  };
+}
+
 /**
  * The command that approves what plugin `name` brings: the installed
  * version by its digest (`{ digest }`), or a pending update by its version

package/vendor/server/src/plugin-web-surface.js

@@ -0,0 +1,307 @@
+/**
+ * A plugin's web surface at the terminal — the arguments of
+ * `lamaste-server plugins web-surface <name> [create|move|delete]`, the
+ * words its output is made of, and how `sites list` marks a site a plugin
+ * owns (what an approval shows about a web tree is in `plugin-approval.js`). Pure — no output, no
+ * panel — so they are tested as they are. Every string from the panel goes
+ * through `terminalText` before it is printed; `--json` carries the data as
+ * it came.
+ */
+
+import { WEB_SURFACE_ACCESS_MODES, isWebSurfaceSubdomain } from '@lamalibre/lamaste';
+import { terminalText } from './plugin-settings.js';
+
+// ---------------------------------------------------------------------------
+// Arguments
+// ---------------------------------------------------------------------------
+
+/** How `plugins web-surface` is called. */
+export const WEB_SURFACE_USAGE =
+  'Usage: lamaste-server plugins web-surface <name> [create [--subdomain <label>] [--access-mode authenticated|restricted] | move --tunnel <id | subdomain | fqdn> | delete [--yes]]';
+
+/** The flags each action takes, and whether each takes a value. */
+const ACTION_FLAGS = {
+  status: {},
+  create: { '--subdomain': true, '--access-mode': true },
+  move: { '--tunnel': true },
+  delete: { '--yes': false },
+};
+
+/** Every flag that takes a value, whichever action it belongs to. */
+const VALUE_FLAGS = new Set(
+  Object.values(ACTION_FLAGS).flatMap((flags) =>
+    Object.entries(flags)
+      .filter(([, takesValue]) => takesValue)
+      .map(([flag]) => flag),
+  ),
+);
+
+/**
+ * The arguments of `plugins web-surface …` after the subcommand: the
+ * plugin, then an action — none (its status), `create` (with `--subdomain`
+ * and `--access-mode`, each defaulting to what the plugin declares),
+ * `move --tunnel <ref>` (a tunnel's id, subdomain or FQDN), or `delete`
+ * (`--yes` skips the typed confirmation).
+ *
+ * @param {string[]} args
+ * @returns {{ ok: true, name: string, action: 'status' }
+ *   | { ok: true, name: string, action: 'create', subdomain: string | null, accessMode: string | null }
+ *   | { ok: true, name: string, action: 'move', tunnel: string }
+ *   | { ok: true, name: string, action: 'delete', yes: boolean }
+ *   | { ok: false, error: string }}
+ */
+export function parseWebSurfaceArgs(args) {
+  const usage = WEB_SURFACE_USAGE;
+  const positional = [];
+  /** @type {Map<string, string | true>} */
+  const flags = new Map();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+    if (flags.has(arg)) return { ok: false, error: `${arg} is given twice — ${usage}` };
+    if (!VALUE_FLAGS.has(arg)) {
+      flags.set(arg, true);
+      continue;
+    }
+    const value = args[i + 1];
+    if (value === undefined || value.startsWith('--')) {
+      return { ok: false, error: `${arg} needs a value — ${usage}` };
+    }
+    flags.set(arg, value);
+    i++;
+  }
+  if (positional.length === 0) return { ok: false, error: usage };
+  if (positional.length > 2) {
+    return { ok: false, error: `Unexpected argument "${positional[2]}" — ${usage}` };
+  }
+  const [name, action = 'status'] = positional;
+  if (positional.length === 2 && !['create', 'move', 'delete'].includes(action)) {
+    return { ok: false, error: `Unknown action "${action}" — ${usage}` };
+  }
+  const allowed = ACTION_FLAGS[action];
+  for (const flag of flags.keys()) {
+    if (!Object.hasOwn(allowed, flag)) {
+      return {
+        ok: false,
+        error:
+          action === 'status'
+            ? `Unknown option ${flag} — ${usage}`
+            : `${action} takes no ${flag} — ${usage}`,
+      };
+    }
+  }
+
+  switch (action) {
+    case 'create': {
+      const subdomain = flags.get('--subdomain') ?? null;
+      const accessMode = flags.get('--access-mode') ?? null;
+      if (subdomain !== null && !isWebSurfaceSubdomain(subdomain)) {
+        return {
+          ok: false,
+          error: `"${subdomain}" cannot be a web surface's subdomain: a DNS label, not reserved (panel, auth, tunnel, www, mail, ftp, api) and not agent-*`,
+        };
+      }
+      if (accessMode !== null && !WEB_SURFACE_ACCESS_MODES.includes(accessMode)) {
+        return {
+          ok: false,
+          error: `--access-mode is ${WEB_SURFACE_ACCESS_MODES.join(' or ')} — a web surface is never public`,
+        };
+      }
+      return { ok: true, name, action, subdomain, accessMode };
+    }
+    case 'move': {
+      const tunnel = flags.get('--tunnel');
+      if (tunnel === undefined) {
+        return {
+          ok: false,
+          error: `Name the tunnel to move: --tunnel <id | subdomain | fqdn> — ${usage}`,
+        };
+      }
+      return { ok: true, name, action, tunnel };
+    }
+    case 'delete':
+      return { ok: true, name, action, yes: flags.has('--yes') };
+    default:
+      return { ok: true, name, action: 'status' };
+  }
+}
+
+/**
+ * The body of `POST /api/plugins/:name/web-surface`: only what was given —
+ * the panel falls back to what the plugin declares.
+ *
+ * @param {{ subdomain: string | null, accessMode: string | null }} parsed
+ * @returns {{ subdomain?: string, accessMode?: string }}
+ */
+export function createBody({ subdomain, accessMode }) {
+  return {
+    ...(subdomain !== null ? { subdomain } : {}),
+    ...(accessMode !== null ? { accessMode } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Output
+// ---------------------------------------------------------------------------
+
+/** A tree digest as the terminal shows it beside others: its first 12 hex digits. */
+export function shortDigest(sha256) {
+  if (typeof sha256 !== 'string' || sha256.length === 0) return '—';
+  return terminalText(sha256.slice(0, 12));
+}
+
+/** A size in bytes, in words (`1.5 MiB`). */
+export function bytesText(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return 'an unknown size';
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ['KiB', 'MiB', 'GiB'];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  return `${value >= 10 ? Math.round(value) : value.toFixed(1)} ${units[unit]}`;
+}
+
+/**
+ * Whether the web surface's site serves the shell and the API, and why not
+ * — the status's `served`/`reason` (and whether it owns a site at all) in
+ * a sentence.
+ *
+ * @param {{ served?: boolean, reason?: string | null, site?: unknown }} view
+ * @param {string} name  the plugin
+ * @returns {{ served: boolean, text: string }}
+ */
+export function webSurfaceServedText(view, name) {
+  const plugin = terminalText(name);
+  const hasSite = view?.site !== null && view?.site !== undefined;
+  if (view?.served) {
+    return hasSite
+      ? { served: true, text: 'served — its site serves the shell and the API' }
+      : {
+          served: false,
+          text: 'ready to be served, but it owns no site yet — create one, or move a bound tunnel to it',
+        };
+  }
+  const where = hasSite ? 'its site answers 503' : 'it owns no site yet';
+  const notServed = (why) => ({ served: false, text: `${why} (${where})` });
+  switch (view?.reason) {
+    case 'not_installed':
+      return notServed('not served — the plugin is not installed');
+    case 'no_identity':
+      return notServed(
+        'not served — its installed version declares no identity, which a web surface fronts',
+      );
+    case 'no_web_surface':
+      return notServed('not served — its installed version declares no web surface');
+    case 'not_owner':
+      return notServed(
+        `not served — its site was created for another package under the same route: delete it (lamaste-server plugins web-surface ${plugin} delete --yes), then create one`,
+      );
+    case 'not_approved':
+      return notServed(
+        `not served — its installed version waits for approval: lamaste-server plugins hooks ${plugin}`,
+      );
+    case 'not_hosted':
+      return notServed(
+        `not served — it is not hosted on an agent, or its hosting is not active: lamaste-server plugins hosting ${plugin}`,
+      );
+    case 'tree_not_current':
+      return notServed(
+        'not served yet — the relay does not serve its approved web tree yet; it switches when the approved version is installed',
+      );
+    default:
+      return {
+        served: false,
+        text: `not served (${terminalText(view?.reason ?? 'unknown')}; ${where})`,
+      };
+  }
+}
+
+/**
+ * The trees the relay holds for a web surface (the status's `tree`:
+ * `{ approved, current, previous }`) as `[label, value]` rows — short
+ * digests, with whether the one served is the approved one.
+ *
+ * @param {{ approved?: string | null, current?: string | null, previous?: string | null } | null | undefined} tree
+ * @returns {Array<[string, string]>}
+ */
+export function webTreeRows(tree) {
+  const approved = tree?.approved ?? null;
+  const current = tree?.current ?? null;
+  const previous = tree?.previous ?? null;
+  const serving =
+    current === null
+      ? 'none'
+      : approved !== null && current === approved
+        ? `${shortDigest(current)} (the approved tree)`
+        : `${shortDigest(current)} (not the approved tree)`;
+  return [
+    ['approved tree', approved === null ? 'none' : shortDigest(approved)],
+    ['serving', serving],
+    [
+      'previous',
+      previous === null ? 'none' : `${shortDigest(previous)} (fallback for pages still open)`,
+    ],
+  ];
+}
+
+/** What each refusal of the web-surface routes asks of the administrator, beside its message. */
+const REFUSAL_HINTS = {
+  no_web_surface: () =>
+    'Its installed version declares no userSurface.web; update to a version that does.',
+  no_identity: () =>
+    'A web surface is the front of its user surface, which needs an identity block.',
+  exists: (name) => `It owns a site already: lamaste-server plugins web-surface ${name}`,
+  bound_to_tunnel: (name) =>
+    `Move that tunnel's host to it instead: lamaste-server plugins web-surface ${name} move --tunnel <id | fqdn>`,
+  hostname_taken: (name) =>
+    `Choose another subdomain: lamaste-server plugins web-surface ${name} create --subdomain <label>`,
+  not_bound: () =>
+    'Only a tunnel bound as its user surface moves (lamaste-server tunnels bind-user-surface).',
+  shared_tunnel: () =>
+    'Unbind the other plugins first: lamaste-server tunnels unbind-user-surface <tunnel> <plugin>',
+  tunnel_disabled: () => 'Enable the tunnel first: lamaste-server tunnels toggle <id> --enable',
+  not_hosted: (name) =>
+    `The agent carrying the tunnel must host it: lamaste-server plugins hosting ${name}`,
+  not_approved: (name) =>
+    `Approve its installed version first: lamaste-server plugins hooks ${name}`,
+  web_tree: () =>
+    "The approved web tree could not be put in place; nothing changed. The panel's log names the file.",
+  gatekeeper: () => 'Gatekeeper could not be reached; nothing changed. Try again once it runs.',
+};
+
+/**
+ * The next step a refusal (`code`) of the web-surface routes points to, or
+ * null when its message says all there is.
+ *
+ * @param {unknown} code
+ * @param {string} name  the plugin
+ * @returns {string | null}
+ */
+export function webSurfaceRefusalHint(code, name) {
+  if (typeof code !== 'string' || !Object.hasOwn(REFUSAL_HINTS, code)) return null;
+  return terminalText(REFUSAL_HINTS[code](terminalText(name)));
+}
+
+// ---------------------------------------------------------------------------
+// Sites
+// ---------------------------------------------------------------------------
+
+/**
+ * How `sites list` marks a site: `[plugin <route>, <access mode>]` for a
+ * site a plugin owns as its web surface, null for any other.
+ *
+ * @param {Record<string, any>} site
+ * @returns {string | null}
+ */
+export function siteOwnerTag(site) {
+  const owner = site?.owner;
+  if (owner === null || typeof owner !== 'object' || typeof owner.plugin !== 'string') return null;
+  const mode = typeof site.accessMode === 'string' ? `, ${site.accessMode}` : '';
+  return terminalText(`[plugin ${owner.plugin}${mode}]`);
+}