Task #589: Live build stamp + server start time in System Updates panel

Problem: After `git pull && docker compose up -d --build api` on the Mac, the admin → System Updates panel kept showing the same version (0.1.0-dev) and the same build (20260517.8a5bd5db) because both come from version.json, a hand-edited file that nothing rewrites on every build. No visible signal that a new image was actually running. Two independent signals were added — neither needs editing version.json by hand: 1) Auto-stamp version.json at Docker build time - docker/api-server.Dockerfile: new ARGs GIT_SHA and BUILD_DATE. A `node -e` step rewrites version.json's `build` field to `${YYYYMMDDTHHmm}.${sha}` (e.g. 20260518T1042.71da8e01). When the args are missing/"unknown", version.json is left untouched so plain `docker build` and Replit `pnpm dev` still work. - docker-compose.yml: api.build.args wires through GIT_SHA and BUILD_DATE with `${GIT_SHA:-unknown}` fallbacks. - scripts/redeploy.sh: exports GIT_SHA (git rev-parse --short HEAD) and BUILD_DATE (date -u +%Y-%m-%dT%H:%M:%SZ) before `docker compose build`, so the helper script just works. 2) startedAt timestamp from the API - artifacts/api-server/src/routes/system.ts: SERVER_STARTED_AT captured at module load (frozen for the process lifetime) and added to every branch of GET /system/version (not-configured, error, invalid-version, up-to-date, update-available, catch). - lib/api-spec/openapi.yaml: added `startedAt: date-time` to SystemVersionResponse (required). Regenerated api-client-react and api-zod via `pnpm --filter @workspace/api-spec run codegen`. 3) Admin UI surfacing both signals - artifacts/tx-os/src/pages/admin.tsx: new formatBuildStamp parses `YYYYMMDD[THHmm].sha` and renders a localized date next to the raw token. A new "Server started" line below the build number formats the boot timestamp via the existing formatChecked helper. - artifacts/tx-os/src/locales/{en,ar}.json: added admin.systemUpdates.serverStartedAt ("Server started" / "بدأ تشغيل الخادم"). 4) Docs - replit.md: documented how to verify a real redeploy via the System Updates panel and the manual one-liner for `docker compose build` without the helper script. Verified: codegen succeeds, API workflow restarted clean, Vite served fine. Pre-existing typecheck errors in push.ts and font-settings are unrelated and untouched. Mac next steps: cd ~/Downloads/TX && git pull && ./scripts/redeploy.sh Then open admin → System Updates: build line should show a new `YYYYMMDDTHHmm.sha` stamp and "Server started" should reflect the new boot time.
2026-05-18 10:39:17 +00:00
parent bbe0482e1c
commit 608e15cf91
10 changed files with 105 additions and 0 deletions
@@ -9,6 +9,12 @@ const router: IRouter = Router();
 const CURRENT_VERSION: string = versionFile.version;
 const CURRENT_BUILD: string = versionFile.build;

+// Captured once at module load — frozen for the lifetime of the
+// process. The admin "System Updates" panel renders this so the user
+// gets a visible signal whenever the container actually restarts
+// (independent of build/version, which only change on rebuild).
+const SERVER_STARTED_AT: string = new Date().toISOString();
+
 const LATEST_URL = process.env.LATEST_VERSION_URL ?? "";
 const FETCH_TIMEOUT_MS = 5000;

@@ -29,6 +35,7 @@ router.get("/system/version", requireAdmin, async (_req, res): Promise<void> =>
        errorMessage: null,
        checkedAt,
        configured: false,
+          startedAt: SERVER_STARTED_AT,
      }),
    );
    return;
@@ -50,6 +57,7 @@ router.get("/system/version", requireAdmin, async (_req, res): Promise<void> =>
          errorMessage: `HTTP ${response.status}`,
          checkedAt,
          configured: true,
+          startedAt: SERVER_STARTED_AT,
        }),
      );
      return;
@@ -68,6 +76,7 @@ router.get("/system/version", requireAdmin, async (_req, res): Promise<void> =>
          errorMessage: "Invalid version format",
          checkedAt,
          configured: true,
+          startedAt: SERVER_STARTED_AT,
        }),
      );
      return;
