@galaxyproject/orbit 0.0.0 → 0.9.0

package/shared/sra-import.js

@@ -0,0 +1,206 @@
+// Shared, shell-neutral core of the SRA fan-out gate. Orbit's brain and the browser agent both
+// refuse one fastq_dump/fasterq_dump job per accession; the parsing and the turn-local batch
+// bookkeeping live here, while each shell keeps its own tool-name family and refusal wording.
+
+const SRA_TOOL = /^(?:(?:[^/]+\/repos\/iuc\/sra_tools\/)?(?:fastq_dump|fasterq_dump))(?:\/[^/]+)?$/;
+const ACCESSION = /^(?:SRR|ERR|DRR)\d+$/;
+
+/** @typedef {Record<string, unknown>} Obj */
+
+/** @param {unknown} value @returns {Obj | null} */
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? /** @type {Obj} */ (value)
+    : null;
+}
+
+/** A JSON object, given as one or as its JSON text.
+ * @param {unknown} value @returns {Obj | null} */
+export function parseObject(value) {
+  if (typeof value !== "string") return object(value);
+  try {
+    return object(JSON.parse(value));
+  } catch {
+    return null;
+  }
+}
+
+/** A canonical rendering, so two spellings of the same settings share a key.
+ * @param {unknown} value @returns {string} */
+export function stable(value) {
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+  const obj = object(value);
+  if (obj)
+    return `{${Object.keys(obj)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${stable(obj[k])}`)
+      .join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+
+/** @param {Obj} inputs @returns {Obj} */
+export function flatten(inputs) {
+  /** @type {Obj} */
+  const result = {};
+  for (const [key, value] of Object.entries(inputs)) {
+    const group = key === "input" || key === "adv" ? object(value) : null;
+    if (!group) {
+      result[key] = value;
+      continue;
+    }
+    for (const [child, v] of Object.entries(group)) {
+      if (child !== "__current_case__") result[`${key}|${child}`] = v;
+    }
+  }
+  return result;
+}
+
+/** @param {unknown} value @returns {string[] | undefined} */
+export function accessions(value) {
+  if (typeof value !== "string") return undefined;
+  const runs = value
+    .trim()
+    .split(/[\s,;]+/)
+    .filter(Boolean);
+  return runs.length > 0 && runs.every((r) => ACCESSION.test(r)) ? runs : undefined;
+}
+
+/** @type {import("./sra-import.js").NormalizeName} */
+const identity = (name, args) => ({ name, args });
+
+/**
+ * Exact structured surfaces only; never interpret arbitrary Python as JSON.
+ * @param {unknown} name
+ * @param {unknown} input
+ * @param {{ normalizeName?: import("./sra-import.js").NormalizeName }} [options]
+ * @returns {import("./sra-import.js").SraCall | null}
+ */
+export function sraCall(name, input, { normalizeName = identity } = {}) {
+  const parsed = parseObject(input);
+  if (!parsed) return null;
+  const normalized = normalizeName(String(name ?? ""), parsed);
+  if (!normalized || normalized.name !== "run_tool") return null;
+  const args = normalized.args;
+  const toolId = args.tool_id;
+  const historyId = args.history_id;
+  if (typeof toolId !== "string" || typeof historyId !== "string" || !historyId) return null;
+  if (!SRA_TOOL.test(toolId)) return null;
+  const inputs = parseObject(args.inputs);
+  if (!inputs) return null;
+  const flat = flatten(inputs);
+  const mode = flat["input|input_select"] ?? "accession_number";
+  if (mode !== "accession_number" && mode !== "file_list") return null;
+  const value = flat[mode === "file_list" ? "input|file_list" : "input|accession"];
+  const ref = object(value);
+  const settings = { ...flat };
+  delete settings["input|input_select"];
+  delete settings["input|accession"];
+  delete settings["input|file_list"];
+  return {
+    key: stable({ ...args, inputs: settings }),
+    historyId,
+    toolId,
+    runs: mode === "accession_number" ? accessions(value) : undefined,
+    mapped: ref?.__class__ === "Batch" || ref?.batch === true || ref?.src === "hdca",
+    fileList: mode === "file_list" && ref?.src === "hda" && typeof ref.id === "string",
+  };
+}
+
+/** Turn-local import intent: what was fanned out, what was let through, what landed. */
+export class SraImportGate {
+  /** @param {{ remediation: (runs: string[]) => string, normalizeName?: import("./sra-import.js").NormalizeName }} options */
+  constructor({ remediation, normalizeName }) {
+    this.remediation = remediation;
+    this.options = { normalizeName };
+    // Not a second durable import registry. A rejected batch is kept across tool-error
+    // recovery so serializing the same calls won't pass.
+    /** @type {Map<string, Set<string>>} */
+    this.batches = new Map();
+    /** @type {Set<string>} */
+    this.blocked = new Set();
+    // A history preflight can leave exactly one missing accession, and a literal singleton is
+    // the right call for it. Let one singleton out of a rejected batch per key; a second one is
+    // serialization.
+    /** @type {Set<string>} */
+    this.releasedSingleton = new Set();
+    // Accessions already sent to Galaxy in one combined call this turn. Splitting them
+    // afterwards is failure recovery (bad accession, resource limit), not fan-out.
+    /** @type {Map<string, Set<string>>} */
+    this.submitted = new Map();
+  }
+
+  clear() {
+    this.batches.clear();
+    this.blocked.clear();
+    this.releasedSingleton.clear();
+    this.submitted.clear();
+  }
+
+  /** One completed answer's calls, read together before any of them runs.
+   * @param {Iterable<{ id: string, name: string, arguments: unknown }>} calls */
+  observe(calls) {
+    /** @type {Map<string, Array<{ id: string, run: string }>>} */
+    const groups = new Map();
+    for (const part of calls) {
+      const call = sraCall(part.name, part.arguments, this.options);
+      if (!call || call.runs?.length !== 1 || call.mapped) continue;
+      if (this.submitted.get(call.key)?.has(call.runs[0])) continue;
+      const group = groups.get(call.key) ?? [];
+      group.push({ id: part.id, run: call.runs[0] });
+      groups.set(call.key, group);
+    }
+    for (const [key, group] of groups) {
+      if (group.length < 2) continue;
+      const batch = this.batches.get(key) ?? new Set();
+      for (const { id, run } of group) {
+        batch.add(run);
+        this.blocked.add(id);
+      }
+      this.batches.set(key, batch);
+    }
+  }
+
+  /**
+   * @param {string} id @param {string} name @param {unknown} args
+   * @returns {import("./sra-import.js").SraBlock | undefined}
+   */
+  block(id, name, args) {
+    const call = sraCall(name, args, this.options);
+    if (!call) return undefined;
+    const batch = this.batches.get(call.key);
+    const runs = call.runs ?? [];
+    const duplicate = new Set(runs).size < runs.length;
+    const single = runs.length === 1 ? runs[0] : undefined;
+    let serialized = !!(batch && single && batch.size > 1 && batch.has(single));
+    const blocked = this.blocked.has(id) || call.mapped || duplicate;
+    if (serialized && !blocked && !this.releasedSingleton.has(call.key)) {
+      this.releasedSingleton.add(call.key);
+      serialized = false;
+    }
+    if (!blocked && !serialized) {
+      // A history preflight may reduce the candidate set. Do not force the original candidates
+      // back into a corrected batch and re-download them.
+      if (batch && single) batch.delete(single);
+      if (batch && (call.fileList || runs.length > 1)) this.batches.delete(call.key);
+      if (runs.length > 1) {
+        const sent = this.submitted.get(call.key) ?? new Set();
+        for (const run of runs) sent.add(run);
+        this.submitted.set(call.key, sent);
+      }
+      return undefined;
+    }
+    const candidates = [...new Set([...(batch ?? []), ...runs])];
+    return {
+      reason: this.remediation(candidates),
+      call,
+      runs: candidates,
+      cause: call.mapped ? "mapped-import" : duplicate ? "duplicate-accession" : "split-batch",
+    };
+  }
+
+  /** The refusal for a call about to run, or undefined to let it through.
+   * @param {string} id @param {string} name @param {unknown} args @returns {string | undefined} */
+  check(id, name, args) {
+    return this.block(id, name, args)?.reason;
+  }
+}

