@xforge-dev/forge-kit 0.18.0 → 0.18.2

package/README.md

@@ -106,6 +106,22 @@ the sign-in cookie, so a third-party script on one can read every user's session
 apps add Vercel Web Analytics (`<Analytics />` from `@vercel/analytics/next` in the root layout);
 it loads from the app's own origin, so the policy needs no extra sources.
 
+## Job catalog
+
+The kit ships a snapshot of `data/jobs.json` for sync lookups (`job()`, `allJobs()`, ...).
+`refreshJobCatalog()` (from `/server`) fetches the published copy at
+`https://cdn.xforge.dev/data/jobs.json`, caching it for an hour, and installs it. The root layout
+awaits it and passes the result to `ForgeJobsProvider` (from `/client`), so the browser gets the same
+catalog. Whenever `data/jobs.json` changes, set `updated` to a new full ISO-8601 UTC timestamp (for
+example `2026-10-29T18:30:00Z`). CI fails a content change that keeps the old stamp.
+
+- **New enum values need a kit release first.** A new `status`, branch or stat value has to ship in
+  a kit release, and every app has to bump to that release, before `data/jobs.json` can use the value.
+  An older parser rejects the whole file and keeps its snapshot, so no part of the edit reaches that app.
+- **Route handlers and server actions refresh the catalog themselves.** They don't run the root layout,
+  so any route handler or server action that looks up jobs must call `await refreshJobCatalog()`
+  before its first lookup. Otherwise it only ever sees the snapshot.
+
 ## Exports
 
 `isForgeAuthConfigured` is exported from the root and `/client` entry points.

package/dist/jobs-provider.js

@@ -3,7 +3,7 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { getJobCatalog, setJobCatalog } from './jobs.js';
 /** Installs the server-fetched catalog before the children render, so client lookups agree with the server. */
 export function ForgeJobsProvider({ catalog, children }) {
-    if (catalog.updated !== getJobCatalog().updated)
+    if (catalog !== getJobCatalog())
         setJobCatalog(catalog);
     return _jsx(_Fragment, { children: children });
 }

package/dist/jobs-server.d.ts

@@ -1,10 +1,12 @@
 import { type JobCatalog } from './jobs.js';
 /**
  * Fetches the shared job catalog (Next's fetch cache, one hour by default), validates it and installs it
- * as the registry. Any failure leaves the current catalog in place and warns once per distinct error.
+ * as the registry. The fetch gives up after `timeoutMs` (default 3s). Any failure, timeout included, leaves the
+ * current catalog in place and warns once per distinct error.
  */
 export declare function refreshJobCatalog(opts?: {
     url?: string;
     revalidate?: number;
+    timeoutMs?: number;
     fetch?: typeof fetch;
 }): Promise<JobCatalog>;

package/dist/jobs-server.js

@@ -2,12 +2,16 @@ import { getJobCatalog, parseJobCatalog, setJobCatalog, JOB_CATALOG_URL } from '
 const warned = new Set();
 /**
  * Fetches the shared job catalog (Next's fetch cache, one hour by default), validates it and installs it
- * as the registry. Any failure leaves the current catalog in place and warns once per distinct error.
+ * as the registry. The fetch gives up after `timeoutMs` (default 3s). Any failure, timeout included, leaves the
+ * current catalog in place and warns once per distinct error.
  */
 export async function refreshJobCatalog(opts = {}) {
     const doFetch = opts.fetch ?? fetch;
     try {
-        const res = await doFetch(opts.url ?? JOB_CATALOG_URL, { next: { revalidate: opts.revalidate ?? 3600 } });
+        const res = await doFetch(opts.url ?? JOB_CATALOG_URL, {
+            next: { revalidate: opts.revalidate ?? 3600 },
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 3000),
+        });
         if (!res.ok)
             throw new Error(`job catalog: HTTP ${res.status}`);
         const next = parseJobCatalog(await res.json());

package/dist/jobs-snapshot.js

@@ -1,6 +1,6 @@
 export const JOBS_SNAPSHOT = {
     "version": 1,
-    "updated": "2026-10-29",
+    "updated": "2026-10-29T18:30:00Z",
     "jobs": [
         {
             "name": "Hero",

package/dist/jobs.js

@@ -115,7 +115,7 @@ export function jobName(name) { return job(name)?.name ?? null; }
 export function allJobs(opts = {}) {
     return catalog.jobs
         .filter((j) => opts.includeRetired || j.status !== 'retired')
-        .sort((a, b) => a.name.localeCompare(b.name));
+        .sort((a, b) => a.name.localeCompare(b.name, 'en'));
 }
 /** Highest Legion rank a character of this level has reached; null below rank B's level. */
 export function legionRankFor(j, level) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xforge-dev/forge-kit",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Shared auth, app registry and UI for xForge apps",
   "license": "MIT",
   "repository": {