3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Serve generated release, changelog and API files from the dev server (#2278)
Nguyen Xuan An7bad57a3daf0
diff --git a/changes/2278.md b/changes/2278.mdnew file mode 100644index 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.mjsnew file mode 100644index 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.jsnew file mode 100644index 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.jsindex 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