Skip to content

3D engine that AI agents drive

Serve generated release, changelog and API files from the dev server (#2278)

Nguyen Xuan An7bad57a3daf0
diff --git a/changes/2278.md b/changes/2278.md
new file mode 100644
index 00000000..d770d59c
--- /dev/null
+++ b/changes/2278.md
@@ -0,0 +1 @@
+- The dev server builds `release.json`, `changelog.json` and `api-reference.json` on request when `public/` lacks them, so the home, changelog and docs pages load without errors in a fresh checkout (#2278).
diff --git a/scripts/vite-generated-files.mjs b/scripts/vite-generated-files.mjs
new file mode 100644
index 00000000..05a65be4
--- /dev/null
+++ b/scripts/vite-generated-files.mjs
@@ -0,0 +1,74 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readChangelogData } from './changelog-fragments.mjs';
+import { buildApiReference } from './api-reference.mjs';
+
+const projectRoot = fileURLToPath(new URL('..', import.meta.url));
+
+function currentCommit(root) {
+ const result = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, windowsHide: true, encoding: 'utf8' });
+ const commit = result.stdout?.trim() ?? '';
+ return /^[a-f0-9]{40}$/.test(commit) ? commit : '0000000000000000000000000000000000000000';
+}
+
+// The release metadata src/home.js reads, for a checkout that never ran `npm run prepare:release`. It names the version in
+// package.json and the commit checked out; the download links point where prepare:release would put the files.
+export function devRelease({ packageJson, commit }) {
+ const { name, version } = packageJson;
+ return {
+ version,
+ packageName: name,
+ packageAlias: 'crucible',
+ commit,
+ installCommand: `npm install crucible@npm:${name}@${version}`,
+ tarball: `/releases/${name.replace(/^@/, '').replace('/', '-')}-${version}.tgz`,
+ module: `/releases/${version}/67.module.js`,
+ registryPublished: false,
+ registryVersion: null,
+ api: './docs.html#renderer-reference',
+ changelog: '/changelog.md',
+ changelogData: '/changelog.json',
+ devPreview: true,
+ };
+}
+
+async function readPackageJson(root) {
+ return JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+}
+
+// Each file `npm run prepare:release` writes into public/ and a site page fetches, with how to build it on request.
+export const GENERATED_FILES = {
+ '/release.json': async root => devRelease({ packageJson: await readPackageJson(root), commit: currentCommit(root) }),
+ '/changelog.json': async root => readChangelogData({
+ changelogText: await readFile(join(root, 'CHANGELOG.md'), 'utf8'),
+ version: (await readPackageJson(root)).version,
+ }),
+ '/api-reference.json': async () => buildApiReference(),
+};
+
+// A fresh checkout has none of these files, so the dev server answered 404 and every console check of the home, changelog and
+// docs pages failed (#2278). The dev server builds them on request; a copy in public/ still wins, and the build is unchanged.
+export function generatedFiles({ root = projectRoot } = {}) {
+ return {
+ name: 'generated-files',
+ apply: 'serve',
+ configureServer(server) {
+ server.middlewares.use(async (request, response, next) => {
+ const pathname = request.url.split('?')[0];
+ const build = GENERATED_FILES[pathname];
+ if (!build || existsSync(join(root, 'public', pathname))) return next();
+ try {
+ const body = JSON.stringify(await build(root));
+ response.setHeader('Content-Type', 'application/json');
+ response.setHeader('Cache-Control', 'no-store');
+ response.end(body);
+ } catch (error) {
+ next(error);
+ }
+ });
+ },
+ };
+}
diff --git a/tests/vite-generated-files.test.js b/tests/vite-generated-files.test.js
new file mode 100644
index 00000000..3d6fdf8f
--- /dev/null
+++ b/tests/vite-generated-files.test.js
@@ -0,0 +1,75 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { devRelease, generatedFiles, GENERATED_FILES } from '../scripts/vite-generated-files.mjs';
+
+function middlewareOf(root) {
+ let handler;
+ generatedFiles({ root }).configureServer({ middlewares: { use: middleware => { handler = middleware; } } });
+ return handler;
+}
+
+async function answer(handler, url) {
+ return new Promise((resolve, reject) => {
+ const headers = {};
+ const response = {
+ setHeader: (name, value) => { headers[name] = value; },
+ end: body => resolve({ served: true, headers, body }),
+ };
+ handler({ url }, response, error => (error ? reject(error) : resolve({ served: false })));
+ });
+}
+
+// The fields and checks src/home.js validateRelease applies before it shows a release.
+function assertHomeAccepts(release) {
+ for (const key of ['version', 'packageName', 'commit', 'installCommand', 'tarball', 'module', 'api']) {
+ assert.equal(typeof release[key], 'string', key);
+ assert.ok(release[key].trim(), key);
+ }
+ assert.equal(typeof release.registryPublished, 'boolean');
+ assert.match(release.commit, /^[a-f0-9]{7,40}$/i);
+ for (const key of ['tarball', 'module', 'api']) assert.match(release[key], /^\.?\//, `${key} stays on the current site`);
+}
+
+test('the dev release names the package version and commit in the shape the home page accepts', () => {
+ const release = devRelease({ packageJson: { name: '@codepawlhq/crucible', version: '1.2.3' }, commit: 'a'.repeat(40) });
+ assertHomeAccepts(release);
+ assert.equal(release.version, '1.2.3');
+ assert.equal(release.tarball, '/releases/codepawlhq-crucible-1.2.3.tgz');
+ assert.equal(release.module, '/releases/1.2.3/67.module.js');
+ assert.equal(release.registryPublished, false);
+});
+
+test('a checkout without public/ files gets the release built on request', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'generated-files-'));
+ try {
+ writeFileSync(join(root, 'package.json'), JSON.stringify({ name: '@codepawlhq/crucible', version: '9.8.7' }));
+ const reply = await answer(middlewareOf(root), '/release.json?commit=abc');
+ assert.equal(reply.served, true);
+ assert.equal(reply.headers['Content-Type'], 'application/json');
+ const release = JSON.parse(reply.body);
+ assertHomeAccepts(release);
+ assert.equal(release.version, '9.8.7');
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+});
+
+test('a copy in public/ wins, and other addresses pass through', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'generated-files-'));
+ try {
+ mkdirSync(join(root, 'public'));
+ writeFileSync(join(root, 'public', 'release.json'), '{}');
+ const handler = middlewareOf(root);
+ assert.equal((await answer(handler, '/release.json')).served, false);
+ assert.equal((await answer(handler, '/index.html')).served, false);
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+});
+
+test('every file the site pages fetch is covered', () => {
+ assert.deepEqual(Object.keys(GENERATED_FILES).sort(), ['/api-reference.json', '/changelog.json', '/release.json']);
+});
diff --git a/vite.config.js b/vite.config.js
index f882a825..70389591 100644
--- a/vite.config.js
+++ b/vite.config.js
@@ -2,6 +2,7 @@ import { defineConfig } from 'vite';
import fs from 'node:fs';
import path from 'node:path';
import { sitePages } from './scripts/vite-site-pages.mjs';
+import { generatedFiles } from './scripts/vite-generated-files.mjs';
const headers = {
'Cross-Origin-Opener-Policy': 'same-origin',
@@ -31,7 +32,7 @@ function serveLocalFolders() {
}
export default defineConfig({
- plugins: [serveLocalFolders(), sitePages()],
+ plugins: [serveLocalFolders(), sitePages(), generatedFiles()],
server: { headers, watch: { ignored: ['**/.claude/**'] } },
// Scan only the project's own pages. Agent worktrees under .claude hold hundreds of copies of them and made the first page load take 13 s.
// The browser denoiser page imports `denoiser`, which is installed by hand (bench/reference/denoise-browser.mjs). Scanning it