@stelstone/server 0.26.0

package/src/adapters/github-oauth.mjs

@@ -0,0 +1,153 @@
+import crypto from "crypto";
+
+/**
+ * GitHub OAuth adapter — drop-in replacement for createBasicAuth.
+ *
+ * Config (cms.config.mjs):
+ *   auth: {
+ *     provider: "github-oauth",
+ *     githubClientIdEnv:     "GITHUB_CLIENT_ID",
+ *     githubClientSecretEnv: "GITHUB_CLIENT_SECRET",
+ *     allowedLogins: ["your-github-username"],  // whitelist
+ *     jwtSecretEnv: "JWT_SECRET",
+ *     jwtTtl: 8 * 60 * 60,
+ *   }
+ *
+ * Add to your .env:
+ *   GITHUB_CLIENT_ID=Ov23li...
+ *   GITHUB_CLIENT_SECRET=...
+ *
+ * Register callback URL in your GitHub OAuth App:
+ *   http://localhost:4001/admin/oauth/callback   (dev)
+ *   https://admin.yoursite.com/admin/oauth/callback  (prod)
+ *
+ * @param {Object} opts
+ * @param {string}   opts.clientId
+ * @param {string}   opts.clientSecret
+ * @param {string[]} opts.allowedLogins   GitHub usernames allowed in
+ * @param {string}   opts.jwtSecret
+ * @param {number}   opts.jwtTtl          Session lifetime in seconds
+ * @param {string}   [opts.realm]
+ * @returns {import('./types.mjs').AuthAdapter & { oauthRoutes: { login, callback } }}
+ */
+export function createGitHubOAuth({
+  clientId,
+  clientSecret,
+  allowedLogins = [],
+  roles = {},
+  jwtSecret,
+  jwtTtl = 8 * 60 * 60,
+  defaultRole = "editor",
+  realm = "Admin",
+}) {
+  // Least privilege: an allowed login without an explicit role entry gets
+  // `defaultRole` ("editor"), matching the basic-auth adapter. Grant admin
+  // via roles: { "login": "admin" } or roles: { "*": "admin" }.
+  function getRole(login) {
+    if (roles[login]) return roles[login];
+    if (roles["*"]) return roles["*"];
+    return defaultRole;
+  }
+  const configured = Boolean(clientId && clientSecret);
+
+  function sign(header, payload) {
+    return crypto
+      .createHmac("sha256", jwtSecret)
+      .update(`${header}.${payload}`)
+      .digest("base64url");
+  }
+
+  function issueToken(claims) {
+    if (!jwtSecret) throw new Error("JWT_SECRET not set");
+    const header = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" })).toString("base64url");
+    const payload = Buffer.from(JSON.stringify({
+      iat: Math.floor(Date.now() / 1000),
+      exp: Math.floor(Date.now() / 1000) + jwtTtl,
+      ...claims,
+    })).toString("base64url");
+    return `${header}.${payload}.${sign(header, payload)}`;
+  }
+
+  function verifyToken(tokenStr) {
+    if (!jwtSecret) return null;
+    const parts = (tokenStr || "").split(".");
+    if (parts.length !== 3) return null;
+    const [header, payload, sig] = parts;
+
+    // Decode and validate header
+    try {
+      const headerData = JSON.parse(Buffer.from(header, "base64url").toString());
+      if (headerData.alg !== "HS256" || headerData.typ !== "JWT") return null;
+    } catch {
+      return null;
+    }
+
+    // Timing-safe signature comparison
+    const expectedSig = sign(header, payload);
+    const sigBuf = Buffer.from(sig, "base64url");
+    const expectedBuf = Buffer.from(expectedSig, "base64url");
+    if (sigBuf.length !== expectedBuf.length) return null;
+    try {
+      if (!crypto.timingSafeEqual(sigBuf, expectedBuf)) return null;
+    } catch {
+      return null;
+    }
+
+    try {
+      const data = JSON.parse(Buffer.from(payload, "base64url").toString());
+      // A token without exp must be rejected — `undefined < now` is false,
+      // which would make it valid forever.
+      if (typeof data.exp !== "number" || data.exp < Math.floor(Date.now() / 1000)) return null;
+      return data;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * @param {Request} request
+   * @returns {Promise<object|null>}
+   */
+  async function verify(request) {
+    const authHeader = request.headers.get("authorization") || "";
+    if (!authHeader.startsWith("Bearer ")) return null;
+    const claims = verifyToken(authHeader.slice(7));
+    if (!claims || claims.type !== "session") return null;
+    return { login: claims.sub, role: getRole(claims.sub), name: claims.name };
+  }
+
+  function issueSessionToken(login, name) {
+    return issueToken({ sub: login, type: "session", name });
+  }
+
+  function issueOAuthState() {
+    if (!jwtSecret) throw new Error("JWT_SECRET not set");
+    const header = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" })).toString("base64url");
+    const now = Math.floor(Date.now() / 1000);
+    const payload = Buffer.from(JSON.stringify({
+      type: "oauth-state",
+      nonce: crypto.randomBytes(16).toString("hex"),
+      iat: now,
+      exp: now + 600,
+    })).toString("base64url");
+    return `${header}.${payload}.${sign(header, payload)}`;
+  }
+
+  function verifyOAuthState(state) {
+    const claims = verifyToken(state);
+    return Boolean(claims && claims.type === "oauth-state");
+  }
+
+  return {
+    configured,
+    /** @param {string} capability */
+    supports: (capability) => ["mediaToken", "session", "oauth"].includes(capability),
+    issueMediaToken(tenantId) {
+      return issueToken({ sub: "media", tenant_id: tenantId, type: "media" });
+    },
+    verify,
+    issueSessionToken,
+    issueOAuthState,
+    verifyOAuthState,
+  };
+}

package/src/adapters/github-templates.mjs

@@ -0,0 +1,100 @@
+import { createGitHubApi } from "./github-api.mjs";
+import { sanitize, safeFileName, commitMsg } from "./_shared.mjs";
+
+/**
+ * GitHub Contents API-backed block-template adapter.
+ *
+ * Templates are stored under `<templatesDir>/<slug>.json` on a configurable
+ * branch. Safe to run on any serverless runtime — no local filesystem.
+ *
+ * @param {Object} opts
+ * @param {string} opts.token        GitHub PAT with repo scope
+ * @param {string} opts.owner
+ * @param {string} opts.repo
+ * @param {string} opts.branch
+ * @param {string} [opts.templatesDir=".cms-templates"]
+ * @param {(ts: string) => string} [opts.commitMessage]
+ * @returns {import('./types.mjs').TemplatesAdapter}
+ */
+export function createGitHubTemplates({
+  token,
+  owner,
+  repo,
+  branch,
+  templatesDir = ".cms-templates",
+  commitMessage,
+}) {
+  const { apiGet, apiPut, apiDelete } = createGitHubApi({ token, owner, repo });
+  const shaCache = new Map();
+
+  function filePath(slug) {
+    return `${templatesDir}/${sanitize(slug)}.json`;
+  }
+
+  function msg() {
+    return commitMsg(commitMessage, "Template updated");
+  }
+
+  return {
+    async list() {
+      const items = await apiGet(`/contents/${templatesDir}?ref=${branch}`);
+      if (!items || !Array.isArray(items)) return [];
+      const jsonFiles = items.filter((i) => i.type === "file" && i.name.endsWith(".json"));
+      return Promise.all(
+        jsonFiles.map(async (item) => {
+          shaCache.set(item.path, item.sha);
+          const r = await fetch(item.download_url, {
+            headers: { Authorization: `Bearer ${token}`, "User-Agent": "stelstone" },
+          });
+          if (!r.ok) return null;
+          const data = await r.json();
+          return {
+            name: data.name,
+            slug: item.name.replace(".json", ""),
+            blockCount: (data.blocks || []).length,
+          };
+        }),
+      ).then((rs) => rs.filter(Boolean));
+    },
+
+    async get(slug) {
+      if (!safeFileName(slug)) return null;
+      const path = filePath(slug);
+      const data = await apiGet(`/contents/${path}?ref=${branch}`);
+      if (!data || Array.isArray(data)) return null;
+      shaCache.set(path, data.sha);
+      return JSON.parse(Buffer.from(data.content, "base64").toString("utf-8"));
+    },
+
+    async put(slug, data) {
+      if (!safeFileName(slug)) return null;
+      const path = filePath(slug);
+      let sha = shaCache.get(path);
+      if (!sha) {
+        const existing = await apiGet(`/contents/${path}?ref=${branch}`);
+        if (existing && !Array.isArray(existing)) sha = existing.sha;
+      }
+      const result = await apiPut(`/contents/${path}`, {
+        message: msg(),
+        content: Buffer.from(JSON.stringify(data, null, 2), "utf-8").toString("base64"),
+        branch,
+        ...(sha ? { sha } : {}),
+      });
+      shaCache.set(path, result.content?.sha);
+    },
+
+    async delete(slug) {
+      if (!safeFileName(slug)) return null;
+      const path = filePath(slug);
+      let sha = shaCache.get(path);
+      if (!sha) {
+        const existing = await apiGet(`/contents/${path}?ref=${branch}`);
+        if (!existing || Array.isArray(existing)) return false;
+        sha = existing.sha;
+      }
+      await apiDelete(`/contents/${path}`, { message: msg(), sha, branch });
+      shaCache.delete(path);
+      return true;
+    },
+  };
+}

package/src/adapters/index.mjs

@@ -0,0 +1,12 @@
+export { createFsJsonContent } from "./fs-json-content.mjs";
+export { createFsTemplates } from "./fs-templates.mjs";
+export { createGitHubContent } from "./github-content.mjs";
+export { createGitHubTemplates } from "./github-templates.mjs";
+export { createLocalAssetsMedia } from "./local-assets-media.mjs";
+export { createCdnProxyMedia } from "./cdn-proxy-media.mjs";
+export { createBasicAuth } from "./basic-auth.mjs";
+export { createGitHubOAuth } from "./github-oauth.mjs";
+export { createCloudflareAccess } from "./cloudflare-access.mjs";
+export { createNetlifyBuild } from "./build-netlify.mjs";
+export { createMediaUrl } from "./media-url.mjs";
+export { createResendMail } from "./resend-mail.mjs";

package/src/adapters/local-assets-media.mjs

@@ -0,0 +1,68 @@
+import fs from "fs";
+import path from "path";
+import { sanitize } from "./_shared.mjs";
+
+const IMAGE_RE = /\.(png|jpg|jpeg|svg|webp|gif)$/i;
+
+/**
+ * Local-filesystem media adapter for the legacy file picker.
+ * Lists images grouped by top-level folder under `<rootDir>/<assetsDir>`.
+ *
+ * @param {Object} opts
+ * @param {string} opts.rootDir
+ * @param {string} opts.assetsDir   Relative to rootDir, e.g. "src/assets".
+ * @returns {import('./types.mjs').MediaAdapter & {urlPrefix: string}}
+ */
+export function createLocalAssetsMedia({ rootDir, assetsDir }) {
+  const ROOT = path.join(rootDir, assetsDir);
+  const URL_PREFIX = `/${assetsDir.replace(/^\/+/, "")}`;
+
+  function listImages(dir, prefix) {
+    const out = [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        out.push(...listImages(full, `${prefix}/${entry.name}`));
+      } else if (IMAGE_RE.test(entry.name)) {
+        out.push(`${prefix}/${entry.name}`);
+      }
+    }
+    return out;
+  }
+
+  return {
+    async listGrouped() {
+      if (!fs.existsSync(ROOT)) return {};
+      const folders = fs
+        .readdirSync(ROOT)
+        .filter((d) => fs.statSync(path.join(ROOT, d)).isDirectory());
+      const out = {};
+      for (const folder of folders) {
+        const files = listImages(
+          path.join(ROOT, folder),
+          `${URL_PREFIX}/${folder}`,
+        );
+        if (files.length > 0) out[folder] = files;
+      }
+      return out;
+    },
+
+    async listFolder(folder) {
+      const dir = path.join(ROOT, sanitize(folder));
+      if (!fs.existsSync(dir)) return [];
+      return listImages(dir, `${URL_PREFIX}/${sanitize(folder)}`);
+    },
+
+    resolveLocalPath(relPath) {
+      const sub = String(relPath).replace(/^\/+/, "");
+      const full = path.resolve(ROOT, sub);
+      // Compare with a trailing separator — a bare startsWith(ROOT) would
+      // also accept sibling dirs like "<ROOT>-evil".
+      if (!full.startsWith(ROOT + path.sep) || !fs.existsSync(full)) return null;
+      return full;
+    },
+
+    urlPrefix: URL_PREFIX,
+  };
+}

package/src/adapters/media-url.mjs

@@ -0,0 +1,133 @@
+/**
+ * Build CDN URLs and responsive <img> props for media stored behind a
+ * CloudFront/S3 (or compatible) origin with a path-based resize behavior.
+ *
+ * Pure factory — no environment, no fs. Configure once with the consumer's
+ * `cms.config.media` settings; everything else is derived.
+ *
+ * @typedef {Object} MediaUrlConfig
+ * @property {string} cdnBase                 e.g. "https://media.natilon.com"
+ * @property {string} [resizePrefix="/_r/"]   path prefix for the resize behavior
+ * @property {number[]} [defaultWidths]       fallback srcset widths
+ * @property {string} [tenantId]              multi-tenant prefix, e.g. "natilon"
+ *
+ * @typedef {Object} ResizeParams
+ * @property {number} [w]
+ * @property {number} [h]
+ * @property {number} [q]
+ * @property {"cover"|"contain"|"fill"|"inside"|"outside"} [fit]
+ * @property {"webp"|"avif"|"jpg"|"png"} [f]
+ */
+
+/**
+ * @param {MediaUrlConfig} config
+ */
+export function createMediaUrl(config) {
+  const cdnBase = String(config.cdnBase || "").replace(/\/+$/, "");
+  const resizePrefix = (config.resizePrefix || "/_r/").replace(/\/+$/, "/");
+  const defaultWidths = config.defaultWidths || [400, 800, 1200, 1600, 2400];
+  const tenantId = config.tenantId ? `/p/${config.tenantId}` : "";
+  let cdnHost = "";
+  try {
+    cdnHost = new URL(cdnBase).hostname;
+  } catch {
+    /* empty cdnBase or invalid URL — url() will still work for absolute inputs */
+  }
+
+  function buildQuery(params) {
+    const qs = new URLSearchParams();
+    if (params?.w) qs.set("w", String(params.w));
+    if (params?.h) qs.set("h", String(params.h));
+    if (params?.q) qs.set("q", String(params.q));
+    if (params?.fit) qs.set("fit", params.fit);
+    if (params?.f) qs.set("f", params.f);
+    return qs.toString();
+  }
+
+  /** Build a CDN URL from a key or a full URL, optionally with resize params. */
+  function url(keyOrUrl, params) {
+    if (!keyOrUrl) return "";
+    const query = buildQuery(params);
+
+    if (keyOrUrl.startsWith("http://") || keyOrUrl.startsWith("https://")) {
+      if (!query) return keyOrUrl;
+      try {
+        const u = new URL(keyOrUrl);
+        if (cdnHost && u.hostname === cdnHost) {
+          const r = resizePrefix.replace(/\/$/, "");
+          if (tenantId && u.pathname.startsWith(tenantId + "/")) {
+            const rest = u.pathname.slice(tenantId.length);
+            if (!rest.startsWith(resizePrefix)) {
+              u.pathname = tenantId + r + rest;
+            }
+          } else if (!u.pathname.startsWith(resizePrefix)) {
+            u.pathname = r + u.pathname;
+          }
+        }
+        const existing = u.search.replace(/^\?/, "");
+        u.search = existing ? `${existing}&${query}` : query;
+        return u.toString();
+      } catch {
+        return `${keyOrUrl}${keyOrUrl.includes("?") ? "&" : "?"}${query}`;
+      }
+    }
+
+    const key = keyOrUrl.replace(/^\/+/, "");
+    if (!query) return `${cdnBase}${tenantId}/${key}`;
+    return `${cdnBase}${tenantId}${resizePrefix}${key}?${query}`;
+  }
+
+  /** Resolve a stored value (key, full URL, or bare name + folder hint) to a CDN URL. */
+  function resolve(value, folder, params) {
+    if (!value) return "";
+    if (value.startsWith("http://") || value.startsWith("https://")) {
+      return params ? url(value, params) : value;
+    }
+    let key = value.replace(/^\/+/, "").replace(/^src\/assets\//, "");
+    if (folder && !key.includes("/")) {
+      key = `${folder}/${key}`;
+    }
+    return url(key, params);
+  }
+
+  function pickWidths(targetW, widths) {
+    if (widths && widths.length) return [...widths].sort((a, b) => a - b);
+    if (!targetW) return defaultWidths;
+    const set = new Set();
+    for (const m of [0.5, 1, 1.5, 2]) {
+      const w = Math.round(targetW * m);
+      if (w >= 200 && w <= 2400) set.add(w);
+    }
+    return [...set].sort((a, b) => a - b);
+  }
+
+  /** Build a srcset string sized at the given widths. */
+  function srcset(value, widths, folder, params) {
+    if (!value) return "";
+    return widths.map((w) => `${resolve(value, folder, { ...params, w })} ${w}w`).join(", ");
+  }
+
+  /** Build the {src, srcset, sizes, width, height} props for a responsive <img>. */
+  function imageProps(value, opts = {}) {
+    if (!value) return { src: "" };
+    const { folder, width, height, widths, sizes = "100vw", f = "webp", q = 80, fit } = opts;
+    const widthList = pickWidths(width, widths);
+    const fallbackW =
+      width ?? widthList[Math.min(widthList.length - 1, Math.floor(widthList.length / 2))];
+    const baseParams = { f, q, ...(fit ? { fit } : {}) };
+    const src = resolve(value, folder, {
+      ...baseParams,
+      w: fallbackW,
+      ...(height ? { h: height } : {}),
+    });
+    return {
+      src,
+      srcset: srcset(value, widthList, folder, baseParams),
+      sizes,
+      width,
+      height,
+    };
+  }
+
+  return { url, resolve, srcset, imageProps, defaultWidths };
+}

package/src/adapters/resend-mail.mjs

@@ -0,0 +1,41 @@
+/**
+ * Mail delivery via Resend — the form module's first (and so far only)
+ * provider. The adapter shape is the extension point: a second provider is a
+ * new file with the same `{ configured, send }` surface, not a code change.
+ *
+ * @param {Object} opts
+ * @param {string} [opts.apiKey]  Missing key → `configured: false`; the forms
+ *        route answers 503 with a clear message instead of failing mid-send.
+ * @param {string} opts.from      Sender, e.g. "Site <forms@site.com>". The
+ *        domain must be verified in Resend (SPF/DKIM) or delivery fails.
+ */
+export function createResendMail({ apiKey, from }) {
+  return {
+    configured: !!(apiKey && from),
+
+    async send({ to, subject, text, replyTo }) {
+      const res = await fetch("https://api.resend.com/emails", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          from,
+          to: Array.isArray(to) ? to : [to],
+          subject,
+          text,
+          ...(replyTo ? { reply_to: replyTo } : {}),
+        }),
+      });
+      if (!res.ok) {
+        let detail = "";
+        try { detail = (await res.json()).message ?? ""; } catch { /* body optional */ }
+        const err = new Error(`Mail delivery failed (${res.status})${detail ? `: ${detail}` : ""}`);
+        err.upstreamStatus = res.status;
+        throw err;
+      }
+      return await res.json();
+    },
+  };
+}