package/shared/state-dir.d.ts

@@ -0,0 +1,21 @@
+export interface StateDirOptions {
+  home?: string;
+  migrate?: boolean;
+}
+
+export type StateDirMigrationStatus =
+  "disabled" | "nothing-to-migrate" | "already-migrated" | "migrated" | "failed";
+
+export const MIGRATE_TO_ORBIT_STATE_DIR: boolean;
+export const MOVED_MARKER_FILE: string;
+
+export function legacyStateDir(home?: string): string;
+export function orbitStateDir(home?: string): string;
+export function resolveStateDir(opts?: StateDirOptions): string;
+export function resolveConfigPath(opts?: StateDirOptions): string;
+export function resolveCliVersionCheckPath(opts?: StateDirOptions): string;
+export function resolveDefaultAnalysesDir(opts?: StateDirOptions): string;
+export function migrateStateDir(opts?: StateDirOptions & { enabled?: boolean; now?: Date }): {
+  status: StateDirMigrationStatus;
+  error?: unknown;
+};

package/shared/state-dir.js

@@ -0,0 +1,240 @@
+/**
+ * Where the brain keeps its global state (config.json, caches, the session
+ * index, the what's-new stamp). Historically ~/.loom; moving to ~/.orbit.
+ *
+ * Every caller that needs a path under that dir resolves it here rather than
+ * joining homedir() with ".loom" itself, so the move is one switch and a
+ * ~/.orbit/config.json written by a newer release is honored by this one.
+ *
+ * ~/.orbit also holds desktop-only shell state (window-state.json and the
+ * desktop's own version-check.json); nothing here touches those.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Off for the compatibility release: ~/.orbit is used only if a newer release
+// already put a config there, and nothing is copied. On since the rename
+// release: the first run copies config.json (encrypted fields intact, mode
+// 0600) and the user's other durable state into ~/.orbit, leaves a
+// MOVED-TO-ORBIT.txt marker behind, and ~/.orbit is the default for new installs. ~/.loom/analyses stays where it is (see
+// resolveDefaultAnalysesDir).
+export const MIGRATE_TO_ORBIT_STATE_DIR = true;
+
+export const MOVED_MARKER_FILE = "MOVED-TO-ORBIT.txt";
+const CONFIG_FILE = "config.json";
+// Carried across on migration besides config.json: what the user accumulated
+// and could not get back. Caches, the session index and the version-check
+// cache rebuild themselves and stay behind, as does analyses/ (see
+// resolveDefaultAnalysesDir).
+const MIGRATED_FILES = [
+  "whats-new-seen.json",
+  "upload-resume.json",
+  "feedback-outbox.jsonl",
+  "observations-outbox.jsonl",
+  "observations-sent.jsonl",
+  "observations-tokens.json",
+];
+const MIGRATED_DIRS = ["lessons", "lesson-drafts"];
+// Holds a credential or a secret token: copied at 0600 whatever the source had.
+const PRIVATE_FILES = new Set([CONFIG_FILE, "observations-tokens.json"]);
+
+/**
+ * @typedef {{ home?: string, migrate?: boolean }} StateDirOptions
+ */
+
+function homeOf(opts) {
+  return opts?.home ?? os.homedir();
+}
+
+/** @param {string} [home] */
+export function legacyStateDir(home = os.homedir()) {
+  return path.join(home, ".loom");
+}
+
+/** @param {string} [home] */
+export function orbitStateDir(home = os.homedir()) {
+  return path.join(home, ".orbit");
+}
+
+/**
+ * ~/.orbit once it holds a config.json, else ~/.loom -- until migration is on,
+ * after which only an unmigrated ~/.loom/config.json keeps a user on the old
+ * dir.
+ *
+ * @param {StateDirOptions} [opts]
+ */
+export function resolveStateDir(opts = {}) {
+  const home = homeOf(opts);
+  const orbit = orbitStateDir(home);
+  if (fs.existsSync(path.join(orbit, CONFIG_FILE))) return orbit;
+  const legacy = legacyStateDir(home);
+  if (!(opts.migrate ?? MIGRATE_TO_ORBIT_STATE_DIR)) return legacy;
+  return fs.existsSync(path.join(legacy, CONFIG_FILE)) ? legacy : orbit;
+}
+
+/** @param {StateDirOptions} [opts] */
+export function resolveConfigPath(opts = {}) {
+  return path.join(resolveStateDir(opts), CONFIG_FILE);
+}
+
+/**
+ * The CLI's npm version-check cache. ~/.orbit/version-check.json already
+ * belongs to the desktop's GitHub release check, so anywhere but the legacy
+ * dir the CLI uses its own name.
+ *
+ * @param {StateDirOptions} [opts]
+ */
+export function resolveCliVersionCheckPath(opts = {}) {
+  const dir = resolveStateDir(opts);
+  const name =
+    dir === legacyStateDir(homeOf(opts)) ? "version-check.json" : "cli-version-check.json";
+  return path.join(dir, name);
+}
+
+/**
+ * Where a new analysis goes when nothing is configured. ~/.loom/analyses is
+ * real user data that is never moved, and pi keys session history by absolute
+ * cwd, so an existing one keeps winning until ~/.orbit/analyses appears.
+ *
+ * @param {StateDirOptions} [opts]
+ */
+export function resolveDefaultAnalysesDir(opts = {}) {
+  const home = homeOf(opts);
+  const legacy = path.join(legacyStateDir(home), "analyses");
+  const orbit = path.join(orbitStateDir(home), "analyses");
+  if (fs.existsSync(legacy) && !fs.existsSync(orbit)) return legacy;
+  return path.join(resolveStateDir(opts), "analyses");
+}
+
+function movedNotice(legacyDir, orbitDir, when) {
+  return `Loom is now Orbit, and its settings live in ${orbitDir} now.
+
+On ${when} Orbit copied config.json, saved lessons and drafts, the observation
+and feedback outboxes and the what's-new stamp from this directory to
+${orbitDir}. From now on it reads ${path.join(orbitDir, CONFIG_FILE)}
+and ignores ${path.join(legacyDir, CONFIG_FILE)}, so changes made to the copy here
+have no effect. Saved API keys were copied as-is and keep working. Caches and
+the session index were not copied; they rebuild on their own.
+
+Nothing here was deleted. Analyses under ${path.join(legacyDir, "analyses")} stay
+where they are, and Orbit keeps opening them. Loom releases older than 0.9
+still read the old config.json here. Once you no longer run one, the rest of
+this directory apart from analyses/ is safe to remove.
+`;
+}
+
+// Stage the bytes beside the destination, then hard-link into place: link()
+// refuses to replace an existing file, so a second process migrating at the
+// same moment can't overwrite a config the first one already copied and the
+// user has since changed.
+function copyNoClobber(src, dest, mode) {
+  const bytes = fs.readFileSync(src);
+  const tmp = `${dest}.migrating-${process.pid}`;
+  fs.rmSync(tmp, { force: true });
+  const fd = fs.openSync(tmp, "wx", mode);
+  try {
+    // writeFileSync on a descriptor loops until every byte is down; a short
+    // writeSync would otherwise be fsynced and linked into place as the config.
+    fs.writeFileSync(fd, bytes);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    if (fs.statSync(tmp).size !== bytes.length) throw new Error(`short write staging ${dest}`);
+    fs.chmodSync(tmp, mode);
+    try {
+      fs.linkSync(tmp, dest);
+      return true;
+    } catch (err) {
+      if (err?.code === "EEXIST") return false;
+      // Filesystems without hard links: an exclusive copy keeps the no-clobber
+      // guarantee (a rename after an existence check would not).
+      try {
+        fs.copyFileSync(tmp, dest, fs.constants.COPYFILE_EXCL);
+        return true;
+      } catch (copyErr) {
+        if (copyErr?.code === "EEXIST") return false;
+        throw copyErr;
+      }
+    }
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+
+function modeFor(name, src) {
+  return PRIVATE_FILES.has(name) ? 0o600 : fs.statSync(src).mode & 0o777;
+}
+
+// Copies files that are missing on the destination side, so an interrupted
+// migration picks up where it stopped. Symlinks are left alone: the lessons
+// store refuses linked directories, and following one could copy anything.
+function copyTreeNoClobber(srcDir, destDir) {
+  fs.mkdirSync(destDir, { recursive: true, mode: 0o700 });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const src = path.join(srcDir, entry.name);
+    const dest = path.join(destDir, entry.name);
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) copyTreeNoClobber(src, dest);
+    else if (entry.isFile() && !fs.existsSync(dest))
+      copyNoClobber(src, dest, modeFor(entry.name, src));
+  }
+}
+
+/**
+ * One-time copy of ~/.loom's settings and durable state into ~/.orbit. Copies, never moves:
+ * ~/.loom is left intact apart from a MOVED-TO-ORBIT.txt explaining where
+ * things went. Safe to call on every startup.
+ *
+ * @param {StateDirOptions & { enabled?: boolean, now?: Date }} [opts]
+ * @returns {{ status: "disabled" | "nothing-to-migrate" | "already-migrated" | "migrated" | "failed", error?: unknown }}
+ */
+export function migrateStateDir(opts = {}) {
+  if (!(opts.enabled ?? MIGRATE_TO_ORBIT_STATE_DIR)) return { status: "disabled" };
+  const home = homeOf(opts);
+  const legacy = legacyStateDir(home);
+  const orbit = orbitStateDir(home);
+  const legacyConfig = path.join(legacy, CONFIG_FILE);
+  const orbitConfig = path.join(orbit, CONFIG_FILE);
+  const marker = path.join(legacy, MOVED_MARKER_FILE);
+  const writeMarker = () => {
+    try {
+      fs.writeFileSync(marker, movedNotice(legacy, orbit, (opts.now ?? new Date()).toISOString()), {
+        flag: "wx",
+      });
+    } catch {
+      /* already there, or ~/.loom is read-only -- the copy still stands */
+    }
+  };
+
+  if (!fs.existsSync(legacyConfig)) return { status: "nothing-to-migrate" };
+  if (fs.existsSync(orbitConfig)) {
+    writeMarker();
+    return { status: "already-migrated" };
+  }
+  try {
+    fs.mkdirSync(orbit, { recursive: true, mode: 0o700 });
+    // Any failure here aborts before config.json is copied, so the user stays
+    // on ~/.loom with everything intact and the next start tries again.
+    for (const name of MIGRATED_FILES) {
+      const src = path.join(legacy, name);
+      if (!fs.existsSync(src) || fs.existsSync(path.join(orbit, name))) continue;
+      copyNoClobber(src, path.join(orbit, name), modeFor(name, src));
+    }
+    for (const name of MIGRATED_DIRS) {
+      const src = path.join(legacy, name);
+      if (fs.existsSync(src) && fs.statSync(src).isDirectory()) {
+        copyTreeNoClobber(src, path.join(orbit, name));
+      }
+    }
+    // Last, because its presence is what switches resolveStateDir over.
+    const copied = copyNoClobber(legacyConfig, orbitConfig, 0o600);
+    writeMarker();
+    return { status: copied ? "migrated" : "already-migrated" };
+  } catch (error) {
+    return { status: "failed", error };
+  }
+}

