sindicate 0.5.0 → 0.7.0

package/tools/devPlugin.js

@@ -0,0 +1,232 @@
+// sindicateDevTools(config) — the engine's dev-server tooling suite, extracted from the
+// western game's vite config. Returns an array of vite plugins (all `apply: 'serve'` —
+// none of this exists in a production build):
+//
+//   • guarded SOURCE-WRITE endpoints — bench pages persist tuned data straight into the
+//     game's data files (grip/rig/map/LOD... whatever the game declares)
+//   • COOK-TO-FILE stores — the game bakes its own caches (VAT bins, nav grids, parsed
+//     animation clips, world cook bins, map PNGs) and every later boot is a file read.
+//     Each store serves its directory itself: the dirs are excluded from vite's watcher
+//     (writes must not full-reload the page), and vite 8's watcher-fed public registry
+//     404s files created after startup — so we bypass it.
+//   • PERF SINK — [PERF]/FREEZE samples append to a JSONL on disk, readable without the
+//     console (a backgrounded tab pauses rAF and CDP is flaky; disk is neither)
+//   • EDITOR + GAME COMMAND BUSES — queue {js|op} snippets over HTTP; the live page polls,
+//     executes, posts results back. Scripted playtests and editor drives with curl.
+//
+// Usage (a game's vite.config.js):
+//   import { sindicateDevTools } from 'sindicate/tools/devPlugin.js';
+//   plugins: [...sindicateDevTools({
+//     sourceWrites: [{ route: '/__save-grip', file: 'src/game/data/gripTuning.json',
+//                      json: true, mustInclude: 'revolver' }],
+//     assetLists:   [{ route: '/__list-assets', dir: 'public/assets/world', ext: 'fbx' }],
+//     perfSink: process.env.MY_PERF_SINK || '/tmp/mygame-perf.jsonl',
+//   })]
+import fs from 'node:fs';
+
+// Guard for the source-writing endpoints: only same-machine pages may write, and the
+// payload must look like the file it claims to be — an empty/garbage body used to be
+// written verbatim (truncating a committed src file to 0 bytes and breaking the boot via
+// HMR), and cross-origin simple POSTs from any open webpage could reach these routes.
+function guardOk(req, res, body, checks) {
+  const origin = req.headers.origin;
+  if (origin && !/^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) {
+    res.statusCode = 403; res.end('cross-origin write refused'); return false;
+  }
+  if (!body || body.length < 20) { res.statusCode = 400; res.end('empty body refused'); return false; }
+  for (const [label, ok] of checks) {
+    if (!ok) { res.statusCode = 400; res.end(`payload failed check: ${label}`); return false; }
+  }
+  return true;
+}
+
+const readBody = (req) => new Promise((resolve) => {
+  const c = []; req.on('data', (d) => c.push(d)); req.on('end', () => resolve(Buffer.concat(c)));
+});
+const sendJson = (res, code, obj) => {
+  res.statusCode = code; res.setHeader('content-type', 'application/json'); res.end(JSON.stringify(obj));
+};
+
+// One guarded write-through-to-a-source-file endpoint (grip/rig/map/LOD tuners).
+function sourceWritePlugin({ route, file, json = false, mustInclude = null }) {
+  return {
+    name: `sindicate-write:${route}`,
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use(route, (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        let body = '';
+        req.on('data', (c) => { body += c; });
+        req.on('end', () => {
+          try {
+            const checks = mustInclude ? [[`payload mentions '${mustInclude}'`, body.includes(mustInclude)]] : [];
+            if (!guardOk(req, res, body, checks)) return;
+            if (json) JSON.parse(body);           // never write a malformed file
+            fs.writeFileSync(file, body);
+            res.statusCode = 200; res.end('ok');
+          } catch (e) { res.statusCode = 500; res.end(String(e)); }
+        });
+      });
+    },
+  };
+}
+
+// Directory listing for editor asset palettes.
+function assetListPlugin({ route, dir, ext }) {
+  const re = new RegExp(`\\.${ext}$`, 'i');
+  return {
+    name: `sindicate-list:${route}`,
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use(route, (req, res) => {
+        try {
+          const files = fs.readdirSync(dir).filter((f) => re.test(f)).map((f) => f.replace(re, '')).sort();
+          sendJson(res, 200, files);
+        } catch (e) { res.statusCode = 500; res.end('[]'); }
+      });
+    },
+  };
+}
+
+// Serve + accept a cook-to-file store (bins/JSON/PNG the game bakes for itself).
+function binStorePlugin({ name, serveRoute, saveRoute, dir, nameRe, contentType }) {
+  return {
+    name: `sindicate-store:${name}`,
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use(serveRoute, (req, res, next) => {
+        const file = (req.url || '').split('?')[0].replace(/^\//, '');
+        if (!nameRe.test(file)) return next();
+        try {
+          const buf = fs.readFileSync(`${dir}/${file}`);
+          res.setHeader('content-type', typeof contentType === 'function' ? contentType(file) : contentType);
+          res.end(buf);
+        } catch (e) { res.statusCode = 404; res.end('not cooked'); }
+      });
+      server.middlewares.use(saveRoute, async (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        const file = new URL(req.url, 'http://x').searchParams.get('name') || '';
+        if (!nameRe.test(file)) { res.statusCode = 400; return res.end('bad name'); }
+        try {
+          fs.mkdirSync(dir, { recursive: true });
+          fs.writeFileSync(`${dir}/${file}`, await readBody(req));
+          res.statusCode = 200; res.end('ok');
+        } catch (e) { res.statusCode = 500; res.end(String(e)); }
+      });
+    },
+  };
+}
+
+// JSONL telemetry sink with size rotation.
+function perfSinkPlugin(sinkPath) {
+  return {
+    name: 'sindicate-perf-sink',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use('/__perf', (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        let body = '';
+        req.on('data', (c) => { body += c; });
+        req.on('end', () => {
+          try {
+            try { if (fs.statSync(sinkPath).size > 8_000_000) fs.renameSync(sinkPath, sinkPath + '.1'); } catch { /* no sink yet */ }
+            fs.appendFileSync(sinkPath, body.trim() + '\n'); res.statusCode = 200; res.end('ok');
+          } catch (e) { res.statusCode = 500; res.end(String(e)); }
+        });
+      });
+    },
+  };
+}
+
+// A poll/take command bus: POST {…} to /cmd → the page polls /poll → posts /result →
+// collect via /take?id=N. `originGuard` restricts /cmd to same-machine pages.
+function busPlugin({ name, prefix, originGuard = false }) {
+  return {
+    name: `sindicate-bus:${name}`,
+    apply: 'serve',
+    configureServer(server) {
+      const queue = [];
+      const results = new Map();
+      let nextId = 1;
+      server.middlewares.use(`${prefix}/cmd`, async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { err: 'POST only' });
+        if (originGuard) {
+          const origin = req.headers.origin;
+          if (origin && !/^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) return sendJson(res, 403, { err: 'cross-origin refused' });
+        }
+        try {
+          const cmd = JSON.parse((await readBody(req)).toString());
+          cmd.id = nextId++; queue.push(cmd);
+          if (queue.length > 40) queue.splice(0, queue.length - 40);
+          sendJson(res, 200, { id: cmd.id });
+        } catch (e) { sendJson(res, 400, { err: String(e) }); }
+      });
+      server.middlewares.use(`${prefix}/poll`, (req, res) => sendJson(res, 200, { cmds: queue.splice(0) }));
+      server.middlewares.use(`${prefix}/result`, async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { err: 'POST only' });
+        try {
+          const r = JSON.parse((await readBody(req)).toString());
+          results.set(r.id, r);
+          if (results.size > 100) results.delete(results.keys().next().value);
+          sendJson(res, 200, { ok: 1 });
+        } catch (e) { sendJson(res, 400, { err: String(e) }); }
+      });
+      server.middlewares.use(`${prefix}/take`, (req, res) => {
+        const id = Number(new URL(req.url, 'http://x').searchParams.get('id') || 0);
+        if (!results.has(id)) return sendJson(res, 404, { pending: true });
+        const r = results.get(id); results.delete(id); sendJson(res, 200, r);
+      });
+    },
+  };
+}
+
+// Editor screenshot drop (ring-limited) + baked-map store.
+function editorShotsPlugin({ shotsDir, mapsDir }) {
+  return {
+    name: 'sindicate-editor-shots',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use('/__save-editorshot', async (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        const name = new URL(req.url, 'http://x').searchParams.get('name') || '';
+        if (!/^[\w.-]+\.png$/.test(name)) { res.statusCode = 400; return res.end('bad name'); }
+        try {
+          fs.mkdirSync(shotsDir, { recursive: true });
+          fs.writeFileSync(`${shotsDir}/${name}`, await readBody(req));
+          const shots = fs.readdirSync(shotsDir).filter((f) => f.endsWith('.png'));
+          if (shots.length > 150) {
+            shots.map((f) => [f, fs.statSync(`${shotsDir}/${f}`).mtimeMs]).sort((a, b) => a[1] - b[1])
+              .slice(0, shots.length - 150).forEach(([f]) => { try { fs.unlinkSync(`${shotsDir}/${f}`); } catch { /* raced */ } });
+          }
+          res.end('ok');
+        } catch (e) { res.statusCode = 500; res.end(String(e)); }
+      });
+    },
+  };
+}
+
+export function sindicateDevTools({
+  sourceWrites = [],
+  assetLists = [],
+  perfSink = process.env.SINDICATE_PERF_SINK || '/tmp/sindicate-perf.jsonl',
+  cookStores = null,        // override to add/remove stores; null = the standard set below
+  editorShotsDir = 'public/editor-shots',
+  mapsDir = 'public/assets/maps',
+} = {}) {
+  const stores = cookStores ?? [
+    { name: 'vat', serveRoute: '/assets/vat', saveRoute: '/__save-vatbin', dir: 'public/assets/vat', nameRe: /^[\w-]+\.bin$/, contentType: 'application/octet-stream' },
+    { name: 'nav', serveRoute: '/assets/nav', saveRoute: '/__save-navbin', dir: 'public/assets/nav', nameRe: /^[\w.-]+\.bin$/, contentType: 'application/octet-stream' },
+    { name: 'clips', serveRoute: '/assets/clips', saveRoute: '/__save-clipjson', dir: 'public/assets/clips', nameRe: /^[\w.-]+\.json$/, contentType: 'application/json' },
+    { name: 'cook', serveRoute: '/assets/cook', saveRoute: '/__save-cookbin', dir: 'public/assets/cook', nameRe: /^[\w.-]+\.(bin|json)$/, contentType: 'application/octet-stream' },
+    { name: 'maps', serveRoute: '/assets/maps', saveRoute: '/__save-mappng', dir: mapsDir, nameRe: /^[\w.-]+\.(png|json)$/, contentType: (f) => (f.endsWith('.json') ? 'application/json' : 'image/png') },
+  ];
+  return [
+    ...sourceWrites.map(sourceWritePlugin),
+    ...assetLists.map(assetListPlugin),
+    ...stores.map(binStorePlugin),
+    perfSinkPlugin(perfSink),
+    busPlugin({ name: 'game', prefix: '/__game', originGuard: true }),
+    busPlugin({ name: 'editor', prefix: '/__editor' }),
+    editorShotsPlugin({ shotsDir: editorShotsDir, mapsDir }),
+  ];
+}