feat: Cornerstone3D 5.0

.agents/skills/metadata-migration.md

@@ -0,0 +1,44 @@
+---
+name: metadata-migration
+description: Migrate codebases from legacy CS3D metadata flows to the metadata branch model with required init/provider updates and recommended provider/cache/imageId changes.
+---
+
+# Metadata Migration Skill (`origin/main` -> `metadata`)
+
+Use this skill to migrate codebases from the legacy CS3D metadata flow in
+`origin/main` to the `metadata` branch model.
+
+## Mandated changes
+
+1. Add the metadata module.
+2. Re-add required providers after each CS3D init call.
+
+### Required checklist
+
+- Add and initialize the metadata module in bootstrap/startup.
+- Ensure provider registration runs after CS3D init.
+- Re-register all providers needed by your workflows after init.
+- Confirm provider priority/ordering where providers overlap.
+
+## Recommended changes
+
+1. Use metadata module imports instead of legacy import paths.
+2. Switch to new metadata providers and deprecate old providers.
+3. Adopt the new caching model.
+4. Adopt the `imageId` / `frameImageId` storage model.
+
+## Compatibility notes
+
+- Some providers are not yet available in both old and new schemes.
+- Do not block migration on full parity.
+- Keep temporary fallback providers only where required.
+- Track and remove fallbacks as equivalent providers become available.
+
+## Suggested migration sequence
+
+1. Add metadata module and initialize it.
+2. Move provider registration to post-init and re-add required providers.
+3. Validate key metadata workflows and provider lookups.
+4. Replace old imports with metadata module imports.
+5. Migrate providers to new implementations where available.
+6. Incrementally adopt new cache and `imageId`/`frameImageId` storage.

.circleci/config.yml

@@ -5,29 +5,27 @@ defaults: &defaults
   working_directory: ~/repo
   # https://circleci.com/docs/2.0/circleci-images/#language-image-variants
   docker:
-    - image: cimg/node:20.18.1-browsers
+    - image: cimg/node:24.0.0-browsers
       environment:
         TERM: xterm # Enable colors in term
 
 commands:
-  install_bun:
+  install_pnpm:
     steps:
       - run:
-          name: Install Bun
+          name: Install pnpm
           command: |
-            curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.23"
-            echo 'export BUN_INSTALL="$HOME/.bun"' >> $BASH_ENV
-            echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> $BASH_ENV
-            source $BASH_ENV
+            sudo corepack enable
+            pnpm --version
 
 jobs:
   CHECKOUT:
     <<: *defaults
     steps:
       - checkout
       - run: echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/repo/.npmrc
-      - install_bun
-      # SECURITY AUDIT - only when bun.lock has changed
+      - install_pnpm
+      # SECURITY AUDIT - only when pnpm-lock.yaml has changed
       - run:
           name: 'Security Audit - High Risk Vulnerabilities'
           command: |
@@ -38,30 +36,14 @@ jobs:
               exit 0
             fi
             CHANGED_FILES=$(git diff --name-only origin/main...HEAD 2>/dev/null || echo "")
-            if ! echo "$CHANGED_FILES" | grep -qx 'bun.lock'; then
-              echo "⏭️ bun.lock unchanged - skipping security audit."
+            if ! echo "$CHANGED_FILES" | grep -qx 'pnpm-lock.yaml'; then
+              echo "⏭️ pnpm-lock.yaml unchanged - skipping security audit."
               exit 0
             fi
-            echo "🔍 bun.lock changed - running bun audit for security vulnerabilities..."
+            echo "🔍 pnpm-lock.yaml changed - running pnpm audit for security vulnerabilities..."
             echo "Checking for HIGH-RISK vulnerabilities..."
 