package/shared/team-dispatch-contract.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Cross-boundary contract for team_dispatch tool-card payloads.
+ * The brain (extensions/orbit/teams) emits these as the `details` field on
+ * tool execution updates; the shell renderer (app/src/renderer/chat) consumes
+ * them. Keeping the shape here prevents the two sides from drifting.
+ */
+
+export const TEAM_DISPATCH_KIND: "team_dispatch";
+
+export interface TeamDispatchSpecSummary {
+  description?: string;
+  roles?: Array<{ name: string; model?: string }>;
+}
+
+export interface TeamDispatchTurn {
+  round: number;
+  role: string;
+  content?: string;
+  approved?: boolean;
+}
+
+export interface TeamDispatchDetails {
+  kind: typeof TEAM_DISPATCH_KIND;
+  spec?: TeamDispatchSpecSummary;
+  turns?: TeamDispatchTurn[];
+  summary?: string;
+  error?: string;
+}

package/shared/team-dispatch-contract.js

@@ -0,0 +1 @@
+export const TEAM_DISPATCH_KIND = "team_dispatch";

package/shared/truncate-middle.d.ts

@@ -0,0 +1,11 @@
+export function utf8ByteLength(s: string): number;
+export function truncateMiddle(
+  content: string,
+  maxBytes: number,
+): {
+  content: string;
+  truncated: boolean;
+  removedChars: number;
+  totalBytes: number;
+  totalLines: number;
+};