@@ -86,6 +95,7 @@ router.get("/system/version", requireAdmin, async (_req, res): Promise<void> =>
        errorMessage: null,
        checkedAt,
        configured: true,
+          startedAt: SERVER_STARTED_AT,
      }),
    );
  } catch (err) {
@@ -103,6 +113,7 @@ router.get("/system/version", requireAdmin, async (_req, res): Promise<void> =>
        errorMessage: message,
        checkedAt,
        configured: true,
+          startedAt: SERVER_STARTED_AT,
      }),
    );
  } finally {
@@ -556,6 +556,7 @@
      "checkNow": "تحقّق الآن",
      "loading": "جاري التحقق من الإصدار…",
      "lastChecked": "آخر تحقق",
+      "serverStartedAt": "بدأ تشغيل الخادم",
      "toastErrorTitle": "تعذّر التحقق",
      "toastErrorDesc": "لم نتمكن من الوصول إلى مصدر التحديثات. حاول مرة أخرى لاحقاً."
    },
@@ -532,6 +532,7 @@
      "checkNow": "Check Now",
      "loading": "Checking version…",
      "lastChecked": "Last checked",
+      "serverStartedAt": "Server started",
      "toastErrorTitle": "Check failed",
      "toastErrorDesc": "Could not reach the update source. Please try again later."
    },
@@ -2381,6 +2381,31 @@ function SystemUpdatesPanel() {
    }).format(d);
  };

