feat(docker): pin build toolchain image by digest

The build image was referenced only by a mutable tag (bugra9/cpp.js:0.3.2), so a hijacked or
re-pushed tag on the registry could swap the compiler out from under every build. Pin it by
digest for the pull/run/create paths; keep the tag solely for the container name (a digest's
'@sha256:' is not a valid container-name character). The existence check moves from
'docker images -q' (which does not resolve a digest ref, so it would re-pull every build) to
'docker image inspect', which resolves both.

- scripts/pin-docker-image.js: re-derives the registry digest from the tag and rewrites the
  IMAGE constant, keeping tag and digest in sync when the image is republished.

Author: bugra9

cppjs-core/cpp.js/src/utils/pullDockerImage.js

@@ -1,22 +1,39 @@
 import { execFileSync } from 'node:child_process';
 import { getContentHash } from './hash.js';
 
+// The build toolchain image is pinned by digest, not just by tag, so a hijacked or re-pushed
+// tag on the registry can't silently swap the compiler out from under a build. IMAGE_TAG is the
+// same image kept only for a readable, stable container name — a digest's '@sha256:...' is not
+// valid in a Docker container name. Bump BOTH together when publishing a new image
+// (scripts/pin-docker-image.js reads the digest back from the registry).
+const IMAGE_TAG = 'bugra9/cpp.js:0.3.2';
+const IMAGE = 'bugra9/cpp.js@sha256:b99af109d096d21a09d44d8b119c671f0af3fe8725e5f88c6d47d7e48b612d2a';
+
 let isDockerImageAvailable = false;
 
 export function getDockerImage() {
-    return 'bugra9/cpp.js:0.3.2';
+    return IMAGE;
 }
 
 export function getDockerContainerName(base) {
-    return `${getDockerImage()}-${getContentHash(base)}`.replaceAll('/', '-').replaceAll(':', '-');
+    return `${IMAGE_TAG}-${getContentHash(base)}`.replaceAll('/', '-').replaceAll(':', '-');
+}
+
+// `docker images -q` does not resolve a digest reference (returns empty), so the existence check
+// uses `docker image inspect`, which works for both tag and digest refs.
+function isImagePresent(ref) {
+    try {
+        execFileSync('docker', ['image', 'inspect', ref], { stdio: 'ignore' });
+        return true;
+    } catch {
+        return false;
+    }
 }
 
 export default function pullDockerImage() {
     if (isDockerImageAvailable) return;
 
-    const isImageExist = execFileSync('docker', ['images', '-q', getDockerImage()], { encoding: 'utf-8' }).trim() !== '';
-
-    if (!isImageExist) {
+    if (!isImagePresent(getDockerImage())) {
         console.log('');
         console.log('===========================================================');
         console.log('============= Downloading the docker image... =============');

scripts/pin-docker-image.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// Re-derives the build image's registry digest from its tag and writes it into pullDockerImage.js,
+// so the pinned digest (IMAGE) stays in sync with the tag (IMAGE_TAG) whenever the image is
+// republished. Run after `docker push`-ing a new image. Requires the tagged image pulled locally
+// (docker pull bugra9/cpp.js:<tag>) so its RepoDigest is known.
+//
+//   node scripts/pin-docker-image.js
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const FILE = path.join(ROOT, 'cppjs-core', 'cpp.js', 'src', 'utils', 'pullDockerImage.js');
+
+const text = fs.readFileSync(FILE, 'utf8');
+const tag = text.match(/const IMAGE_TAG = '([^']+)'/)?.[1];
+if (!tag) {
+    console.error('pin-docker-image: could not find IMAGE_TAG in pullDockerImage.js');
+    process.exit(1);
+}
+if (!/const IMAGE = '[^']*';/.test(text)) {
+    console.error('pin-docker-image: could not find the IMAGE constant to update in pullDockerImage.js');
+    process.exit(1);
+}
+
+let repoDigest;
+try {
+    repoDigest = execFileSync('docker', ['inspect', '--format', '{{index .RepoDigests 0}}', tag], { encoding: 'utf8' }).trim();
+} catch {
+    console.error(`pin-docker-image: '${tag}' is not available locally. Run: docker pull ${tag}`);
+    process.exit(1);
+}
+if (!/^[^@]+@sha256:[0-9a-f]{64}$/.test(repoDigest)) {
+    console.error(`pin-docker-image: no registry digest for ${tag} (built locally but never pushed?). Got: ${repoDigest || '(empty)'}`);
+    process.exit(1);
+}
+
+const next = text.replace(/const IMAGE = '[^']*';/, `const IMAGE = '${repoDigest}';`);
+if (next === text) {
+    console.log(`pin-docker-image: already pinned to ${repoDigest}`);
+    process.exit(0);
+}
+fs.writeFileSync(FILE, next);
+console.log(`pin-docker-image: pinned ${tag} -> ${repoDigest}`);