-            # Define ignored vulnerabilities with comments
-            IGNORED_VULNS=(
-              "GHSA-5j98-mcp5-4vw2"  # CVE-2025-64756 - glob is strictly for building and CI/CD purposes
-              "GHSA-3ppc-4f35-3m26"  # CVE-2026-26996 - minimatch via itk-wasm and glob is safe because it does NOT use the CLI
-                                     # CVE-2026-26996 - minimatch via other packages are strictly for building and CI/CD purposes; no user supplied expressions are passed to minimatch
-              "GHSA-7r86-cg39-jmmj"  # CVE-2026-27903 - minimatch same as above
-              "GHSA-23c5-xmqv-rm74"  # CVE-2026-27904 - minimatch same as above
-              "GHSA-c2c7-rcm5-vvqj"  # CVE-2026-33671 - picomatch is generally used for development and CI/CD purposes
-            )
-
-            # Build ignore flags
-            IGNORE_FLAGS=""
-            for vuln in "${IGNORED_VULNS[@]}"; do
-              IGNORE_FLAGS="$IGNORE_FLAGS --ignore=$vuln"
-            done
-
-            if bun audit $IGNORE_FLAGS --audit-level high; then
+            if pnpm audit --audit-level high; then
               echo "✅ No high-risk vulnerabilities found"
               echo "🎉 Security audit passed!"
             else
@@ -70,21 +52,21 @@ jobs:
               echo "======================================"
               echo ""
               echo "🔧 To fix these issues:"
-              echo "  1. Run: bun audit"
+              echo "  1. Run: pnpm audit"
               echo "  2. Review the vulnerability details"
               echo "  3. Update affected packages to secure versions"
               echo "  4. Test your changes"
-              echo "  5. Re-run: bun audit --audit-level high"
+              echo "  5. Re-run: pnpm audit --audit-level high"
               echo ""
               echo "📋 Full audit report:"
 
-              bun audit $IGNORE_FLAGS --audit-level low || true
+              pnpm audit || true
 
               echo ""
               echo "❌ This build cannot proceed until high-risk vulnerabilities are resolved."
               exit 1
             fi
-      - run: bun install
+      - run: pnpm install --frozen-lockfile
       - persist_to_workspace:
           root: ~/repo
           paths:
@@ -95,14 +77,15 @@ jobs:
     steps:
       - attach_workspace:
           at: ~/repo
-      - install_bun
+      - install_pnpm
       - run:
           name: 'Perform the versioning before build'
-          command: bun ./version.mjs
-      - run: bun run build
+          command: node ./version.mjs
+      - run: pnpm run build
       - persist_to_workspace:
           root: ~/repo
           paths:
+            - packages/metadata/dist
             - packages/core/dist
             - packages/tools/dist
             - packages/adapters/dist
@@ -118,7 +101,7 @@ jobs:
     steps:
       - attach_workspace:
           at: ~/repo
-      - install_bun
+      - install_pnpm
       - run:
           name: Avoid hosts unknown for github
           command:
@@ -133,14 +116,14 @@ jobs:
       - run:
           name: publish package versions
           command: |
-            bun ./publish-version.mjs
+            node ./publish-version.mjs
       - run:
           name: Again set the NPM registry (was deleted in the version script)
           command: echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ~/repo/.npmrc
       - run:
           name: publish package dist
           command: |
-            bun ./publish-package.mjs
+            node ./publish-package.mjs
 
 workflows:
   version: 2
@@ -171,7 +154,11 @@ workflows:
       - BUILD:
           requires:
             - CHECKOUT
-      - NPM_PUBLISH:
+      - HOLD_FOR_APPROVAL:
+          type: approval
           requires:
             - BUILD
+      - NPM_PUBLISH:
+          requires:
+            - HOLD_FOR_APPROVAL
 # VS Code Extension Version: 1.5.1

.github/workflows/build-docs.yml

@@ -23,15 +23,16 @@ jobs:
       pull-requests: read
     steps:
       - uses: actions/checkout@v4
-      - uses: oven-sh/setup-bun@v2
+      - uses: pnpm/action-setup@v4
         with:
-          bun-version: 1.2.23
+          version: 11.4.0
       - uses: actions/setup-node@v4
         with:
-          node-version: 20 # Or your desired Node version
+          node-version: '24'
+          cache: 'pnpm'
 
       - name: Install root dependencies
-        run: bun install --frozen-lockfile
+        run: pnpm install --frozen-lockfile
 
       # Removed Playwright tests and coverage generation steps
 
@@ -83,7 +84,7 @@ jobs:
           echo "Artifact downloaded successfully."
 
       - name: Install docs dependencies
-        run: cd packages/docs && bun install
+        run: pnpm install --frozen-lockfile
 
       - name: Copy coverage to docs static directory
         run: |
@@ -100,7 +101,7 @@ jobs:
           cp ./coverage-artifact/sorter.js packages/docs/static/
 
       - name: Build docs