+  // The Docker build step stamps `build` as `YYYYMMDDTHHmm.shortsha`
+  // (e.g. `20260518T1042.a34eb5f5`). When the value matches that
+  // pattern, render a localized date/time next to the raw token so a
+  // non-technical user can see at a glance when the image was built.
+  // Older / hand-edited values (e.g. `20260517.b5efd9eb`) still render
+  // with date-only when possible, otherwise we just show the raw text.
+  const formatBuildStamp = (build: string | undefined) => {
+    if (!build) return null;
+    const m = build.match(
+      /^(\d{4})(\d{2})(\d{2})(?:T(\d{2})(\d{2}))?\.[A-Fa-f0-9]+$/,
+    );
+    if (!m) return null;
+    const [, y, mo, da, hh, mm] = m;
+    const iso =
+      hh && mm
+        ? `${y}-${mo}-${da}T${hh}:${mm}:00Z`
+        : `${y}-${mo}-${da}T00:00:00Z`;
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime())) return null;
+    return new Intl.DateTimeFormat(i18n.language === "ar" ? "ar" : "en", {
+      dateStyle: "medium",
+      ...(hh && mm ? { timeStyle: "short" } : {}),
+    }).format(d);
+  };
+
  const renderStatusBadge = (resp: SystemVersionResponse | undefined) => {
    if (!resp) return null;
    const map: Record<
@@ -2474,7 +2499,25 @@ function SystemUpdatesPanel() {
                <span className="tabular-nums" data-testid="system-updates-current-build">
                  {data.current.build}
                </span>
+                {formatBuildStamp(data.current.build) && (
+                  <span className="ms-2 text-muted-foreground/80">
+                    ({formatBuildStamp(data.current.build)})
+                  </span>
+                )}
              </div>
+              {data.startedAt && (
+                <div
+                  className="text-xs text-muted-foreground mt-1"
+                  data-testid="system-updates-started-at"
+                >
+                  {t("admin.systemUpdates.serverStartedAt")}:{" "}
+                  {formatChecked(
+                    typeof data.startedAt === "string"
+                      ? data.startedAt
+                      : (data.startedAt as Date).toISOString(),
+                  )}
+                </div>
+              )}
            </div>

            <div className="rounded-xl border border-slate-200 p-4 bg-slate-50/60">
@@ -43,6 +43,16 @@ services:
    build:
      context: .
      dockerfile: docker/api-server.Dockerfile
+      # Stamped into version.json inside the image so the admin
+      # "System Updates" panel can show *which* code is running.
+      # `scripts/redeploy.sh` exports both before calling `build`.
+      # If you call `docker compose build` by hand, pass them too:
+      #   GIT_SHA=$(git rev-parse --short HEAD) \
+      #   BUILD_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
+      #   docker compose up -d --build api
+      args:
+        GIT_SHA: ${GIT_SHA:-unknown}
+        BUILD_DATE: ${BUILD_DATE:-unknown}
    image: tx-os/api-server:latest
    restart: unless-stopped
    depends_on:
@@ -32,11 +32,23 @@ RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
    pnpm install --frozen-lockfile --ignore-scripts

 FROM deps AS build
+# Build-time stamp. Pass these from `docker compose build` so the
+# admin "System Updates" panel can show *which* code is running, not
+# just whatever is hard-coded in version.json. When the args are not
+# provided (e.g. someone running `docker build` by hand), we leave
+# version.json untouched.
+ARG GIT_SHA=""
+ARG BUILD_DATE=""
 COPY tsconfig.base.json* tsconfig.json* ./
 COPY version.json ./
 COPY lib lib
 COPY scripts scripts
 COPY artifacts/api-server artifacts/api-server
+RUN if [ -n "$GIT_SHA" ] && [ -n "$BUILD_DATE" ] && [ "$GIT_SHA" != "unknown" ] && [ "$BUILD_DATE" != "unknown" ]; then \
+      GIT_SHA="$GIT_SHA" BUILD_DATE="$BUILD_DATE" node -e "const fs=require('fs');const p='./version.json';const v=JSON.parse(fs.readFileSync(p,'utf8'));const d=String(process.env.BUILD_DATE||'').replace(/[-:]/g,'').replace(/\..*$/,'').slice(0,13);v.build=(d||'unknownDate')+'.'+(process.env.GIT_SHA||'unknownSha');fs.writeFileSync(p,JSON.stringify(v,null,2)+'\n');console.log('Stamped build:',v.build);" ; \
+    else \
+      echo "No GIT_SHA/BUILD_DATE provided — keeping version.json as-is" ; \
+    fi
 RUN pnpm --filter @workspace/api-server run build

 FROM base AS runtime
@@ -33,6 +33,12 @@ export interface SystemVersionResponse {
  /** @nullable */
  checkedAt: string | null;
  configured: boolean;
+  /** ISO-8601 timestamp captured when the API process booted.
+Frozen for the lifetime of the process — used by the admin
+System Updates panel as visible proof that the container
+actually restarted (independent of build/version changes).
+ */
+  startedAt: string;
 }

 export interface ErrorResponse {
@@ -2977,6 +2977,14 @@ components:
          format: date-time
        configured:
          type: boolean
+        startedAt:
+          type: string
+          format: date-time
+          description: |
+            ISO-8601 timestamp captured when the API process booted.
+            Frozen for the lifetime of the process — used by the admin
+            System Updates panel as visible proof that the container
+            actually restarted (independent of build/version changes).
      required:
        - current
        - latest
@@ -2984,6 +2992,7 @@ components:
        - errorMessage
        - checkedAt
        - configured
+        - startedAt

    ErrorResponse:
      type: object
@@ -43,6 +43,11 @@ export const GetSystemVersionResponse = zod.object({
  errorMessage: zod.string().nullable(),
  checkedAt: zod.coerce.date().nullable(),
  configured: zod.boolean(),
+  startedAt: zod.coerce
+    .date()
+    .describe(
+      "ISO-8601 timestamp captured when the API process booted.\nFrozen for the lifetime of the process — used by the admin\nSystem Updates panel as visible proof that the container\nactually restarted (independent of build\/version changes).\n",
+    ),
 });

 /**
@@ -79,6 +79,13 @@ else
 fi

 step "2/5  docker compose build api web  (rebuilds SPA + API images)"
+# Stamp the API image with the current git SHA + UTC build time so the
+# admin "System Updates" panel shows visible proof that the new image
+# is actually running (instead of the old, hand-edited version.json).
+# Both are read inside docker/api-server.Dockerfile as ARGs.
+export GIT_SHA="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
+export BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo "[redeploy]   GIT_SHA=$GIT_SHA  BUILD_DATE=$BUILD_DATE"
 "${DC[@]}" build api web

 step "3/5  docker compose run --rm migrate  (schema push + tolerant seed)"