fix(build): stamp runtime postbuild artifacts

scripts/lib/local-build-metadata-paths.d.mts

@@ -0,0 +1,7 @@
+export const BUILD_STAMP_FILE: ".buildstamp";
+export const RUNTIME_POSTBUILD_STAMP_FILE: ".runtime-postbuildstamp";
+export const LOCAL_BUILD_METADATA_DIST_PATHS: readonly [
+  "dist/.buildstamp",
+  "dist/.runtime-postbuildstamp",
+];
+export function isLocalBuildMetadataDistPath(relativePath: string): boolean;

scripts/lib/local-build-metadata-paths.mjs

@@ -0,0 +1,13 @@
+export const BUILD_STAMP_FILE = ".buildstamp";
+export const RUNTIME_POSTBUILD_STAMP_FILE = ".runtime-postbuildstamp";
+
+export const LOCAL_BUILD_METADATA_DIST_PATHS = Object.freeze([
+  `dist/${BUILD_STAMP_FILE}`,
+  `dist/${RUNTIME_POSTBUILD_STAMP_FILE}`,
+]);
+
+const LOCAL_BUILD_METADATA_DIST_PATH_SET = new Set(LOCAL_BUILD_METADATA_DIST_PATHS);
+
+export function isLocalBuildMetadataDistPath(relativePath) {
+  return LOCAL_BUILD_METADATA_DIST_PATH_SET.has(relativePath);
+}

scripts/lib/local-build-metadata.d.mts

@@ -0,0 +1,43 @@
+export {
+  BUILD_STAMP_FILE,
+  LOCAL_BUILD_METADATA_DIST_PATHS,
+  RUNTIME_POSTBUILD_STAMP_FILE,
+  isLocalBuildMetadataDistPath,
+} from "./local-build-metadata-paths.mjs";
+
+export function resolveGitHead(params?: {
+  cwd?: string;
+  spawnSync?: (
+    cmd: string,
+    args: string[],
+    options: unknown,
+  ) => { status: number | null; stdout?: string | null };
+}): string | null;
+
+export function writeBuildStamp(params?: {
+  cwd?: string;
+  fs?: {
+    mkdirSync(path: string, options?: { recursive?: boolean }): void;
+    writeFileSync(path: string, data: string, encoding?: string): void;
+  };
+  now?: () => number;
+  spawnSync?: (
+    cmd: string,
+    args: string[],
+    options: unknown,
+  ) => { status: number | null; stdout?: string | null };
+}): string;
+
+export function writeRuntimePostBuildStamp(params?: {
+  cwd?: string;
+  fs?: {
+    mkdirSync(path: string, options?: { recursive?: boolean }): void;
+    writeFileSync(path: string, data: string, encoding?: string): void;
+  };
+  now?: () => number;
+  spawnSync?: (
+    cmd: string,
+    args: string[],
+    options: unknown,
+  ) => { status: number | null; stdout?: string | null };
+}): string;

scripts/lib/local-build-metadata.mjs

@@ -0,0 +1,79 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import {
+  BUILD_STAMP_FILE,
+  LOCAL_BUILD_METADATA_DIST_PATHS,
+  RUNTIME_POSTBUILD_STAMP_FILE,
+  isLocalBuildMetadataDistPath,
+} from "./local-build-metadata-paths.mjs";
+
+export {
+  BUILD_STAMP_FILE,
+  LOCAL_BUILD_METADATA_DIST_PATHS,
+  RUNTIME_POSTBUILD_STAMP_FILE,
+  isLocalBuildMetadataDistPath,
+};
+
+export function resolveGitHead(params = {}) {
+  const cwd = params.cwd ?? process.cwd();
+  const spawnSyncImpl = params.spawnSync ?? spawnSync;
+  try {
+    const result = spawnSyncImpl("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (result.status !== 0) {
+      return null;
+    }
+    const head = (result.stdout ?? "").trim();
+    return head || null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeBuildStamp(params = {}) {
+  const cwd = params.cwd ?? process.cwd();
+  const fsImpl = params.fs ?? fs;
+  const now = params.now ?? Date.now;
+  const distRoot = path.join(cwd, "dist");
+  const buildStampPath = path.join(distRoot, BUILD_STAMP_FILE);
+  const head = resolveGitHead({
+    cwd,
+    spawnSync: params.spawnSync,
+  });
+
+  fsImpl.mkdirSync(distRoot, { recursive: true });
+  fsImpl.writeFileSync(buildStampPath, `${JSON.stringify({ builtAt: now(), head })}\n`, "utf8");
+  return buildStampPath;
+}
+
+export function writeRuntimePostBuildStamp(params = {}) {
+  const cwd = params.cwd ?? process.cwd();
+  const fsImpl = params.fs ?? fs;
+  const now = params.now ?? Date.now;
+  const distRoot = path.join(cwd, "dist");
+  const stampPath = path.join(distRoot, RUNTIME_POSTBUILD_STAMP_FILE);
+  const head = resolveGitHead({
+    cwd,
+    spawnSync: params.spawnSync,
+  });
+
+  fsImpl.mkdirSync(distRoot, { recursive: true });
+  fsImpl.writeFileSync(
+    stampPath,
+    `${JSON.stringify(
+      {
+        syncedAt: now(),
+        ...(head ? { head } : {}),
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+  return stampPath;
+}