-        run: cd packages/docs && bun run build:docs
+        run: pnpm --filter docs run build:docs
         # This runs
         # 1. prepare-markdown-files.js - which copies markdown files to /docs/llm directory
         #    making them available at cornerstonejs.org/docs/llm/[folder]/[filename.md]
@@ -110,7 +111,7 @@ jobs:
         #    the concatenated content of all documentation files
 
       - name: Install Netlify CLI
-        run: bun add -g netlify-cli
+        run: pnpm add -g netlify-cli
 
       - name: Deploy to Netlify
         run: |

.github/workflows/docusaurus-build.yml

@@ -22,37 +22,25 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
         with:
-          node-version: '20.18.1'
-          cache: 'npm'
+          version: 11.4.0
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
-          bun-version: 1.2.23
+          node-version: '24'
+          cache: 'pnpm'
 
       - name: Install root dependencies
-        run: bun install --frozen-lockfile
-
-      - name: reset nx cache
-        run: rm -rf .nx/cache
-
-      - name: reset nx cache
-        run: bun nx reset
+        run: pnpm install --frozen-lockfile
 
       - name: Build packages in ESM format
-        run: bun run build:esm
-        env:
-          NX_CACHE_DIRECTORY: ${{ runner.temp }}/nx-cache
-          NX_DAEMON: false
-
-      - name: Install docs dependencies
-        run: cd packages/docs && bun install
+        run: pnpm run build:esm
 
       - name: Build Docusaurus documentation
-        run: cd packages/docs && bun run build:ci
+        run: pnpm --filter docs run build:ci
         env:
           NODE_OPTIONS: --max_old_space_size=32384
 

.github/workflows/format-check.yml

@@ -19,22 +19,22 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
         with:
-          node-version: '20.18.1'
-          cache: 'npm'
+          version: 11.4.0
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
-          bun-version: 1.2.23
+          node-version: '24'
+          cache: 'pnpm'
 
       - name: Install dependencies
-        run: bun install
+        run: pnpm install --frozen-lockfile
 
       - name: Run lint
-        run: bun run lint
+        run: pnpm run lint
 
       - name: Run format check
-        run: bun run format-check
+        run: pnpm run format-check

.github/workflows/ohif-downstream.yml

@@ -28,8 +28,10 @@ jobs:
     runs-on: self-hosted
     timeout-minutes: 120
     env:
-      BUN_VERSION: 1.3.11
+      PNPM_VERSION: 11.4.0
+      BUN_VERSION: 1.2.23
       NODE_VERSION: 24
+      OHIF_REF: master
       OHIF_DIR: ohif
       # Update to force a rebuild of the OHIF integration
       BUILD_INDEX: 0
@@ -60,6 +62,14 @@ jobs:
           echo "[build-context] OHIF ref: ${{ env.OHIF_REF }}"
           echo "[build-context] ═══════════════════════════════════════════════════════════════"
 
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+
+      # OHIF (a bun/yarn project) is installed with bun so it gets an isolated
+      # node_modules instead of being pulled into this repo's pnpm workspace,
+      # which mixes jest copies and breaks jest-runner (leakDetector error).
       - name: Set up Bun
         uses: oven-sh/setup-bun@v2
         with:
@@ -69,12 +79,13 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: ${{ env.NODE_VERSION }}
+          cache: 'pnpm'
 
       - name: Install Cornerstone dependencies
-        run: bun install --frozen-lockfile
+        run: pnpm install --frozen-lockfile
 
-      - name: Build local Cornerstone packages for OHIF
-        run: bun run build:esm
+      - name: Build local Cornerstone packages for OHIF (includes metadata)
+        run: pnpm run build:esm
 
       - name: Checkout OHIF
         uses: actions/checkout@v4
@@ -99,7 +110,7 @@ jobs:
 
       - name: Install OHIF dependencies
         working-directory: ${{ env.OHIF_DIR }}
-        run: bun install --frozen-lockfile
+        run: bun install
 
       - name: Link local Cornerstone packages into OHIF node_modules
         run: node scripts/link-ohif-cornerstone-node-modules.mjs ${{ env.OHIF_DIR }}
@@ -110,7 +121,7 @@ jobs:
 
       - name: Install Playwright browsers
         working-directory: ${{ env.OHIF_DIR }}
-        run: npx playwright install
+        run: npx playwright install --with-deps chromium
 
       - name: Run OHIF e2e tests
         working-directory: ${{ env.OHIF_DIR }}