Sandcastle build config updates

.github/workflows/deploy.yml

@@ -2,7 +2,7 @@ name: deploy
 on:
   push:
     branches-ignore:
-      - 'cesium.com'
+      - "cesium.com"
       - production
 concurrency:
   group: deploy-${{ github.ref }}
@@ -22,14 +22,13 @@ jobs:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       GITHUB_REPO: ${{ github.repository }}
       GITHUB_SHA: ${{ github.sha }}
-      BASE_URL: /cesium/${{ github.ref_name }}/
       DEPLOYED_URL: https://ci-builds.cesium.com/cesium/${{ github.ref_name }}/
     steps:
       - uses: actions/checkout@v5
       - name: install node 22
         uses: actions/setup-node@v6
         with:
-          node-version: '22'
+          node-version: "22"
       - name: npm install
         run: npm install
       - name: set the version in package.json
@@ -42,8 +41,6 @@ jobs:
         run: npm pack --workspaces &> /dev/null
       - name: build apps
         run: npm run build-apps
-      - name: build sandcastle v2
-        run: npm run build-ci -w packages/sandcastle -- -l warn
       - uses: ./.github/actions/verify-package
       - name: deploy to s3
         if: ${{ env.AWS_ACCESS_KEY_ID != '' }}

.github/workflows/prod.yml

@@ -41,14 +41,17 @@ jobs:
         run: npm install
       - name: build website release
         run: npm run website-release
-      - name: build apps
-        run: npm run build-apps
       - name: build types
         run: npm run build-ts
-      - name: build prod sandcastle
-        run: npm run build-prod -w packages/sandcastle -- -l warn
+      - name: build apps
+        run: npm run build-apps
       - name: deploy to cesium.com
         if: ${{ env.AWS_ACCESS_KEY_ID != '' }}