package/shared/truncate-middle.js

@@ -0,0 +1,68 @@
+// Byte-bounded head + tail cut of tool output, the same cut pi 1.1.0 makes for its own tool results
+// (`dist/core/tools/truncate.js` truncateMiddle). Ported over TextEncoder rather than imported: that
+// file is a deep dist import, and it uses Node's byte buffers, which the browser worker lacks.
+
+const encoder = new TextEncoder();
+// ignoreBOM keeps a leading U+FEFF in the head or tail, as pi's Node decode does.
+const decoder = new TextDecoder("utf-8", { ignoreBOM: true });
+
+/**
+ * UTF-8 length of `s` without encoding it. A lone surrogate counts as 3 bytes, the U+FFFD that
+ * TextEncoder (and Node's byteLength) write in its place.
+ * @param {string} s @returns {number}
+ */
+export function utf8ByteLength(s) {
+  let bytes = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c < 0x80) bytes += 1;
+    else if (c < 0x800) bytes += 2;
+    else if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {
+      const next = s.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        i++;
+      } else bytes += 3;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+/** @param {string} content @returns {number} */
+function lineCount(content) {
+  if (content.length === 0) return 0;
+  const lines = content.split("\n");
+  if (content.endsWith("\n")) lines.pop();
+  return lines.length;
+}
+
+/**
+ * Keep the first and last halves of `maxBytes` and replace the middle with a
+ * `…N chars truncated…` marker. Cuts only at character boundaries.
+ * @param {string} content @param {number} maxBytes
+ * @returns {{ content: string, truncated: boolean, removedChars: number, totalBytes: number, totalLines: number }}
+ */
+export function truncateMiddle(content, maxBytes) {
+  const buf = encoder.encode(content);
+  const totalLines = lineCount(content);
+  if (buf.length <= maxBytes) {
+    return { content, truncated: false, removedChars: 0, totalBytes: buf.length, totalLines };
+  }
+  // Continuation bytes (10xxxxxx) never start a character.
+  const isBoundary = (/** @type {number} */ index) =>
+    index >= buf.length || (buf[index] & 0xc0) !== 0x80;
+  let headEnd = Math.floor(maxBytes / 2);
+  while (headEnd > 0 && !isBoundary(headEnd)) headEnd--;
+  let tailStart = buf.length - (maxBytes - Math.floor(maxBytes / 2));
+  while (tailStart < buf.length && !isBoundary(tailStart)) tailStart++;
+  const head = decoder.decode(buf.subarray(0, headEnd));
+  const tail = decoder.decode(buf.subarray(tailStart));
+  const removedChars = Array.from(decoder.decode(buf.subarray(headEnd, tailStart))).length;
+  return {
+    content: `${head}…${removedChars} chars truncated…${tail}`,
+    truncated: true,
+    removedChars,
+    totalBytes: buf.length,
+    totalLines,
+  };
+}