package/src/adapters/types.mjs

@@ -0,0 +1,104 @@
+/**
+ * Adapter interface contracts for the natilon CMS core.
+ *
+ * These are JSDoc typedefs only — no runtime code. Concrete implementations
+ * (fs-json-content, local-assets-media, basic-auth, build-netlify) export
+ * factory functions that return objects matching these shapes.
+ *
+ * The admin server depends only on these interfaces, so swapping a backend
+ * (e.g. GitHub Contents API instead of local fs, S3 instead of local
+ * assets, OAuth instead of basic-auth) is a one-line config change.
+ */
+
+/**
+ * @typedef {Object} PageSummary
+ * @property {string} id
+ * @property {string} slug
+ * @property {string} lang
+ * @property {string} collection
+ * @property {string} title
+ * @property {string} file
+ */
+
+/**
+ * @typedef {Object} CollectionSummary
+ * @property {string} name
+ * @property {number} count
+ */
+
+/**
+ * @typedef {Object} PublishResult
+ * @property {boolean} ok
+ * @property {string} message
+ * @property {string} [sha]
+ * @property {string} [shortSha]
+ * @property {string} [branch]
+ */
+
+/**
+ * @typedef {Object} PendingChanges
+ * @property {boolean} hasChanges
+ * @property {number} changedFiles
+ */
+
+/**
+ * @typedef {Object} ContentAdapter
+ * @property {() => Promise<CollectionSummary[]>} listCollections
+ * @property {(collection: string) => Promise<PageSummary[]|null>} listPages
+ * @property {(collection: string, file: string) => Promise<object|null>} readPage
+ * @property {(collection: string, file: string, data: object) => Promise<void>} writePage
+ * @property {(collection: string, data: object) => Promise<{file: string}>} createPage
+ * @property {(collection: string, file: string) => Promise<boolean>} deletePage
+ * @property {(collection: string, file: string) => Promise<{file: string}|null>} duplicatePage
+ * @property {() => Promise<PendingChanges>} pendingChanges
+ * @property {() => Promise<PublishResult>} publish
+ * @property {(items: Array<{collection: string, file: string, data: object}>, message?: string) => Promise<{ok: boolean, sha?: string, commitCount: number}>} writeBatch
+ */
+
+/**
+ * @typedef {Object} MediaAdapter
+ * @property {() => Promise<Record<string, string[]>>} listGrouped
+ * @property {(folder: string) => Promise<string[]>} listFolder
+ * @property {(relPath: string) => string|null} resolveLocalPath
+ */
+
+/**
+ * Auth port.
+ *
+ * `verify` receives the whole Request — not just the Authorization header —
+ * so adapters that authenticate from a different header or a cookie (e.g.
+ * Cloudflare Access) are first-class rather than special cases. It is async
+ * by contract even when an implementation answers synchronously, so callers
+ * can always await it.
+ *
+ * @typedef {Object} AuthAdapter
+ * @property {boolean} configured
+ * @property {(request: Request) => Promise<{login: string, name?: string, role: string}|null>} verify
+ * @property {(tenantId: string) => string} issueMediaToken
+ * @property {(login: string, name?: string) => string} [issueSessionToken]  github-oauth only
+ * @property {() => string} [issueOAuthState]                                github-oauth only
+ * @property {(state: string) => boolean} [verifyOAuthState]                 github-oauth only
+ */
+
+/**
+ * @typedef {Object} BuildAdapter
+ * @property {boolean} configured
+ * @property {(opts?: {branch?: string, sha?: string}) => Promise<object>} getDeployStatus
+ */
+
+/**
+ * @typedef {Object} TemplateSummary
+ * @property {string} name
+ * @property {string} slug
+ * @property {number} blockCount
+ */
+
+/**
+ * @typedef {Object} TemplatesAdapter
+ * @property {() => Promise<TemplateSummary[]>} list
+ * @property {(slug: string) => Promise<object|null>} get
+ * @property {(slug: string, data: object) => Promise<void>} put
+ * @property {(slug: string) => Promise<boolean>} delete
+ */
+
+export {};

