3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Tell when the installed Cook does not match the pinned commit (#2274)
Nguyen Xuan Ane68fb3778337
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 8d1b4342..888f0e64 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -11,6 +11,7 @@ Coding agents are welcome to open pull requests. There is no disclosure box: the1. Install Node.js 20.19 or later (the `Test` workflow uses 24) and Google Chrome.2. Clone the repository and run `npm ci`.3. Run `npm run dev`. Vite prints the local URL of the showcase.+4. For the Cook tests and native renders, run `npm run cook:fetch` to get the prebuilt addon of the pinned Cook (or `npm run cook:build` with Rust). `npm run cook:check` says whether the installed Cook is the one `package-lock.json` pins. When it is not, the Cook tests skip and `tests/cook-install.test.js` fails with what to run. Set `COOK_ALLOW_UNPINNED=1` only when you link a Cook checkout on purpose.The library source is in `src/` and the Node tools and smoke scripts are in `scripts/`.The tests are in `tests/` and the guides are in `docs/`.diff --git a/package.json b/package.jsonindex cf427b64..07e4b1a8 100644--- a/package.json+++ b/package.json@@ -180,6 +180,8 @@"test:coverage": "node --test --import ./scripts/test-hang-guard.mjs --test-timeout=300000 --experimental-test-coverage --test-coverage-exclude=\"tests/**\" --test-coverage-exclude=\"scripts/**\" --test-coverage-exclude=\"build/**\"","coverage:gate": "node scripts/coverage-gate.mjs","cook:build": "node node_modules/@codepawlhq/cook/build.mjs",+ "cook:check": "node scripts/cook-install-check.mjs",+ "cook:fetch": "node node_modules/@codepawlhq/cook/fetch-addon.mjs","preflight": "node scripts/preflight.mjs","render:file-cook": "node scripts/render-file-native.mjs","smoke": "node scripts/smoke.mjs",diff --git a/scripts/cook-install-check.mjs b/scripts/cook-install-check.mjsnew file mode 100644index 00000000..5212b028--- /dev/null+++ b/scripts/cook-install-check.mjs@@ -0,0 +1,101 @@+#!/usr/bin/env node+// Tells whether the installed Cook (@codepawlhq/cook) is the one package-lock.json pins (#2274).+// A Cook that is not the pinned one fails deep inside its own code ("KernelParamsV2 must be 320 bytes, got 336"), which looks+// like a bug in the change under test; this check names the mismatch and the command that fixes it.+// Usage: node scripts/cook-install-check.mjs (exits 1 on a mismatch, 0 when Cook matches the pin or is absent).+import { execFileSync } from 'node:child_process';+import { existsSync, readFileSync, realpathSync } from 'node:fs';+import { createRequire } from 'node:module';+import { dirname, join, resolve } from 'node:path';+import { fileURLToPath, pathToFileURL } from 'node:url';++const COOK_PACKAGE = '@codepawlhq/cook';+const COOK_LOCK_ENTRY = `node_modules/${COOK_PACKAGE}`;+const CRUCIBLE_REPOSITORY = 'codepawl/crucible';+const repositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');++export const FIX_COMMANDS = 'npm ci, then npm run cook:fetch (the pinned prebuilt addon) or npm run cook:build (needs Rust)';++/** The version and commit SHA package-lock.json pins for Cook, or null when the lock has no Cook entry. */+export function pinnedCookFromLock(lockText) {+ if (typeof lockText !== 'string') {+ throw new TypeError('pinnedCookFromLock: pass the text of package-lock.json.');+ }+ const entry = JSON.parse(lockText).packages?.[COOK_LOCK_ENTRY];+ if (entry === undefined) return null;+ const commit = /#([0-9a-f]{40})$/.exec(String(entry.resolved ?? ''))?.[1] ?? null;+ return { version: entry.version ?? null, commit };+}++/**+ * A mismatch is intentional when Cook's own CI copies a Cook checkout into Crucible to test it (GITHUB_REPOSITORY is then+ * not Crucible), or when COOK_ALLOW_UNPINNED=1 is set.+ */+export function unpinnedCookAllowed(environment) {+ if (environment.COOK_ALLOW_UNPINNED === '1') return true;+ const repository = environment.GITHUB_REPOSITORY;+ return typeof repository === 'string' && repository !== '' && repository !== CRUCIBLE_REPOSITORY;+}++function shortCommit(commit) {+ return commit === null ? 'unknown commit' : commit.slice(0, 8);+}++/**+ * Compares the installed Cook with the pin. `installed` is { version, commit, directory } (commit null when the installed copy+ * is not a git checkout, so only the version can be compared). Returns { status: 'absent' | 'match' | 'mismatch' | 'allowed',+ * message }.+ */+export function compareCookInstall({ pinned, installed, environment = {} }) {+ if (installed === null) return { status: 'absent', message: `${COOK_PACKAGE} is not installed.` };+ if (pinned === null) return { status: 'match', message: `package-lock.json pins no ${COOK_PACKAGE}; nothing to compare.` };+ const versionDiffers = pinned.version !== null && installed.version !== pinned.version;+ const commitDiffers = installed.commit !== null && pinned.commit !== null && installed.commit !== pinned.commit;+ if (!versionDiffers && !commitDiffers) {+ return { status: 'match', message: `${COOK_PACKAGE} ${installed.version} matches the pin.` };+ }+ const description = `The installed ${COOK_PACKAGE} is ${installed.version} (${shortCommit(installed.commit)}) at ${installed.directory}, `+ + `but package-lock.json pins ${pinned.version} (${shortCommit(pinned.commit)}).`;+ if (unpinnedCookAllowed(environment)) {+ return { status: 'allowed', message: `${description} Allowed: COOK_ALLOW_UNPINNED=1 or a Cook CI run.` };+ }+ const linkHint = installed.commit === null+ ? ''+ : ` The installed copy is a git checkout: if node_modules/${COOK_PACKAGE} links to it on purpose, check out ${shortCommit(pinned.commit)} there and rebuild, or set COOK_ALLOW_UNPINNED=1.`;+ return { status: 'mismatch', message: `${description} Run ${FIX_COMMANDS}.${linkHint}` };+}++function gitHead(directory) {+ if (!existsSync(join(directory, '.git'))) return null;+ try {+ return execFileSync('git', ['-C', directory, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();+ } catch {+ return null;+ }+}++/** Reads the installed Cook as seen from `root`: { version, commit, directory } or null when it does not resolve. */+export function readInstalledCook(root = repositoryRoot) {+ let packageJsonPath;+ try {+ packageJsonPath = createRequire(join(root, 'package.json')).resolve(`${COOK_PACKAGE}/package.json`);+ } catch {+ return null;+ }+ const directory = realpathSync(dirname(packageJsonPath));+ const { version } = JSON.parse(readFileSync(packageJsonPath, 'utf8'));+ return { version: version ?? null, commit: gitHead(directory), directory };+}++/** The whole check for the checkout at `root`. */+export function checkCookInstall({ root = repositoryRoot, environment = process.env } = {}) {+ const lockPath = join(root, 'package-lock.json');+ const pinned = existsSync(lockPath) ? pinnedCookFromLock(readFileSync(lockPath, 'utf8')) : null;+ return compareCookInstall({ pinned, installed: readInstalledCook(root), environment });+}++if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {+ const result = checkCookInstall();+ console.log(result.message);+ process.exitCode = result.status === 'mismatch' ? 1 : 0;+}diff --git a/tests/cook-install.test.js b/tests/cook-install.test.jsnew file mode 100644index 00000000..acd78cac--- /dev/null+++ b/tests/cook-install.test.js@@ -0,0 +1,78 @@+import assert from 'node:assert/strict';+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import test from 'node:test';++import {+ checkCookInstall, compareCookInstall, FIX_COMMANDS, pinnedCookFromLock, readInstalledCook, unpinnedCookAllowed,+} from '../scripts/cook-install-check.mjs';++const PINNED_COMMIT = '55f2448dbb5121d82a5b125c3564403b64798d03';+const OTHER_COMMIT = '212c0bafaf2dfbbf60cb5c759c5cf759d23198c7';+const PINNED = { version: '0.2.0', commit: PINNED_COMMIT };++function lockText(resolved, version = '0.2.0') {+ return JSON.stringify({ packages: { 'node_modules/@codepawlhq/cook': { version, resolved } } });+}++// The check that keeps a Cook that is not the pinned one from failing deep inside Cook (#2274).+test('the Cook installed in this checkout is the one package-lock.json pins, or absent', () => {+ const result = checkCookInstall();+ assert.notEqual(result.status, 'mismatch', result.message);+});++test('the pin is the version and the commit after the # of the resolved git URL', () => {+ assert.deepEqual(pinnedCookFromLock(lockText(`git+https://github.com/codepawl/cook.git#${PINNED_COMMIT}`)), PINNED);+ assert.deepEqual(pinnedCookFromLock(lockText('https://registry.npmjs.org/x.tgz', '0.3.0')), { version: '0.3.0', commit: null });+ assert.equal(pinnedCookFromLock(JSON.stringify({ packages: {} })), null);+ assert.throws(() => pinnedCookFromLock(undefined), /pass the text of package-lock.json/);+});++test('a matching version without git, or a matching commit, is a match', () => {+ assert.equal(compareCookInstall({ pinned: PINNED, installed: { version: '0.2.0', commit: null, directory: 'cook' } }).status, 'match');+ assert.equal(compareCookInstall({ pinned: PINNED, installed: { version: '0.2.0', commit: PINNED_COMMIT, directory: 'cook' } }).status, 'match');+ assert.equal(compareCookInstall({ pinned: null, installed: { version: '0.1.0', commit: null, directory: 'cook' } }).status, 'match');+ assert.equal(compareCookInstall({ pinned: PINNED, installed: null }).status, 'absent');+});++test('another version or another commit is a mismatch that names both and the command to run', () => {+ const linked = compareCookInstall({ pinned: PINNED, installed: { version: '0.1.1', commit: OTHER_COMMIT, directory: 'cook-checkout' } });+ assert.equal(linked.status, 'mismatch');+ for (const part of ['0.1.1 (212c0baf)', 'cook-checkout', '0.2.0 (55f2448d)', FIX_COMMANDS, 'check out 55f2448d there']) {+ assert.ok(linked.message.includes(part), `${part} is missing from: ${linked.message}`);+ }+ const sameVersionOtherCommit = compareCookInstall({ pinned: PINNED, installed: { version: '0.2.0', commit: OTHER_COMMIT, directory: 'cook' } });+ assert.equal(sameVersionOtherCommit.status, 'mismatch');+ const copied = compareCookInstall({ pinned: PINNED, installed: { version: '0.1.1', commit: null, directory: 'cook' } });+ assert.equal(copied.status, 'mismatch');+ assert.ok(!copied.message.includes('git checkout'));+});++test('Cook CI and COOK_ALLOW_UNPINNED=1 allow a mismatch, Crucible CI and a plain shell do not', () => {+ assert.equal(unpinnedCookAllowed({ GITHUB_REPOSITORY: 'codepawl/cook' }), true);+ assert.equal(unpinnedCookAllowed({ COOK_ALLOW_UNPINNED: '1' }), true);+ assert.equal(unpinnedCookAllowed({ GITHUB_REPOSITORY: 'codepawl/crucible' }), false);+ assert.equal(unpinnedCookAllowed({}), false);+ const installed = { version: '0.1.1', commit: OTHER_COMMIT, directory: 'cook' };+ assert.equal(compareCookInstall({ pinned: PINNED, installed, environment: { GITHUB_REPOSITORY: 'codepawl/cook' } }).status, 'allowed');+});++test('the installed Cook is read from node_modules, with no commit when it is not a git checkout', () => {+ const root = mkdtempSync(join(tmpdir(), 'cook-install-'));+ try {+ writeFileSync(join(root, 'package.json'), '{"name":"fixture"}');+ assert.equal(readInstalledCook(root), null);+ assert.equal(checkCookInstall({ root, environment: {} }).status, 'absent');+ const cookDirectory = join(root, 'node_modules', '@codepawlhq', 'cook');+ mkdirSync(cookDirectory, { recursive: true });+ writeFileSync(join(cookDirectory, 'package.json'), JSON.stringify({ name: '@codepawlhq/cook', version: '0.1.1', main: 'index.mjs' }));+ const installed = readInstalledCook(root);+ assert.equal(installed.version, '0.1.1');+ assert.equal(installed.commit, null);+ writeFileSync(join(root, 'package-lock.json'), lockText(`git+https://github.com/codepawl/cook.git#${PINNED_COMMIT}`));+ assert.equal(checkCookInstall({ root, environment: {} }).status, 'mismatch');+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+});diff --git a/tests/cook-test-helper.test.js b/tests/cook-test-helper.test.jsindex 2b1c6764..d5398671 100644--- a/tests/cook-test-helper.test.js+++ b/tests/cook-test-helper.test.js@@ -9,7 +9,8 @@ const SKIP_REASON = 'Cook (@codepawlhq/cook) is not installed';const helperUrl = new URL('./support/cook.js', import.meta.url).href;test('the helper agrees with itself about whether Cook is installed', async () => {- assert.equal(cookSkipReason, cookInstalled ? false : SKIP_REASON);+ if (cookInstalled) assert.equal(cookSkipReason, false);+ else assert.ok(cookSkipReason === SKIP_REASON || cookSkipReason.includes("package-lock.json pins"), cookSkipReason);const engine = await cookModule('engine');if (cookInstalled) {assert.equal(typeof engine.describeEngine, 'function');diff --git a/tests/support/cook.js b/tests/support/cook.jsindex e8e3a24b..51932865 100644--- a/tests/support/cook.js+++ b/tests/support/cook.js@@ -1,9 +1,12 @@// Lets a test use Cook (@codepawlhq/cook) when it is installed and skip when it is not, so `npm test` passes either way.-// COOK_DISABLE=1 behaves like an absent package, which is how the absent mode is tested.+// COOK_DISABLE=1 behaves like an absent package, which is how the absent mode is tested. A Cook that is not the one+// package-lock.json pins skips too, with a reason that says what to run (#2274); tests/cook-install.test.js fails on it.import { createRequire } from 'node:module';import { dirname, join } from 'node:path';import test, { describe } from 'node:test';+import { checkCookInstall } from '../../scripts/cook-install-check.mjs';+const COOK_PACKAGE = '@codepawlhq/cook';function findCookDirectory() {@@ -16,10 +19,13 @@ function findCookDirectory() {}}-const cookDirectory = findCookDirectory();+const resolvedCookDirectory = findCookDirectory();+const installCheck = resolvedCookDirectory === null ? null : checkCookInstall();+const cookMismatched = installCheck?.status === 'mismatch';+const cookDirectory = cookMismatched ? null : resolvedCookDirectory;export const cookInstalled = cookDirectory !== null;-export const cookSkipReason = cookInstalled ? false : 'Cook (@codepawlhq/cook) is not installed';+export const cookSkipReason = cookInstalled ? false : (cookMismatched ? installCheck.message : 'Cook (@codepawlhq/cook) is not installed');function exportSubpath(subpath) {if (subpath === '' || subpath === '.') return COOK_PACKAGE;