package/shared/version-compare.d.ts

@@ -0,0 +1,10 @@
+export interface SemverParts {
+  major: number;
+  minor: number;
+  patch: number;
+  pre: string;
+}
+export function parseSemver(v: string): SemverParts | null;
+export function comparePre(a: string, b: string): number;
+export function isNewer(current: string, candidate: string): boolean;
+export function pickChannel(version: string): string;

package/shared/version-compare.js

@@ -0,0 +1,74 @@
+// Shared, shell-neutral semver helpers. Used by the Orbit version-check banner
+// and the CLI update notice so there's one implementation of precedence rules.
+// Deliberately dependency-free (no `semver` package) for one small feature.
+
+/**
+ * @typedef {{ major: number, minor: number, patch: number, pre: string }} SemverParts
+ */
+
+/** @param {string} v @returns {SemverParts | null} */
+export function parseSemver(v) {
+  const m = String(v)
+    .replace(/^v/, "")
+    .match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+  if (!m) return null;
+  return {
+    major: parseInt(m[1], 10),
+    minor: parseInt(m[2], 10),
+    patch: parseInt(m[3], 10),
+    pre: m[4] ?? "",
+  };
+}
+
+// Compares two prerelease tags per semver precedence. Numeric segments compare
+// numerically (alpha.10 > alpha.9, which a string compare gets wrong). Returns
+// negative when a < b, positive when a > b, zero when equal.
+/** @param {string} a @param {string} b @returns {number} */
+export function comparePre(a, b) {
+  if (a === b) return 0;
+  // No prerelease tag outranks the same version with one (1.0.0 > 1.0.0-alpha).
+  if (!a) return 1;
+  if (!b) return -1;
+  const ap = a.split(".");
+  const bp = b.split(".");
+  const len = Math.min(ap.length, bp.length);
+  for (let i = 0; i < len; i++) {
+    const x = ap[i];
+    const y = bp[i];
+    const xn = /^\d+$/.test(x);
+    const yn = /^\d+$/.test(y);
+    if (xn && yn) {
+      const dx = parseInt(x, 10);
+      const dy = parseInt(y, 10);
+      if (dx !== dy) return dx < dy ? -1 : 1;
+    } else if (xn !== yn) {
+      // Numeric identifiers have lower precedence than alphanumeric ones.
+      return xn ? -1 : 1;
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+  }
+  return ap.length === bp.length ? 0 : ap.length < bp.length ? -1 : 1;
+}
+
+/** True when `candidate` is a strictly newer version than `current`.
+ * @param {string} current @param {string} candidate @returns {boolean} */
+export function isNewer(current, candidate) {
+  const a = parseSemver(current);
+  const b = parseSemver(candidate);
+  if (!a || !b) return false;
+  if (b.major !== a.major) return b.major > a.major;
+  if (b.minor !== a.minor) return b.minor > a.minor;
+  if (b.patch !== a.patch) return b.patch > a.patch;
+  return comparePre(a.pre, b.pre) < 0;
+}
+
+// Maps an installed version to the npm dist-tag / release channel it tracks.
+// Mirrors release.yml: prerelease -> first prerelease identifier (alpha/beta/
+// rc), plain semver -> latest. So an alpha user hears about alphas, not stable.
+/** @param {string} version @returns {string} */
+export function pickChannel(version) {
+  const parsed = parseSemver(version);
+  if (!parsed || !parsed.pre) return "latest";
+  return parsed.pre.split(".")[0] || "latest";
+}