package/src/admin-ui-path.mjs

@@ -0,0 +1,77 @@
+import { createRequire } from "module";
+import path from "path";
+import fs from "fs";
+
+const __dirname = path.dirname(new URL(import.meta.url).pathname);
+const require_ = createRequire(import.meta.url);
+
+/**
+ * Locate the installed `@stelstone/admin-ui` package.
+ *
+ * The admin UI is a *peer* of this package, not a dependency: it is a
+ * deployment artifact the site owns, exactly like the site's Worker assets.
+ * That means it must be located through module resolution rather than by
+ * guessing a relative path — the previous `../../admin-ui/dist` guess happened
+ * to work for a flat npm layout and silently resolved to nothing whenever npm
+ * nested or deduped the package elsewhere.
+ *
+ * Node only. A Worker serves the SPA from its assets binding and never calls
+ * any of this.
+ *
+ * @returns {string|null} Absolute path to the package root.
+ */
+function resolvePackageDir() {
+  try {
+    return path.dirname(require_.resolve("@stelstone/admin-ui/package.json"));
+  } catch {
+    // Monorepo or linked checkout where the package is a sibling directory
+    // rather than an installed dependency.
+    const sibling = path.resolve(__dirname, "../../admin-ui");
+    return fs.existsSync(path.join(sibling, "package.json")) ? sibling : null;
+  }
+}
+
+/**
+ * Absolute path to the built admin-ui dist directory, or null when the admin
+ * UI is not installed or has not been built yet.
+ */
+export function resolveAdminUiDir() {
+  const pkgDir = resolvePackageDir();
+  if (!pkgDir) return null;
+  const dist = path.join(pkgDir, "dist");
+  return fs.existsSync(path.join(dist, "index.html")) ? dist : null;
+}
+
+/**
+ * The admin-ui source root (the Vite project root) for dev/HMR mode.
+ * Only available when the source is present — a published tarball ships
+ * `dist` alone.
+ */
+export function resolveAdminUiSourceDir() {
+  const pkgDir = resolvePackageDir();
+  if (!pkgDir) return null;
+  return fs.existsSync(path.join(pkgDir, "vite.config.js")) &&
+    fs.existsSync(path.join(pkgDir, "index.html"))
+    ? pkgDir
+    : null;
+}
+
+/**
+ * The version of the admin UI this server would actually serve.
+ *
+ * Read from the resolved package at runtime, never baked in at build time:
+ * the server and the admin UI are versioned independently, so a constant
+ * captured when the server was released would describe a different bundle
+ * than the one on disk.
+ *
+ * @returns {string|null}
+ */
+export function resolveAdminUiVersion() {
+  const pkgDir = resolvePackageDir();
+  if (!pkgDir) return null;
+  try {
+    return JSON.parse(fs.readFileSync(path.join(pkgDir, "package.json"), "utf-8")).version ?? null;
+  } catch {
+    return null;
+  }
+}