Skip to content

3D engine that AI agents drive

Tell when the installed Cook does not match the pinned commit (#2274)

Nguyen Xuan Ane68fb3778337
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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: the
1. 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.json
index 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.mjs
new file mode 100644
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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;