+        # Download zip from the Github release and unzip to Build/release/
+        # Publish that unzipped code to the bucket for https://cesium.com/downloads/cesiumjs/releases/[version]/... urls
+        # Publish the documentation files to the bucket for https://cesium.com/learn/cesiumjs/ref-doc/
+        # Publish the simple viewer app to the bucket for https://cesium.com/cesiumjs/cesium-viewer/
+        # Publish sandcastle to the bucket for https://sandcastle.cesium.com/
         run: |
           curl -LO $(curl https://api.github.com/repos/CesiumGS/cesium/releases/latest -H "Authorization: ${GITHUB_TOKEN}" | jq -r '.assets[0].browser_download_url')
           unzip Cesium-$(cat package.json | jq -r '.version' | sed 's/\.0$//').zip -d Build/release/ -x "Apps"

.github/workflows/sandcastle-dev.yml

@@ -2,7 +2,7 @@ name: sandcastle-dev
 on:
   push:
     branches:
-      - 'cesium.com'
+      - "main"
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -20,15 +20,15 @@ jobs:
       - name: install node 22
         uses: actions/setup-node@v6
         with:
-          node-version: '22'
+          node-version: "22"
       - name: npm install
         run: npm install
       - name: build website release
         run: npm run website-release
       - name: build types
         run: npm run build-ts
       - name: build prod sandcastle
-        run: npm run build-prod -w packages/sandcastle -- -l warn
+        run: npm run build-sandcastle
       - name: deploy to dev-sandcastle.cesium.com
         if: ${{ env.AWS_ACCESS_KEY_ID != '' }}
         run: |

gulpfile.js

@@ -30,6 +30,7 @@ import {
   createCombinedSpecList,
   createJsHintOptions,
   defaultESBuildOptions,
+  buildSandcastleApp,
 } from "./scripts/build.js";
 
 // Determines the scope of the workspace packages. If the scope is set to cesium, the workspaces should be @cesium/engine.
@@ -55,7 +56,7 @@ function getWorkspaces(onlyDependencies = false) {
 }
 
 const devDeployUrl = process.env.DEPLOYED_URL;
-const isProduction = process.env.PROD;
+const isProduction = process.env.PROD === "true";
 
 //Gulp doesn't seem to have a way to get the currently running tasks for setting
 //per-task variables.  We use the command line argument here to detect which task is being run.
@@ -287,10 +288,19 @@ export async function buildTs() {
   await createTypeScriptDefinitions();
 }
 
-export function buildApps() {
-  return Promise.all([buildCesiumViewer(), buildSandcastle()]);
+export async function buildSandcastle() {
+  return buildSandcastleApp({
+    outputToBuildDir: isProduction,
+    includeDevelopment: !isProduction,
+  });
 }
 
+export const buildApps = gulp.parallel(
+  buildCesiumViewer,
+  buildLegacySandcastle,
+  buildSandcastle,
+);
+
 const filesToClean = [
   "Source/Cesium.js",
   "Source/Shaders/**/*.js",
@@ -582,121 +592,129 @@ async function pruneScriptsForZip(packageJsonPath) {
   });
 }
 
-export const makeZip = gulp.series(release, async function createZipFile() {
-  //For now we regenerate the JS glsl to force it to be unminified in the release zip
-  //See https://github.com/CesiumGS/cesium/pull/3106#discussion_r42793558 for discussion.
-  await glslToJavaScript(false, "Build/minifyShaders.state", "engine");
-
-  const packageJsonSrc = await pruneScriptsForZip("package.json");
-  const enginePackageJsonSrc = await pruneScriptsForZip(
-    "packages/engine/package.json",
-  );
-  const widgetsPackageJsonSrc = await pruneScriptsForZip(
-    "packages/widgets/package.json",
-  );
+export const makeZip = gulp.series(
+  release,
+  async function buildSandcastleStep() {
+    return buildSandcastleApp({
+      outputToBuildDir: false,
+      includeDevelopment: false,
+    });
+  },
+  async function createZipFile() {
+    //For now we regenerate the JS glsl to force it to be unminified in the release zip
+    //See https://github.com/CesiumGS/cesium/pull/3106#discussion_r42793558 for discussion.
+    await glslToJavaScript(false, "Build/minifyShaders.state", "engine");
+
+    const packageJsonSrc = await pruneScriptsForZip("package.json");
+    const enginePackageJsonSrc = await pruneScriptsForZip(
+      "packages/engine/package.json",
+    );
+    const widgetsPackageJsonSrc = await pruneScriptsForZip(
+      "packages/widgets/package.json",
+    );
 
-  const src = gulp
-    .src("index.release.html")
-    .pipe(
-      gulpRename((file) => {
-        if (file.basename === "index.release") {
-          file.basename = "index";
-        }
-      }),
-    )
-    .pipe(enginePackageJsonSrc)
-    .pipe(widgetsPackageJsonSrc)
-    .pipe(packageJsonSrc)
-    .pipe(
-      gulpRename((file) => {
-        if (file.basename === "package.noprepare") {
-          file.basename = "package";
-        }
-      }),
-    )
-    .pipe(
-      gulp.src(
-        [
-          "Build/Cesium/**",
-          "Build/CesiumUnminified/**",
-          "Build/Documentation/**",
-          "Build/Specs/**",
-          "Build/package.json",
-          "packages/engine/Build/**",
-          "packages/widgets/Build/**",
-          "!Build/Specs/e2e/**",
-          "!Build/InlineWorkers.js",
-          "!packages/engine/Build/Specs/**",
-          "!packages/widgets/Build/Specs/**",
-          "!packages/engine/Build/minifyShaders.state",
-        ],
-        {
-          encoding: false,
-          base: ".",
-        },
-      ),
-    )
-    .pipe(
-      gulp.src(
-        [
-          "Apps/**",
-          "Apps/Sandcastle/.jshintrc",
-          "packages/engine/index.js",
-          "packages/engine/index.d.ts",
-          "packages/engine/LICENSE.md",
-          "packages/engine/README.md",
-          "packages/engine/Source/**",
-          "packages/widgets/index.js",
-          "packages/widgets/index.d.ts",
-          "packages/widgets/LICENSE.md",
-          "packages/widgets/README.md",
-          "packages/widgets/Source/**",
-          "Source/**",
-          "Specs/**",
-          "ThirdParty/**",
-          "scripts/**",
-          "favicon.ico",
-          ".prettierignore",
-          "eslint.config.js",
-          "gulpfile.js",
-          "server.js",
-          "index.cjs",
-          "LICENSE.md",
-          "CHANGES.md",
-          "README.md",
-          "web.config",
-          "!**/*.gitignore",
-          "!Specs/e2e/*-snapshots/**",
-          "!Apps/Sandcastle/gallery/development/**",
-          "!Apps/Sandcastle2/**",
-        ],
-        {
-          encoding: false,
-          base: ".",
-        },
-      ),
-    )
-    .pipe(
-      gulpTap(function (file) {
-        // Work around an issue with gulp-zip where archives generated on Windows do
-        // not properly have their directory executable mode set.
-        // see https://github.com/sindresorhus/gulp-zip/issues/64#issuecomment-205324031
-        if (file.isDirectory()) {
-          file.stat.mode = parseInt("40777", 8);
-        }
-      }),
-    )
-    .pipe(gulpZip(`Cesium-${version}.zip`))
-    .pipe(gulp.dest("."));
+    const src = gulp
+      .src("index.release.html")
+      .pipe(
+        gulpRename((file) => {
+          if (file.basename === "index.release") {
+            file.basename = "index";
+          }
+        }),
+      )
+      .pipe(enginePackageJsonSrc)
+      .pipe(widgetsPackageJsonSrc)
+      .pipe(packageJsonSrc)
+      .pipe(
+        gulpRename((file) => {
+          if (file.basename === "package.noprepare") {
+            file.basename = "package";
+          }
+        }),
+      )
+      .pipe(
+        gulp.src(
+          [
+            "Build/Cesium/**",
+            "Build/CesiumUnminified/**",
+            "Build/Documentation/**",
+            "Build/Specs/**",
+            "Build/package.json",
+            "packages/engine/Build/**",
+            "packages/widgets/Build/**",
+            "!Build/Specs/e2e/**",
+            "!Build/InlineWorkers.js",
+            "!packages/engine/Build/Specs/**",
+            "!packages/widgets/Build/Specs/**",
+            "!packages/engine/Build/minifyShaders.state",
+          ],
+          {
+            encoding: false,
+            base: ".",
+          },
+        ),
+      )
+      .pipe(
+        gulp.src(
+          [
+            "Apps/**",
+            "Apps/Sandcastle/.jshintrc",
+            "packages/engine/index.js",
+            "packages/engine/index.d.ts",
+            "packages/engine/LICENSE.md",
+            "packages/engine/README.md",
+            "packages/engine/Source/**",
+            "packages/widgets/index.js",
+            "packages/widgets/index.d.ts",
+            "packages/widgets/LICENSE.md",
+            "packages/widgets/README.md",
+            "packages/widgets/Source/**",
+            "Source/**",
+            "Specs/**",
+            "ThirdParty/**",
+            "scripts/**",
+            "favicon.ico",
+            ".prettierignore",
+            "eslint.config.js",
+            "gulpfile.js",
+            "server.js",
+            "index.cjs",
+            "LICENSE.md",
+            "CHANGES.md",
+            "README.md",
+            "web.config",
+            "!**/*.gitignore",
+            "!Specs/e2e/*-snapshots/**",
+            "!Apps/Sandcastle/gallery/development/**",
+          ],
+          {
+            encoding: false,
+            base: ".",
+          },
+        ),
+      )
+      .pipe(
+        gulpTap(function (file) {
+          // Work around an issue with gulp-zip where archives generated on Windows do
+          // not properly have their directory executable mode set.
+          // see https://github.com/sindresorhus/gulp-zip/issues/64#issuecomment-205324031
+          if (file.isDirectory()) {
+            file.stat.mode = parseInt("40777", 8);
+          }
+        }),
+      )
+      .pipe(gulpZip(`Cesium-${version}.zip`))
+      .pipe(gulp.dest("."));
 
-  await finished(src);
+    await finished(src);
 
-  rimraf.sync("./package.noprepare.json");
-  rimraf.sync("./packages/engine/package.noprepare.json");
-  rimraf.sync("./packages/widgets/package.noprepare.json");
+    rimraf.sync("./package.noprepare.json");
+    rimraf.sync("./packages/engine/package.noprepare.json");
+    rimraf.sync("./packages/widgets/package.noprepare.json");
 
-  return src;
-});
+    return src;
+  },
+);
 
 export async function deploySetVersion() {
   const buildVersion = argv.buildVersion;
@@ -1239,13 +1257,6 @@ function generateTypeScriptDefinitions(
       "raiseEvent(...arguments: Parameters<Listener>): void;",
     );
 
-  // Wrap the source to actually be inside of a declared cesium module
-  // and add any workaround and private utility types.
-  source = `declare module "@${scope}/${workspaceName}" {
-${source}
-}
-`;
-
   if (importModules) {
     let imports = "";
     Object.keys(importModules).forEach((workspace) => {
@@ -1259,6 +1270,13 @@ ${source}
     source = imports + source;
   }
 
+  // Wrap the source to actually be inside of a declared cesium module
+  // and add any workaround and private utility types.
+  source = `declare module "@${scope}/${workspaceName}" {
+${source}
+}
+`;
+
   // Write the final source file back out
   writeFileSync(definitionsPath, source);
 
@@ -1631,7 +1649,7 @@ export async function buildThirdParty() {
   return writeFile("ThirdParty.json", JSON.stringify(licenseJson, null, 2));
 }
 
-async function buildSandcastle() {
+async function buildLegacySandcastle() {
   const streams = [];
   let appStream = gulp.src(
     [