@galaxyproject/orbit 0.0.0 → 0.9.0

package/shared/dashboard-layout-store.js

@@ -0,0 +1,281 @@
+/**
+ * The layout file, read and written the same way by everything that touches it.
+ *
+ * Three processes write `.loom-dashboard.json`: the Electron main process on the
+ * renderer's behalf, the web server on the browser's behalf, and the brain. Each
+ * had its own copy of "lstat, read, compare the revision, stage a temp file,
+ * rename", and hand-mirrored copies drift -- one of them followed a dangling
+ * symlink the others refused, and none of them was a compare-and-swap.
+ *
+ * It was not a compare-and-swap because the check and the rename were separated
+ * by an `await`. Two saves based on the same revision both passed the check and
+ * both reported success, and the second silently replaced the first: reproduced
+ * three times out of three against a real directory. Serializing per path inside
+ * the process and re-checking immediately before the rename closes that.
+ *
+ * **The promise chain serializes one process.** The shell and the brain are two,
+ * and two processes that both pass the revision check on the same base both
+ * rename, both report success, and the later rename silently discards the
+ * earlier write -- reproduced with two instances of this module. So the lock is
+ * also a lock FILE beside the layout, created with O_EXCL and held for the
+ * critical section; every writer in every process goes through `withLayoutLock`,
+ * so the file is the one thing they all agree on. A lock left behind by a
+ * process that died is taken over once it is stale.
+ */
+
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+
+import { dashboardRevision } from "./dashboard-contract.js";
+
+/**
+ * One promise chain per absolute path. Every save on a path queues behind the
+ * previous one, so the read-check-rename below is a critical section rather
+ * than three syscalls that happen to be near each other.
+ */
+const chains = new Map();
+
+/**
+ * How long a lock file may sit before another process takes it over. The
+ * critical section is a few small reads and one rename, so anything holding it
+ * this long is gone; the risk of taking over a live one is a lost write, which
+ * is what the lock exists to prevent, so this errs long.
+ */
+const LOCK_STALE_MS = 10_000;
+/** How long a writer waits for the lock before giving up. */
+const LOCK_WAIT_MS = 5_000;
+const LOCK_RETRY_MS = 20;
+
+function lockPathFor(absPath) {
+  return `${absPath}.lock`;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Take the lock file, or throw once the wait runs out.
+ *
+ * `wx` is O_CREAT | O_EXCL: the create either makes the file or fails, and it
+ * fails on a symlink at that name too, so a planted link cannot stand in for
+ * the lock. A stale file -- by its own mtime -- is removed and the create
+ * retried; `rm` on a symlink removes the link, never what it points at.
+ */
+async function acquireLockFile(lockPath) {
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      const fd = await fsp.open(lockPath, "wx");
+      await fd.close();
+      return;
+    } catch (err) {
+      if (err?.code !== "EEXIST") throw err;
+    }
+    try {
+      const st = await fsp.lstat(lockPath);
+      if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+        await fsp.rm(lockPath, { force: true });
+        continue;
+      }
+    } catch {
+      // Gone between the failed create and the lstat: the holder released it.
+      continue;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error("another process is writing the dashboard layout; try again");
+    }
+    await sleep(LOCK_RETRY_MS);
+  }
+}
+
+/**
+ * Run `fn` with nothing else on this path running at the same time -- in this
+ * process, by the promise chain, and in any other, by the lock file.
+ */
+export function withLayoutLock(absPath, fn) {
+  const key = path.resolve(absPath);
+  const previous = chains.get(key) ?? Promise.resolve();
+  const lockPath = lockPathFor(key);
+  const locked = async () => {
+    await acquireLockFile(lockPath);
+    try {
+      return await fn();
+    } finally {
+      await fsp.rm(lockPath, { force: true }).catch(() => {});
+    }
+  };
+  // Settle either way: one caller's failure must not wedge the queue behind it.
+  const run = previous.then(locked, locked);
+  const settled = run.then(
+    () => {},
+    () => {},
+  );
+  chains.set(key, settled);
+  // Drop the entry once nothing is waiting, so a long session switching
+  // analysis directories does not accumulate one chain per directory.
+  void settled.then(() => {
+    if (chains.get(key) === settled) chains.delete(key);
+  });
+  return run;
+}
+
+/** For tests: is anything queued? */
+export function layoutLockIdle() {
+  return chains.size === 0;
+}
+
+/**
+ * Read the layout file, through a descriptor.
+ *
+ * `lstat` first, and on the link itself rather than its target: a dangling
+ * symlink has to read as "there is a symlink here", not as "there is no file
+ * here". The web shell used `existsSync`, which follows the link and therefore
+ * called a dangling one absent -- so it then replaced it while the desktop
+ * refused, which is the drift this module exists to end.
+ *
+ * Then the open, with O_NOFOLLOW, and everything after it on the descriptor:
+ * the agent can write in this directory, and a symlink swapped in between the
+ * `lstat` and a read by name is followed by the read. Reviewers won that race
+ * against the plain `readFile` this used to be, and the bytes of whatever the
+ * link pointed at came back down the layout channel. The kernel refuses the
+ * link at open time; the `fstat` after it has to agree with the `lstat` before
+ * it on identity, regular-file-ness and size; and the read itself stops at the
+ * cap plus one byte, so a file that grows after the `fstat` is refused rather
+ * than served. On Windows there is no O_NOFOLLOW and the identity check is what
+ * remains.
+ */
+export async function readLayoutFile(absPath, maxBytes) {
+  let stat;
+  try {
+    stat = await fsp.lstat(absPath);
+  } catch (err) {
+    if (err?.code === "ENOENT") return { ok: true, raw: null, revision: null };
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+  const name = path.basename(absPath);
+  if (stat.isSymbolicLink()) {
+    return { ok: false, error: `${name} is a symlink; refusing to read` };
+  }
+  if (!stat.isFile()) {
+    return { ok: false, error: `${name} is not a regular file` };
+  }
+  // Checked before the open, so an oversized file is never pulled into memory --
+  // it used to come back whole inside a conflict response.
+  if (stat.size > maxBytes) {
+    return { ok: false, error: `dashboard layout is larger than ${maxBytes} bytes` };
+  }
+
+  let fd;
+  try {
+    fd = await fsp.open(absPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  } catch (err) {
+    // Removed between the two: that is "no file", the same as before the lstat.
+    if (err?.code === "ENOENT") return { ok: true, raw: null, revision: null };
+    // ELOOP is a symlink swapped in after the lstat: the race, refused.
+    if (err?.code === "ELOOP")
+      return { ok: false, error: `${name} is a symlink; refusing to read` };
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+  try {
+    const st = await fd.stat();
+    if (!st.isFile()) return { ok: false, error: `${name} is not a regular file` };
+    if (!sameIdentity(stat, st)) {
+      return { ok: false, error: `${name} changed while it was being read` };
+    }
+    if (st.size > maxBytes) {
+      return { ok: false, error: `dashboard layout is larger than ${maxBytes} bytes` };
+    }
+    const buf = Buffer.alloc(maxBytes + 1);
+    let total = 0;
+    while (total < buf.length) {
+      const { bytesRead } = await fd.read(buf, total, buf.length - total, total);
+      if (bytesRead === 0) break;
+      total += bytesRead;
+    }
+    if (total > maxBytes) {
+      return { ok: false, error: `dashboard layout is larger than ${maxBytes} bytes` };
+    }
+    const raw = buf.subarray(0, total).toString("utf8");
+    return { ok: true, raw, revision: dashboardRevision(raw) };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  } finally {
+    await fd.close().catch(() => {});
+  }
+}
+
+/**
+ * Is the descriptor the file the lstat saw? Inode and device settle it where
+ * the platform reports them; a filesystem that reports zero for either gets no
+ * check, which is the Windows fallback rather than a refusal of every read.
+ */
+function sameIdentity(a, b) {
+  if (!a.ino || !b.ino) return true;
+  return a.ino === b.ino && a.dev === b.dev;
+}
+
+/**
+ * Replace the layout file if it still has the revision the caller based its
+ * change on.
+ *
+ * `baseRevision === undefined` means an unconditional write -- the escape hatch
+ * for a reset over a file nothing can parse. `null` means "there should be no
+ * file yet" and is checked like any other revision.
+ */
+export async function casWriteLayoutFile(absPath, raw, baseRevision, maxBytes) {
+  if (typeof raw !== "string") return { ok: false, error: "expected dashboard JSON text" };
+  if (Buffer.byteLength(raw, "utf8") > maxBytes) {
+    return { ok: false, error: `dashboard layout is larger than ${maxBytes} bytes` };
+  }
+
+  try {
+    return await withLayoutLock(absPath, async () => {
+      const current = await readLayoutFile(absPath, maxBytes);
+      if (!current.ok) return current;
+      if (baseRevision !== undefined && baseRevision !== current.revision) {
+        return {
+          ok: false,
+          conflict: true,
+          error: "the dashboard changed on disk since it was loaded",
+          raw: current.raw,
+          revision: current.revision,
+        };
+      }
+
+      // Stage first, then re-check, then rename with nothing awaited in between.
+      // The scratch name is random and the write is `wx` (O_CREAT | O_EXCL) for
+      // the same reason the real name is lstat'd: the agent can write in this
+      // directory, and a guessable scratch name is a second place to plant a
+      // symlink that the following write would go through.
+      const tmp = `${absPath}.tmp.${randomBytes(8).toString("hex")}`;
+      try {
+        await fsp.writeFile(tmp, raw, { encoding: "utf8", flag: "wx" });
+        const before = await readLayoutFile(absPath, maxBytes);
+        if (!before.ok) {
+          await fsp.rm(tmp, { force: true });
+          return before;
+        }
+        if (baseRevision !== undefined && baseRevision !== before.revision) {
+          await fsp.rm(tmp, { force: true });
+          return {
+            ok: false,
+            conflict: true,
+            error: "the dashboard changed on disk since it was loaded",
+            raw: before.raw,
+            revision: before.revision,
+          };
+        }
+        await fsp.rename(tmp, absPath);
+        return { ok: true, revision: dashboardRevision(raw) };
+      } catch (err) {
+        await fsp.rm(tmp, { force: true }).catch(() => {});
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+    });
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}

package/shared/feedback-contract.d.ts

@@ -0,0 +1,61 @@
+export declare const SCHEMA_VERSION: 1;
+export declare const FEEDBACK_ROUTE: "/feedback";
+export declare const FEEDBACK_KEY_HEADER: "X-Orbit-Feedback-Key";
+export declare const FEEDBACK_ENDPOINT_URL: string;
+export declare const CLI_FEEDBACK_SOURCE: "orbit-cli";
+
+export interface FeedbackSysinfo {
+  appVersion?: string;
+  platform?: string;
+  arch?: string;
+  /**
+   * True when the client runs under WSL. WSL reports `platform: "linux"`, so
+   * without this a WSL report is indistinguishable from a native Linux one --
+   * and GUI/windowing, xdg-open and sandbox behaviour all differ there.
+   * Optional + additive, so schemaVersion stays 1; absent means the report came
+   * from a client that predates the field.
+   */
+  wsl?: boolean;
+  electron?: string;
+  chrome?: string;
+  node?: string;
+  llmProvider?: string;
+  llmModel?: string;
+  galaxyConfigured?: boolean;
+}
+
+export interface FeedbackPayload {
+  schemaVersion: 1;
+  source: "orbit" | "loom-cli" | "orbit-cli";
+  /**
+   * Opaque beta-tester code (e.g. "orbit-007"), copied from OrbitConfig.testerId.
+   * MUST stay top-level: the orbit-feedback worker maps `payload.testerId` to a
+   * first-class `tester_id` column. Optional + additive, so schemaVersion stays 1.
+   */
+  testerId?: string;
+  title: string;
+  body: string;
+  sysinfo?: FeedbackSysinfo;
+  activityTail?: string;
+  shellTail?: string;
+  clientTs: string;
+}
+
+export declare function validateFeedbackPayload(obj: unknown): obj is FeedbackPayload;
+
+export interface FeedbackActivityEvent {
+  timestamp: string;
+  kind: string;
+  source: string;
+  payload?: Record<string, unknown>;
+}
+
+export declare function formatActivityTail(
+  events: FeedbackActivityEvent[],
+  opts?: { maxBytes?: number },
+): string;
+
+export declare function capFeedbackPayload(
+  payload: FeedbackPayload,
+  opts?: { maxTotalBytes?: number },
+): FeedbackPayload;

package/shared/feedback-contract.js

@@ -0,0 +1,146 @@
+// Shared feedback wire contract. Dual-file (.js runtime + .d.ts types) to match
+// team-dispatch-contract: the brain resolves a real .js at runtime, so a single
+// .ts would risk a missing runtime file. No Node imports here -- this file is
+// renderer-safe and shared by the brain, Orbit main, and (by copy) the worker.
+
+export const SCHEMA_VERSION = 1;
+export const FEEDBACK_ROUTE = "/feedback";
+export const FEEDBACK_KEY_HEADER = "X-Orbit-Feedback-Key";
+
+// Production endpoint base (no trailing slash). Set after `wrangler deploy` of
+// the orbit-feedback worker. Clients may override via the LOOM_FEEDBACK_URL env
+// var for local dev.
+export const FEEDBACK_ENDPOINT_URL = "https://orbit-feedback.dannon-baker.workers.dev";
+
+// What the terminal client stamps on its rows. The worker accepts "loom-cli"
+// (0.8 and older) and "orbit-cli" alike.
+export const CLI_FEEDBACK_SOURCE = "orbit-cli";
+
+// "orbit-cli" is accepted ahead of time so a mixed-version fleet validates.
+const SOURCES = new Set(["orbit", "loom-cli", "orbit-cli"]);
+
+export function validateFeedbackPayload(obj) {
+  if (typeof obj !== "object" || obj === null) return false;
+  const p = obj;
+  if (p.schemaVersion !== SCHEMA_VERSION) return false;
+  if (typeof p.source !== "string" || !SOURCES.has(p.source)) return false;
+  if (typeof p.title !== "string" || p.title.trim().length === 0) return false;
+  if (typeof p.body !== "string") return false;
+  if (typeof p.clientTs !== "string") return false;
+  // testerId is optional; when present it must be a string (opaque tester code).
+  if (p.testerId !== undefined && typeof p.testerId !== "string") return false;
+  return true;
+}
+
+const ACTIVITY_TAIL_MAX_BYTES = 64 * 1024;
+// Per-field character limits (not bytes) for readability; the wire byte budget
+// is enforced separately by trimLinesToBytes.
+const ARGS_MAX = 200;
+const RESULT_MAX = 500;
+const PROMPT_MAX = 200;
+
+const textEncoder = new TextEncoder();
+
+function byteLen(s) {
+  return textEncoder.encode(s).length;
+}
+
+function truncate(s, n) {
+  return s.length <= n ? s : s.slice(0, n) + "…";
+}
+
+function compactArgs(args) {
+  if (args == null) return "";
+  let s;
+  try {
+    s = JSON.stringify(args);
+  } catch {
+    s = String(args);
+  }
+  return s ? "args=" + truncate(s, ARGS_MAX) : "";
+}
+
+// One line per event. Renders the already-redacted/truncated payload fields the
+// upstream activity hooks produced -- this function adds no redaction of its own.
+// Embedded line breaks (LF, CRLF, or bare CR from progress-style output) are
+// flattened to spaces so each event stays exactly one line, which keeps the
+// byte-budget trimmer from orphaning a fragment of a multi-line event.
+function formatActivityEvent(e) {
+  const ts = e && e.timestamp ? e.timestamp : "?";
+  const p = (e && e.payload) || {};
+  let rawLine;
+  switch (e && e.kind) {
+    case "user.prompt":
+      rawLine = `${ts} user.prompt ${truncate(String(p.text ?? ""), PROMPT_MAX)}`;
+      break;
+    case "tool.start":
+      rawLine = `${ts} tool.start ${p.toolName ?? "?"} ${compactArgs(p.args)}`;
+      break;
+    case "tool.end": {
+      const flag = p.isError ? "✗" : "✓";
+      rawLine = `${ts} tool.end ${p.toolName ?? "?"} ${flag} ${truncate(String(p.resultSummary ?? ""), RESULT_MAX)}`;
+      break;
+    }
+    default:
+      rawLine = `${ts} ${(e && e.kind) ?? "?"}${e && e.source ? " (" + e.source + ")" : ""}`;
+      break;
+  }
+  return rawLine.trimEnd().replace(/[\r\n]+/g, " ");
+}
+
+// Drop oldest (leading) lines until the text fits maxBytes; hard-slice a lone
+// over-budget line as a floor.
+function trimLinesToBytes(text, maxBytes) {
+  if (byteLen(text) <= maxBytes) return text;
+  const lines = text.split("\n");
+  while (lines.length > 1 && byteLen(lines.join("\n")) > maxBytes) {
+    lines.shift();
+  }
+  let out = lines.join("\n");
+  if (byteLen(out) > maxBytes) {
+    // Binary search for the maximum prefix of 'out' that fits in maxBytes
+    // using character offsets to avoid splitting Unicode surrogate pairs.
+    const arr = Array.from(out);
+    let low = 0;
+    let high = arr.length;
+    let best = "";
+    while (low <= high) {
+      const mid = Math.floor((low + high) / 2);
+      const candidate = arr.slice(0, mid).join("");
+      if (byteLen(candidate) <= maxBytes) {
+        best = candidate;
+        low = mid + 1;
+      } else {
+        high = mid - 1;
+      }
+    }
+    out = best;
+  }
+  return out;
+}
+
+export function formatActivityTail(events, opts = {}) {
+  const maxBytes = opts.maxBytes ?? ACTIVITY_TAIL_MAX_BYTES;
+  const text = (events || []).map(formatActivityEvent).join("\n");
+  return trimLinesToBytes(text, maxBytes);
+}
+
+const FEEDBACK_MAX_TOTAL_BYTES = 200 * 1024;
+
+// Final guard so an assembled payload never bounces off the worker's 256 KB cap.
+// Trim activityTail before shellTail -- the shell tail is closest to what the user
+// actually saw, so it's the last diagnostic we shed. Title/body always stay intact.
+export function capFeedbackPayload(payload, opts = {}) {
+  const maxTotalBytes = opts.maxTotalBytes ?? FEEDBACK_MAX_TOTAL_BYTES;
+  const totalBytes = (p) => byteLen(JSON.stringify(p));
+  let p = { ...payload };
+  for (const field of ["activityTail", "shellTail"]) {
+    const total = totalBytes(p);
+    if (total <= maxTotalBytes) break;
+    if (typeof p[field] !== "string" || p[field].length === 0) continue;
+    const over = total - maxTotalBytes;
+    const target = Math.max(0, byteLen(p[field]) - over);
+    p = { ...p, [field]: trimLinesToBytes(p[field], target) };
+  }
+  return p;
+}

package/shared/galaxy-artifact-links.d.ts

@@ -0,0 +1,30 @@
+export type GalaxyArtifactKind =
+  | "server"
+  | "history"
+  | "dataset"
+  | "collection"
+  | "job"
+  | "invocation"
+  | "workflow"
+  | "page"
+  | "revision"
+  | "tool";
+export interface GalaxyArtifactReference {
+  start: number;
+  end: number;
+  href: string;
+  kind: GalaxyArtifactKind;
+}
+export function normalizeGalaxyLinkServer(serverUrl: unknown): string | null;
+export function galaxyArtifactUrl(
+  serverUrl: unknown,
+  kind: GalaxyArtifactKind,
+  id?: string | null,
+  options?: { pageId?: string },
+): string | null;
+export function galaxyLinkServerInText(text: string): string | null;
+export function galaxyArtifactReferences(
+  text: string,
+  fallbackServer?: string | null,
+  options?: { trustTextServer?: boolean },
+): GalaxyArtifactReference[];

package/shared/galaxy-artifact-links.js

@@ -0,0 +1,166 @@
+/** Galaxy navigation shared by Orbit and its shells. No credentials or network I/O. */
+export function normalizeGalaxyLinkServer(serverUrl) {
+  if (typeof serverUrl !== "string" || !/^https?:\/\//i.test(serverUrl.trim())) return null;
+  try {
+    const url = new URL(serverUrl.trim());
+    if (url.username || url.password || url.search || url.hash) return null;
+    return url.href.replace(/\/+$/, "");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read/view routes from Galaxy's client router. Pages and stored workflows use
+ * /published/... even for private resources: Galaxy still enforces access.
+ * Revisions have no UI deep link; use the exact read-only revision API route.
+ */
+export function galaxyArtifactUrl(serverUrl, kind, id, options = {}) {
+  const base = normalizeGalaxyLinkServer(serverUrl);
+  if (!base) return null;
+  if (kind === "server") return base;
+  if (typeof id !== "string" || !id) return null;
+  if (kind === "tool") return `${base}/?tool_id=${encodeURIComponent(id)}`;
+  if (!/^[a-f0-9]{16,}$/i.test(id)) return null;
+  const encoded = encodeURIComponent(id);
+  switch (kind) {
+    case "history":
+      return `${base}/histories/view?id=${encoded}`;
+    case "dataset":
+      return `${base}/datasets/${encoded}`;
+    case "collection":
+      return `${base}/collection/${encoded}/sheet`;
+    case "job":
+      return `${base}/jobs/${encoded}/view`;
+    case "invocation":
+      return `${base}/workflows/invocations/${encoded}`;
+    case "workflow":
+      return `${base}/published/workflow?id=${encoded}`;
+    case "page":
+      return `${base}/published/page?id=${encoded}`;
+    case "revision":
+      return /^[a-f0-9]{16,}$/i.test(options.pageId ?? "")
+        ? `${base}/api/pages/${encodeURIComponent(options.pageId)}/revisions/${encoded}`
+        : null;
+    default:
+      return null;
+  }
+}
+
+const FIELD_KINDS = {
+  page_id: "page",
+  history_id: "history",
+  dataset_id: "dataset",
+  hda_id: "dataset",
+  collection_id: "collection",
+  hdca_id: "collection",
+  job_id: "job",
+  invocation_id: "invocation",
+  workflow_id: "workflow",
+  stored_workflow_id: "workflow",
+  tool_id: "tool",
+  last_synced_revision: "revision",
+  latest_revision_id: "revision",
+  revision_id: "revision",
+  galaxy_server_url: "server",
+  page_slug: "page",
+};
+const FIELDS = new RegExp(
+  `\\b(${Object.keys(FIELD_KINDS).join("|")})\\b["']?\\s*[:=][ \\t]*["'\x60]?([^\\s"'\x60,}<>]+)`,
+  "gi",
+);
+
+/** Flat metadata only; deliberately not an arbitrary YAML/JSON interpreter. */
+function fieldsIn(text) {
+  return Array.from(text.matchAll(FIELDS), (match) => {
+    const field = match[1].toLowerCase();
+    const kind = FIELD_KINDS[field];
+    const value =
+      ["server", "tool"].includes(kind) || field === "page_slug"
+        ? match[2]
+        : match[2].replace(/[.;]+$/, "");
+    const start = match.index + match[0].lastIndexOf(match[2]);
+    return { field, value, start, end: start + value.length };
+  });
+}
+
+/** Null means absent; "" means explicit but ambiguous/invalid (do not guess). */
+export function galaxyLinkServerInText(text) {
+  const values = fieldsIn(text)
+    .filter((f) => f.field === "galaxy_server_url")
+    .map((f) => f.value);
+  if (!values.length) return null;
+  const servers = new Set(values.map(normalizeGalaxyLinkServer));
+  return servers.size === 1 ? (servers.values().next().value ?? "") : "";
+}
+
+/**
+ * Typed references only. Bare hashes, history item numbers, dates, etc. stay text.
+ *
+ * A `galaxy_server_url` in the text only redirects the other IDs when the
+ * caller says the text is trusted metadata (a notebook block Orbit wrote).
+ * Otherwise a dataset peek, fetched page, or README could point "Open Galaxy
+ * history" links at any host it likes.
+ */
+export function galaxyArtifactReferences(text, fallbackServer, options = {}) {
+  const fields = fieldsIn(text);
+  const server = options.trustTextServer
+    ? (galaxyLinkServerInText(text) ?? fallbackServer)
+    : fallbackServer;
+  const pageIds = new Set(fields.filter((f) => f.field === "page_id").map((f) => f.value));
+  const pageId = pageIds.size === 1 ? pageIds.values().next().value : undefined;
+  const refs = [];
+  for (const field of fields) {
+    // An invocation response's workflow_id names an internal workflow version,
+    // not the stored workflow required by Galaxy's published-workflow view.
+    if (field.field === "workflow_id" && fields.some((f) => f.field === "invocation_id")) continue;
+    const kind = FIELD_KINDS[field.field];
+    const href = galaxyArtifactUrl(
+      // Untrusted, the server field still links to the URL it shows -- just not the other IDs.
+      kind === "server" && !options.trustTextServer ? field.value : server,
+      kind,
+      field.field === "page_slug" ? pageId : field.value,
+      { pageId },
+    );
+    if (href && !["null", "~", "<none>"].includes(field.value)) {
+      refs.push({ start: field.start, end: field.end, href, kind });
+    }
+  }
+  // Prose such as `Dataset ID: abc...` or `invocation abc...`. Require an
+  // encoded ID's length here so ordinary words/numeric history HIDs don't link.
+  const prose =
+    /\b(page|history|dataset|collection|job|invocation|workflow)(?:[ _]id)?\s*[:=#]?\s*([a-f0-9]{16,})\b/gi;
+  for (const match of text.matchAll(prose)) {
+    const start = match.index + match[0].lastIndexOf(match[2]);
+    if (fields.some((r) => start >= r.start && start < r.end)) continue;
+    const kind = match[1].toLowerCase();
+    const href = galaxyArtifactUrl(server, kind, match[2]);
+    if (href) refs.push({ start, end: start + match[2].length, href, kind });
+  }
+  // Markdown deliberately doesn't auto-link inline-code URLs. Recognize Galaxy
+  // view/API routes so an explicit URL still works there, without needing a
+  // connected profile or rewriting links to another server.
+  for (const match of text.matchAll(/https?:\/\/[^\s<>"'`]+/gi)) {
+    const href = match[0].replace(/[.,;!?)\]}]+$/, "");
+    if (refs.some((r) => match.index < r.end && match.index + href.length > r.start)) continue;
+    let url;
+    try {
+      url = new URL(href);
+    } catch {
+      continue;
+    }
+    if (url.username || url.password) continue;
+    const path = url.pathname;
+    let kind;
+    if (/\/api\/pages\/[^/]+\/revisions\/[^/]+$/.test(path)) kind = "revision";
+    else if (/\/published\/(page|workflow)$/.test(path))
+      kind = path.endsWith("page") ? "page" : "workflow";
+    else if (/\/histories\/view$/.test(path)) kind = "history";
+    else if (/\/workflows\/invocations\/[^/]+(?:\/[^/]+)?$/.test(path)) kind = "invocation";
+    else if (/\/jobs\/[^/]+\/view$/.test(path)) kind = "job";
+    else if (/\/collection\/[^/]+\/sheet$/.test(path)) kind = "collection";
+    else if (/\/datasets\/[^/]+(?:\/[^/]+)?$/.test(path)) kind = "dataset";
+    if (kind) refs.push({ start: match.index, end: match.index + href.length, href, kind });
+  }
+  return refs.sort((a, b) => a.start - b.start);
+}