fix(docs-bundle): dedupe dotenv loader, drop compat re-export, serialize CDN uploads

Move loadDotenvIfAvailable into oss-cdn.mjs instead of defining it twice
in upload-openapi.mjs and upload-docs-bundle.mjs. Drop upload-openapi.mjs's
re-export of requiredEnv/validateRequiredEnv now that its test imports
validateRequiredEnv from oss-cdn.mjs directly. Add a concurrency group to
docs-bundle-upload.yml so two pushes to the same branch in quick
succession can't finish out of order and leave a stale tarball on the CDN.

Author: ysyneu

.github/workflows/docs-bundle-upload.yml

@@ -3,6 +3,10 @@ name: Upload docs bundle to OSS
 env:
   CDN_URL: 'https://docs-cdn.flashcat.cloud'
 
+concurrency:
+  group: docs-bundle-upload-${{ github.ref }}
+  cancel-in-progress: true
+
 on:
   push:
     branches: [main, test]

integration-docs/scripts/oss-cdn.mjs

@@ -51,3 +51,16 @@ export async function refreshCdnCache(cdnRuntime, url) {
   await cdnRuntime.client.refreshObjectCaches(request);
   console.log(`Refreshed CDN cache: ${url}`);
 }
+
+// Load .env for local runs. Tolerate 'dotenv' not being installed (e.g. a
+// pruned install) rather than failing scripts that get their env from CI.
+export async function loadDotenvIfAvailable() {
+  try {
+    const { default: dotenv } = await import('dotenv');
+    dotenv.config();
+  } catch (err) {
+    if (err.code !== 'ERR_MODULE_NOT_FOUND') {
+      throw err;
+    }
+  }
+}

integration-docs/scripts/upload-docs-bundle.mjs

@@ -5,6 +5,7 @@ import { buildCdnUrl } from './cdn-url.mjs';
 import {
   createCdnRuntime,
   createOssClient,
+  loadDotenvIfAvailable,
   normalizeCdnDir,
   refreshCdnCache,
   validateRequiredEnv
@@ -54,17 +55,6 @@ export async function uploadDocsBundle({
   return cdnUrl;
 }
 
-async function loadDotenvIfAvailable() {
-  try {
-    const { default: dotenv } = await import('dotenv');
-    dotenv.config();
-  } catch (err) {
-    if (err.code !== 'ERR_MODULE_NOT_FOUND') {
-      throw err;
-    }
-  }
-}
-
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   await loadDotenvIfAvailable();
   await uploadDocsBundle();

integration-docs/scripts/upload-openapi.mjs

@@ -5,9 +5,9 @@ import { buildCdnUrl } from './cdn-url.mjs';
 import {
   createCdnRuntime,
   createOssClient,
+  loadDotenvIfAvailable,
   normalizeCdnDir,
   refreshCdnCache,
-  requiredEnv,
   validateRequiredEnv
 } from './oss-cdn.mjs';
 
@@ -18,8 +18,6 @@ const defaultApiReferenceDir = path.join(repoRoot, 'api-reference');
 const docsBaseUrl = 'https://docs.flashcat.cloud';
 const httpMethods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
 
-export { requiredEnv, validateRequiredEnv };
-
 export function listOpenapiJsonFiles(apiReferenceDir = defaultApiReferenceDir) {
   if (!fs.existsSync(apiReferenceDir)) {
     throw new Error(`OpenAPI directory does not exist: ${apiReferenceDir}`);
@@ -137,17 +135,6 @@ export async function uploadOpenapiJsonFiles({
   console.log(`Uploaded ${files.length} OpenAPI JSON files and manifest from ${apiReferenceDir}`);
 }
 
-async function loadDotenvIfAvailable() {
-  try {
-    const { default: dotenv } = await import('dotenv');
-    dotenv.config();
-  } catch (err) {
-    if (err.code !== 'ERR_MODULE_NOT_FOUND') {
-      throw err;
-    }
-  }
-}
-
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   await loadDotenvIfAvailable();
   await uploadOpenapiJsonFiles();

integration-docs/scripts/upload-openapi.test.mjs

@@ -4,12 +4,12 @@ import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
 
+import { validateRequiredEnv } from './oss-cdn.mjs';
 import {
   buildOpenapiReferenceIndex,
   buildOssFilePath,
   listOpenapiJsonFiles,
-  uploadOpenapiJsonFiles,
-  validateRequiredEnv
+  uploadOpenapiJsonFiles
 } from './upload-openapi.mjs';
 
 test('listOpenapiJsonFiles returns only direct JSON files sorted by name', () => {