Nucleus 3.0

.claude/skills/tag-dev/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: tag-dev
+description: Create and push a timestamped dev tag for Nucleus 3.0 in the format v3.0.0-dev-YYYYMMDDHHMM, publishing runtime modules to Maven Central and the plugin to the Gradle Plugin Portal without running preMerge. Use when the user asks to "publish a dev build", "cut a dev", "tag dev", "publier une version dev", or similar on this project.
+---
+
+# Tag dev — Nucleus 3.0
+
+Creates a timestamped dev tag on the current HEAD and pushes it to `origin`. The tag publishes
+**unverified** artifacts: `.github/workflows/publish-maven.yaml` and `publish-plugin.yaml` skip
+`preMerge` for dev tags, and the desktop / GraalVM release workflows ignore them entirely.
+
+## Format
+
+`v3.0.0-dev-YYYYMMDDHHMM` — e.g. `v3.0.0-dev-202609200830` for Sep 20 2026, 08:30 UTC.
+
+Timestamp components come from `date -u +%Y%m%d%H%M` (UTC, no separators, 12 chars).
+
+The published Maven version is the tag without the leading `v` (`3.0.0-dev-202609200830`), which
+orders below `3.0.0` for Gradle and Maven, so a dev build can never shadow the real release.
+
+## Procedure
+
+1. **Verify the branch is on the 3.0 line** — `nucleus-2.6` (the 3.0 release is cut from it),
+   `nucleus-3.0` if it exists, or a feature branch cut from either. A dev tag on `main` or on the
+   2.5 line would publish a `3.0.0-dev-*` version from the wrong code; abort and say so.
+2. **Verify the working tree is clean** — `git status --porcelain` empty. If dirty, ask the user
+   whether to commit first or abort. Never tag a dirty tree: the tag is what CI builds.
+3. **Verify HEAD is pushed** — `git fetch origin` then check the commit exists on the remote
+   (`git branch -r --contains HEAD`). A tag on an unpushed commit makes CI check out a commit
+   nobody else has; push the branch first (ask before pushing).
+4. **Generate the timestamp** with `date -u +%Y%m%d%H%M`.
+5. **Check the tag doesn't already exist** — `git tag -l v3.0.0-dev-<ts>`. If it does, use the
+   next minute; Maven Central versions are immutable, a retag would publish nothing.
+6. **Create an annotated tag**:
+   ```bash
+   git tag -a "v3.0.0-dev-<ts>" -m "v3.0.0-dev-<ts>"
+   ```
+   Annotated (not lightweight) because the published history uses annotated tags.
+7. **Push the tag**:
+   ```bash
+   git push origin "v3.0.0-dev-<ts>"
+   ```
+8. **Report** the tag name, the commit SHA, the resulting Maven version, and the coordinates a
+   consumer needs, e.g.:
+   ```kotlin
+   implementation("dev.nucleusframework:nucleus.decorated-window-tao:3.0.0-dev-<ts>")
+   ```
+   Mention that Central takes ~15 minutes to expose the version after the workflow goes green.
+
+## Hard rules
+
+- Never tag `main` or the 2.5 line with this format.
+- Never cut a `2.6.0-dev-*` tag anymore: the next release is 3.0.0.
+- Never overwrite or force-push a tag — the version is already on Central and cannot be replaced.
+- Never add `Co-Authored-By` or AI attribution to the tag message (per the project's CLAUDE.md).
+- Tag message body is just the tag name itself — matches the existing convention.
+- The tag must stay `v<major>.<minor>.<patch>-dev-<id>`: `.github/actions/release-tag-info`
+  rejects anything else, because every publish task derives its version by stripping
+  `refs/tags/v` from `GITHUB_REF`.
+
+## When NOT to use this skill
+
+- Stable releases (`v3.0.0`) — those go through the full `preMerge` gate and cut GitHub releases.
+- Alpha/beta/rc prereleases — see the `tag-alpha` skill and `.github/actions/validate-release-ref`.
+- Backporting onto an old commit — this skill always tags `HEAD`.

.github/actions/build-macos-universal/action.yml

@@ -52,6 +52,14 @@ inputs:
     description: 'Path to runtime embedded.provisionprofile for sandboxed app runtime'
     required: false
     default: ''
+  electron-builder-toolchain-dir:
+    description: 'Directory holding the package.json / package-lock.json of the pinned electron-builder toolchain embedded in the Nucleus plugin'
+    required: false
+    default: 'plugin-build/plugin/src/main/resources/nucleus/electron-builder'
+  node-version:
+    description: 'Node.js line to provision (a major like 22, or a pinned x.y.z). Keep in sync with the nativeDistributions { nodejs { version } } default.'
+    required: false
+    default: '22'
 
 outputs:
   zip:
@@ -102,6 +110,22 @@ runs:
           echo "==> No sandboxed ZIPs found (App Store PKG will use electron-builder fallback)"
         fi
 
+    # Same cache entry as setup-nucleus: the provisioning script uses the
+    # plugin's install layout, so a Node.js downloaded by either is reused.
+    - name: Cache Node.js toolchain
+      uses: actions/cache@v6
+      with:
+        path: ~/.gradle/nucleus/nodejs
+        key: nodejs-toolchain-${{ runner.os }}-${{ runner.arch }}-${{ inputs.node-version }}
+
+    - name: Provision Node.js and electron-builder
+      shell: bash
+      env:
+        NODE_LINE: ${{ inputs.node-version }}
+        TOOLCHAIN_DIR: ${{ inputs.electron-builder-toolchain-dir }}
+        TOOL_DIR: ${{ runner.temp }}/electron-builder-tool
+      run: bash "${{ github.action_path }}/provision-electron-builder.sh"
+
     - name: Build universal binary
       id: build
       shell: bash

.github/actions/build-macos-universal/build-universal.sh

@@ -4,7 +4,7 @@
 set -euo pipefail
 
 # ── Required env vars ─────────────────────────────────────────────────────
-: "${ARM64_ZIP:?}" "${X64_ZIP:?}" "${OUTPUT_DIR:?}"
+: "${ARM64_ZIP:?}" "${X64_ZIP:?}" "${OUTPUT_DIR:?}" "${NODE_BIN:?}" "${ELECTRON_BUILDER_CLI:?}"
 
 # ── Optional env vars (default to empty) ──────────────────────────────────
 SIGNING_IDENTITY="${SIGNING_IDENTITY:-}"
@@ -499,8 +499,9 @@ run_electron_builder() {
     codesign --force --deep --sign - "$app_copy"
   fi
 
+  # Provisioned by provision-electron-builder.sh from the plugin's lock file.
   CSC_IDENTITY_AUTO_DISCOVERY=false \
-  npx --yes electron-builder \
+  "$NODE_BIN" "$ELECTRON_BUILDER_CLI" \
     --prepackaged "$app_copy" \
     --config "$eb_dir/electron-builder.yml" \
     --config.electronVersion=33.0.0 \

.github/actions/build-macos-universal/provision-electron-builder.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Provisions the same Node.js and the same pinned electron-builder toolchain the Nucleus plugin
+# uses, for the universal repack — which runs electron-builder outside the plugin.
+#
+# - Node.js: the newest release of $NODE_LINE from nodejs.org, verified against the release's
+#   SHASUMS256.txt, installed with the plugin's layout (NodeToolchainProvisioner):
+#   <install-base>/node-<line>-darwin-<arch>/<archive top dir>/ plus a `.nucleus-provisioned`
+#   marker naming that top dir. A cache restored from a plugin run is therefore reused as is.
+# - electron-builder: `npm ci --ignore-scripts` against the lock file embedded in the plugin, so
+#   every transitive package is checked against its recorded integrity hash (no `npx --yes`).
+#
+# Writes NODE_BIN and ELECTRON_BUILDER_CLI to $GITHUB_ENV.
+set -euo pipefail
+
+: "${NODE_LINE:?}" "${TOOLCHAIN_DIR:?}" "${TOOL_DIR:?}"
+# The plugin's default cache location (<gradle-user-home>/nucleus/nodejs).
+NODE_INSTALL_BASE="${NODE_INSTALL_BASE:-$HOME/.gradle/nucleus/nodejs}"
+
+case "$(uname -m)" in
+  arm64 | aarch64) arch="arm64" ;;
+  x86_64) arch="x64" ;;
+  *) echo "::error::Unsupported architecture $(uname -m)" >&2; exit 1 ;;
+esac
+
+install_dir="$NODE_INSTALL_BASE/node-$NODE_LINE-darwin-$arch"
+marker="$install_dir/.nucleus-provisioned"
+
+if [[ -f "$marker" && -x "$install_dir/$(cat "$marker")/bin/node" ]]; then
+  node_home="$install_dir/$(cat "$marker")"
+  echo "==> Reusing Node.js at $node_home"
+else
+  dist="https://nodejs.org/dist"
+  # Same rule as the plugin: a pinned x.y.z as is, otherwise the newest release of that major.
+  if [[ "$NODE_LINE" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    version="v${NODE_LINE#v}"
+  else
+    version="$(curl -fsSL "$dist/index.json" |
+      jq -r --arg major "$NODE_LINE" \
+        '[.[] | select(.version | startswith("v" + $major + "."))]
+         | sort_by(.version | ltrimstr("v") | split(".") | map(tonumber)) | last | .version')"
+  fi
+  if [[ -z "$version" || "$version" == "null" ]]; then
+    echo "::error::No Node.js release matches '$NODE_LINE'" >&2
+    exit 1
+  fi
+
+  archive="node-$version-darwin-$arch.tar.gz"
+  work="$(mktemp -d)"
+  trap 'rm -rf "$work"' EXIT
+
+  echo "==> Downloading Node.js $version from $dist/$version/$archive"
+  curl -fsSL -o "$work/$archive" "$dist/$version/$archive"
+  curl -fsSL -o "$work/SHASUMS256.txt" "$dist/$version/SHASUMS256.txt"
+  (cd "$work" && grep "  $archive\$" SHASUMS256.txt | shasum -a 256 -c -)
+
+  tar -xzf "$work/$archive" -C "$work"
+  top_dir="node-$version-darwin-$arch"
+  rm -rf "$install_dir"
+  mkdir -p "$install_dir"
+  mv "$work/$top_dir" "$install_dir/"
+  echo "$top_dir" > "$marker"
+  node_home="$install_dir/$top_dir"
+  echo "==> Node.js $version installed to $node_home"
+fi
+
+node_bin="$node_home/bin/node"
+# npm's launcher resolves `node` through PATH.
+export PATH="$node_home/bin:$PATH"
+
+echo "==> Provisioning electron-builder from the plugin's lock file (npm ci --ignore-scripts)"
+rm -rf "$TOOL_DIR"
+mkdir -p "$TOOL_DIR"
+cp "$TOOLCHAIN_DIR/package.json" "$TOOLCHAIN_DIR/package-lock.json" "$TOOL_DIR/"
+(cd "$TOOL_DIR" && npm ci --ignore-scripts --no-audit --no-fund --no-progress --loglevel=error)
+
+cli="$TOOL_DIR/node_modules/electron-builder/cli.js"
+if [[ ! -f "$cli" ]]; then
+  echo "::error::electron-builder CLI missing at $cli after npm ci" >&2
+  exit 1
+fi
+echo "==> electron-builder $("$node_bin" "$cli" --version)"
+
+{
+  echo "NODE_BIN=$node_bin"
+  echo "ELECTRON_BUILDER_CLI=$cli"
+} >> "$GITHUB_ENV"

.github/actions/release-tag-info/action.yml

@@ -0,0 +1,64 @@
+name: Release tag info
+description: Classifies the pushed tag into a release channel and derives the version the build will publish
+
+outputs:
+  version:
+    description: Maven version the publish tasks will derive from the tag (tag name without the leading `v`)
+    value: ${{ steps.classify.outputs.version }}
+  channel:
+    description: '`dev` for a `v<version>-dev-<id>` tag, `release` for anything else'
+    value: ${{ steps.classify.outputs.channel }}
+  is-dev:
+    description: '`true` when the tag is a dev tag (publish without running preMerge)'
+    value: ${{ steps.classify.outputs.is-dev }}
+
+runs:
+  using: composite
+  steps:
+    - name: Classify tag
+      id: classify
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        if [[ "${GITHUB_REF_TYPE:-}" != "tag" ]]; then
+          echo "::error::release-tag-info only runs on tag refs (got '${GITHUB_REF_TYPE:-none}')."
+          exit 1
+        fi
+
+        tag="${GITHUB_REF_NAME}"
+
+        # Every publish task derives its version with `GITHUB_REF.removePrefix("refs/tags/v")`,
+        # so a tag that is not `v<semver>` would publish a version literally named
+        # `refs/tags/<tag>`. Fail here rather than on Maven Central, where it is permanent.
+        if [[ ! "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z]+([.-][0-9A-Za-z]+)*)?$ ]]; then
+          echo "::error::Tag '$tag' is not a publishable version tag (expected v<major>.<minor>.<patch>[-qualifier])."
+          exit 1
+        fi
+
+        version="${tag#v}"
+
+        # Dev channel: `v2.6.0-dev-202609200830`. Cut from any branch, published without
+        # preMerge — the usual Kotlin-ecosystem `-dev-` build.
+        if [[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-dev([.-][0-9A-Za-z]+)*$ ]]; then
+          channel=dev
+          is_dev=true
+        else
+          channel=release
+          is_dev=false
+        fi
+
+        echo "Tag '$tag' → version '$version', channel '$channel'."
+        {
+          echo "version=$version"
+          echo "channel=$channel"
+          echo "is-dev=$is_dev"
+        } >> "$GITHUB_OUTPUT"
+
+        {
+          echo "### Publishing \`$version\` (\`$channel\` channel)"
+          if [[ "$is_dev" == "true" ]]; then
+            echo ""
+            echo "Dev tag: \`preMerge\` is skipped."
+          fi
+        } >> "$GITHUB_STEP_SUMMARY"

.github/actions/setup-nucleus/action.yml

@@ -23,29 +23,25 @@ inputs:
     required: false
     default: 'false'
   setup-gradle:
-    description: 'Setup Gradle via gradle/actions/setup-gradle@v5'
+    description: 'Setup Gradle via gradle/actions/setup-gradle@v6 (open-source basic cache provider)'
     required: false
     default: 'true'
   graalvm:
     description: 'Prepare a GraalVM native-image build: native build tools (Xcode/MSVC) and toolchain cache. The GraalVM JDK itself is auto-downloaded by the Nucleus plugin.'
     required: false
     default: 'false'
   graalvm-version:
-    description: 'GraalVM toolchain version, used only as a cache-key component. Keep in sync with the graalvm { toolchain { } } DSL (e.g. 25i3, 25).'
+    description: 'GraalVM toolchain version, used only as a cache-key component. Keep in sync with the graalvm { toolchain { } } DSL (e.g. 25i4, 25).'
     required: false
-    default: '25i3'
+    default: '25i4'
   graalvm-distribution:
     description: 'GraalVM distribution, used only as a cache-key component. Keep in sync with graalvm { toolchain { distribution } } (community or oracle). Changing it must not restore a cache holding the other distribution.'
     required: false
     default: 'community'
-  setup-node:
-    description: 'Setup Node.js'
-    required: false
-    default: 'true'
   node-version:
-    description: 'Node.js version'
+    description: 'Node.js line the Nucleus plugin provisions, used only as a cache-key component. Keep in sync with the nativeDistributions { nodejs { version } } DSL.'
     required: false
-    default: '24'
+    default: '22'
 
 outputs:
   java-home:
@@ -62,10 +58,9 @@ runs:
     # Temurin, matching the rest of the workflows. jpackage bundles this JDK into
     # the distributed app. In GraalVM mode the native image is built entirely by
     # the plugin-provisioned GraalVM, so the Gradle JDK contributes nothing to
-    # that output. decorated-window-jbr needs no JBR here — the JBR API comes
-    # from the org.jetbrains.runtime:jbr-api Maven artifact.
+    # that output.
     - name: Set up JDK
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v6
       with:
         distribution: ${{ runner.os == 'Windows' && 'microsoft' || 'temurin' }}
         java-version: ${{ inputs.java-version }}
@@ -94,7 +89,7 @@ runs:
     # a cache still holding the other build.
     - name: Cache GraalVM toolchain
       if: inputs.graalvm == 'true'
-      uses: actions/cache@v4
+      uses: actions/cache@v6
       with:
         path: ~/.gradle/nucleus/graalvm
         key: graalvm-toolchain-${{ runner.os }}-${{ runner.arch }}-${{ inputs.graalvm-distribution }}-${{ inputs.graalvm-version }}
@@ -152,11 +147,18 @@ runs:
     # ── Gradle ──────────────────────────────────────────────────────────
     - name: Setup Gradle
       if: inputs.setup-gradle == 'true'
-      uses: gradle/actions/setup-gradle@v5
+      uses: gradle/actions/setup-gradle@v6
+      with:
+        # Open-source cache on GitHub Actions cache; v6's default provider is proprietary.
+        cache-provider: basic
 
     # ── Node.js ─────────────────────────────────────────────────────────
-    - name: Setup Node.js
-      if: inputs.setup-node == 'true'
-      uses: actions/setup-node@v6
+    # No actions/setup-node: the Nucleus plugin downloads the Node.js it runs
+    # electron-builder with and caches it under ~/.gradle/nucleus/nodejs, so CI
+    # packages with the same toolchain a developer machine does. Only the cache
+    # is CI's business.
+    - name: Cache Node.js toolchain
+      uses: actions/cache@v6
       with:
-        node-version: ${{ inputs.node-version }}
+        path: ~/.gradle/nucleus/nodejs
+        key: nodejs-toolchain-${{ runner.os }}-${{ runner.arch }}-${{ inputs.node-version }}