Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

21.3 KB
Raw Blame
import { afterEach, describe, expect, mock, spyOn, test } from 'bun:test';
import { existsSync } from 'node:fs';
import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import scenePacks from '../src/data/scene-packs.json';
import { farmScene, foundryFloorScene, goldenGateScene } from '../src/data/scenes';
import { hashBytes } from './mirror-core.mjs';
import { comparePackRecord, compareRuntimeRecord, main, packRecord, parseSums, stagePack, stagedPackDirectory, verifyPack } from './scene-pack.mjs';
import { CEILINGS, checkCeiling, measureFrameRuntime } from './scene-runtime.mjs';

const directories: string[] = [];
test('review release suffixes stay confined to one pack directory', () => {
  expect(stagedPackDirectory({ base: '/scene-packs/farm/r35-local-review/' }, '/site'))
    .toBe(resolve('/site/public/scene-packs/farm/r35-local-review'));
  for (const base of ['/scene-packs/farm/../', '/scene-packs/farm/r35/../../', '/scene-packs/farm/-review/', '/scene-packs/farm/r35\\escape/'])
    expect(() => stagedPackDirectory({ base }, '/site')).toThrow('Unexpected');
});

test('packs-off mode clears served scenes even when an explicit pack input exists', async () => {
  const { root } = await fixture();
  const site = join(root, 'site');
  for (const directory of ['scene-packs/farm/r1', 'scene-runtime/farm', 'scene-runtime/golden-gate']) {
    await mkdir(join(site, 'public', directory), { recursive: true });
    await writeFile(join(site, 'public', directory, 'stale.json'), '{}');
  }
  await main(['--scene', 'farm', '--source', root], { KILN_SITE_PACKS: '0' }, site);
  expect(existsSync(join(site, 'public/scene-packs/farm'))).toBe(false);
  expect(existsSync(join(site, 'public/scene-runtime/farm'))).toBe(false);
});
afterEach(async () => {
  mock.restore();
  for (const directory of directories.splice(0)) await rm(directory, { recursive: true, force: true });
});

const files: Record<string, string> = {
  'models/a.glb': 'model a',
  'models/b.glb': 'model b, a little longer',
  'data/layout.json': '{"cells":[]}',
  'licenses/ASSET-LICENSE.txt': 'licence text',
};

const MODULES = ['C:/scenes/packages/scene-kit/src/renderer/three-runtime.ts', 'C:/scenes/node_modules/three/build/three.core.js', 'C:/scenes/node_modules/react/index.js'];

/** A small pack in the standalone layout: assets/{pack.json,SHA256SUMS,...} beside the notices. */
async function fixture(id = 'farm', content: Record<string, string> = files) {
  const root = await mkdtemp(join(tmpdir(), 'kiln-scene-pack-'));
  directories.push(root);
  const assets = join(root, 'assets');
  for (const [path, text] of Object.entries(content)) {
    await mkdir(join(assets, path, '..'), { recursive: true });
    await writeFile(join(assets, path), text);
  }
  const sealed = Object.entries(content).map(([path, text]) => ({ path, bytes: Buffer.byteLength(text), sha256: hashBytes(Buffer.from(text)) }));
  await writeFile(join(assets, 'SHA256SUMS'), sealed.map((file) => `${file.sha256}  ${file.path}\n`).join(''));
  await writeFile(
    join(assets, 'pack.json'),
    JSON.stringify({
      schema: 'kiln.scene-pack/1',
      id,
      release: 'r9',
      three: '0.186.0',
      models: [{ id: 'a', path: 'models/a.glb' }, { id: 'b', path: 'models/b.glb' }],
      data: { layout: 'data/layout.json' },
      files: sealed,
    }),
  );
  await writeFile(join(assets, 'index-abc.js'), 'not part of the pack');
  await writeFile(join(root, 'bundle-modules.json'), JSON.stringify({ modules: MODULES }));
  await writeFile(join(root, 'THIRD-PARTY-NOTICES.txt'), 'notices');
  return { root, assets, notices: join(root, 'THIRD-PARTY-NOTICES.txt') };
}

describe('scene pack staging', () => {
  test('an initial-load receipt must name the sealed pack release even when its pack hash matches', async () => {
    const { root, assets } = await fixture('foundry-floor');
    const pack = JSON.parse(await readFile(join(assets, 'pack.json'), 'utf8'));
    pack.release = 'ff3-review2';
    const bytes = Buffer.from(JSON.stringify(pack));
    await writeFile(join(assets, 'pack.json'), bytes);
    await writeFile(join(root, 'bundle-public.json'), JSON.stringify({ mode: 'public', release: 'ff3', packSha256: hashBytes(bytes), chunks: [], initialChunks: [] }));
    await expect(measureFrameRuntime({ id: 'foundry-floor', source: root })).rejects.toThrow(/release/);
  });
  test('copies a verified pack byte for byte and reports its totals', async () => {
    const { root } = await fixture();
    const target = join(root, 'served');
    await mkdir(target, { recursive: true });
    await writeFile(join(target, 'stale.txt'), 'left by an earlier stage');
    const inventory = await stagePack({ source: root, target });
    const sealedBytes = Object.values(files).reduce((sum, text) => sum + Buffer.byteLength(text), 0);
    expect(inventory).toMatchObject({ id: 'farm', release: 'r9', sealedFiles: 4, sealedBytes, totalFiles: 7 });
    const overhead = ['pack.json', 'SHA256SUMS'].reduce((sum, name) => sum + Bun.file(join(root, 'assets', name)).size, 0) + Buffer.byteLength('notices');
    expect(inventory.totalBytes).toBe(sealedBytes + overhead);
    for (const [path, text] of Object.entries(files)) expect(await readFile(join(target, path), 'utf8')).toBe(text);
    expect(await readFile(join(target, 'THIRD-PARTY-NOTICES.txt'), 'utf8')).toBe('notices');
    expect((await readdir(target)).sort()).toEqual(['SHA256SUMS', 'THIRD-PARTY-NOTICES.txt', 'data', 'licenses', 'models', 'pack.json']);
    expect((await verifyPack(target, join(target, 'THIRD-PARTY-NOTICES.txt'))).totalBytes).toBe(inventory.totalBytes);
  });

  test('refuses a corrupt, resized, unsealed or unlisted file', async () => {
    const corrupt = await fixture();
    await writeFile(join(corrupt.assets, 'models/a.glb'), 'model X');
    await expect(verifyPack(corrupt.assets, corrupt.notices)).rejects.toThrow('SHA-256');

    const unsealed = await fixture();
    await writeFile(join(unsealed.assets, 'models/extra.glb'), 'not sealed');
    await expect(verifyPack(unsealed.assets, unsealed.notices)).rejects.toThrow('Unsealed');

    const missing = await fixture();
    await rm(join(missing.assets, 'data/layout.json'));
    await expect(verifyPack(missing.assets, missing.notices)).rejects.toThrow('missing');

    const unlisted = await fixture();
    const manifest = JSON.parse(await readFile(join(unlisted.assets, 'pack.json'), 'utf8'));
    manifest.files.pop();
    await writeFile(join(unlisted.assets, 'pack.json'), JSON.stringify(manifest));
    await expect(verifyPack(unlisted.assets, unlisted.notices)).rejects.toThrow('does not');

    const resized = await fixture();
    const sized = JSON.parse(await readFile(join(resized.assets, 'pack.json'), 'utf8'));
    sized.files[0].bytes += 1;
    await writeFile(join(resized.assets, 'pack.json'), JSON.stringify(sized));
    await expect(verifyPack(resized.assets, resized.notices)).rejects.toThrow('Size');
  });

  test('every directory of the pack must be sealed, not only the ones a scene names', async () => {
    const { assets, notices } = await fixture();
    await mkdir(join(assets, 'vehicles'), { recursive: true });
    await writeFile(join(assets, 'vehicles/loose.glb'), 'not sealed');
    await expect(verifyPack(assets, notices)).rejects.toThrow('Unsealed file in the scene pack: vehicles/loose.glb');
  });

  test('rejects malformed, duplicate and escaping SHA256SUMS entries', () => {
    const digest = 'a'.repeat(64);
    expect(parseSums(`${digest}  models/a.glb\n`).get('models/a.glb')).toBe(digest);
    expect(() => parseSums('')).toThrow('no files');
    expect(() => parseSums('not a digest  models/a.glb\n')).toThrow('Malformed');
    expect(() => parseSums(`${digest}  models/a.glb\n${digest}  models/a.glb\n`)).toThrow('Duplicate');
    expect(() => parseSums(`${digest}  ../outside.glb\n`)).toThrow('Unsafe');
    expect(() => parseSums(`${digest}  /absolute.glb\n`)).toThrow('Unsafe');
  });

  test('refuses a sealed pack that carries a local user path, before copying anything', async () => {
    // The Golden Gate g5 terrain record named the author's local path (design and engineering reviews, finding 1).
    const path = ['C:', 'Users', 'alexq', 'X', 'kiln-commons', 'golden-gate.glb'].join('\\');
    const { root } = await fixture('golden-gate', { ...files, 'terrain/frame.json': `{"bridge_glb":{"path":"${path}"}}` });
    const target = join(root, 'served');
    await mkdir(target, { recursive: true });
    await writeFile(join(target, 'kept.txt'), 'previous stage');
    await expect(stagePack({ source: root, target, names: ['alexq'] })).rejects.toThrow('The scene pack carries private data and is not staged (2)');
    expect(await readFile(join(target, 'kept.txt'), 'utf8')).toBe('previous stage');
    // The build's own module list beside the pack is not part of it and is never copied, so it is not scanned.
    const clean = await fixture('golden-gate');
    await writeFile(join(clean.root, 'bundle-modules.json'), JSON.stringify({ modules: [['C:', 'Users', 'alexq', 'scenes'].join('/')] }));
    await expect(stagePack({ source: clean.root, target: join(clean.root, 'served'), names: ['alexq'] })).resolves.toMatchObject({ id: 'golden-gate' });
  });

  test('a stage that cannot verify its source leaves the served copy untouched', async () => {
    const { root, assets } = await fixture();
    const target = join(root, 'served');
    await mkdir(target, { recursive: true });
    await writeFile(join(target, 'kept.txt'), 'previous stage');
    await writeFile(join(assets, 'models/a.glb'), 'model X');
    await expect(stagePack({ source: root, target })).rejects.toThrow('SHA-256');
    expect(await readFile(join(target, 'kept.txt'), 'utf8')).toBe('previous stage');
  });
});

describe('scene pack command', () => {
  /** A site directory whose scene pack catalog holds `records`, beside the pack fixture's root. */
  async function site(root: string, records: Record<string, unknown>) {
    const directory = join(root, 'site');
    await mkdir(join(directory, 'src/data'), { recursive: true });
    await writeFile(join(directory, 'src/data/scene-packs.json'), JSON.stringify(records));
    return directory;
  }
  const catalogOf = async (directory: string) => JSON.parse(await readFile(join(directory, 'src/data/scene-packs.json'), 'utf8'));
  const quiet = () => spyOn(console, 'log').mockImplementation(() => {});
  const off = { KILN_SITE_SCENES_DIR: 'off' };

  test('without a workspace or pack it skips and clears every pack staged earlier', async () => {
    quiet();
    const { root } = await fixture();
    const directory = await site(root, { farm: { base: '/scene-packs/farm/r9/', source: 'packages/farm/dist/r9/standalone' } });
    for (const release of ['r8', 'r9']) {
      await mkdir(join(directory, 'public/scene-packs/farm', release), { recursive: true });
      await writeFile(join(directory, 'public/scene-packs/farm', release, 'pack.json'), '{}');
    }
    await mkdir(join(directory, 'public/scene-runtime/golden-gate'), { recursive: true });
    await writeFile(join(directory, 'public/scene-runtime/golden-gate/runtime.json'), '{}');
    expect(await main([], off, directory)).toEqual([]);
    expect(existsSync(join(directory, 'public/scene-packs'))).toBe(false);
    expect(existsSync(join(directory, 'public/scene-runtime/golden-gate'))).toBe(false);
    expect(await main([], off, directory)).toEqual([]);
  });

  test('stages the pack its record agrees with and refuses one that has drifted', async () => {
    quiet();
    const { root, assets, notices } = await fixture();
    const inventory = await verifyPack(assets, notices);
    const directory = await site(root, { farm: packRecord(inventory) });
    const env = { ...off, KILN_SITE_SCENE_PACK_DIR: root };
    await mkdir(join(directory, 'public/scene-packs/farm/r8'), { recursive: true });
    await writeFile(join(directory, 'public/scene-packs/farm/r8/pack.json'), '{}');
    const staged = await main([], env, directory);
    expect(staged.map((entry: { totalBytes: number }) => entry.totalBytes)).toEqual([inventory.totalBytes]);
    expect(await readFile(join(directory, 'public/scene-packs/farm/r9/models/a.glb'), 'utf8')).toBe('model a');
    expect(existsSync(join(directory, 'public/scene-packs/farm/r8'))).toBe(false);

    await writeFile(join(directory, 'src/data/scene-packs.json'), JSON.stringify({ farm: { ...packRecord(inventory), totalBytes: inventory.totalBytes + 1 } }));
    await expect(main([], env, directory)).rejects.toThrow('disagrees');
  });

  test('--record rewrites the catalog record from the verified pack and stages it', async () => {
    quiet();
    const { root, assets, notices } = await fixture();
    const inventory = await verifyPack(assets, notices);
    const directory = await site(root, { farm: { ...packRecord(inventory), release: 'r8', base: '/scene-packs/farm/r8/', totalBytes: 1 }, other: { kept: true } });
    await main(['--record'], { ...off, KILN_SITE_SCENE_PACK_DIR: root }, directory);
    const written = await catalogOf(directory);
    expect(written.farm).toEqual(packRecord(inventory));
    expect(written.other).toEqual({ kept: true });
    expect(existsSync(join(directory, 'public/scene-packs/farm/r9/pack.json'))).toBe(true);
  });

  test('--scene stages one scene and leaves another one staged', async () => {
    quiet();
    const { root, assets, notices } = await fixture();
    const inventory = await verifyPack(assets, notices);
    const directory = await site(root, { farm: packRecord(inventory) });
    await mkdir(join(directory, 'public/scene-packs/golden-gate/g3'), { recursive: true });
    await writeFile(join(directory, 'public/scene-packs/golden-gate/g3/pack.json'), '{}');
    await main(['--scene', 'farm'], { ...off, KILN_SITE_SCENE_PACK_DIR: root }, directory);
    expect(existsSync(join(directory, 'public/scene-packs/farm/r9/pack.json'))).toBe(true);
    expect(existsSync(join(directory, 'public/scene-packs/golden-gate/g3/pack.json'))).toBe(true);
    await expect(main(['--scene', 'nowhere'], off, directory)).rejects.toThrow('Unknown scene');
    await expect(main(['--source', root], off, directory)).rejects.toThrow('--source needs --scene');
  });

  test('a standalone-built scene also stages its chunk as built, and drift in it is named', async () => {
    quiet();
    const { root, assets, notices } = await fixture('golden-gate');
    const inventory = await verifyPack(assets, notices);
    const { record } = await measureFrameRuntime({ id: 'golden-gate', source: root });
    const directory = await site(root, { 'golden-gate': { ...packRecord(inventory), runtime: record } });
    const env = { ...off, KILN_SITE_SCENE_PACK_DIR_GOLDEN_GATE: root };
    await main(['--scene', 'golden-gate'], env, directory);
    const staged = join(directory, 'public/scene-runtime/golden-gate');
    expect((await readdir(staged)).sort()).toEqual(['frame.html', 'index-abc.js', 'runtime.json']);
    expect(await readFile(join(staged, 'index-abc.js'), 'utf8')).toBe('not part of the pack');
    expect(await readFile(join(directory, 'public/scene-packs/golden-gate/r9/models/a.glb'), 'utf8')).toBe('model a');
    // The chunk beside the pack is the scene's code, not pack data: it is not served under the pack.
    expect(existsSync(join(directory, 'public/scene-packs/golden-gate/r9/index-abc.js'))).toBe(false);

    await writeFile(join(root, 'assets/index-abc.js'), 'a different chunk');
    await expect(main(['--scene', 'golden-gate'], env, directory)).rejects.toThrow('runtime.sha256');
    expect(existsSync(staged)).toBe(false);
  });
});

describe('scene pack catalog record', () => {
  test('a record built from a verified pack agrees with it, and drift names the field', async () => {
    const { assets, notices } = await fixture();
    const inventory = await verifyPack(assets, notices);
    const record = packRecord(inventory);
    expect(record).toMatchObject({ release: 'r9', base: '/scene-packs/farm/r9/', source: 'packages/farm/dist/m4/standalone' });
    expect(comparePackRecord(record, inventory)).toEqual([]);
    expect(comparePackRecord({ ...record, totalBytes: record.totalBytes + 1 }, inventory)[0]).toContain('totalBytes');
    expect(comparePackRecord({ ...record, release: 'r10' }, inventory)[0]).toContain('release');
    expect(comparePackRecord(undefined, inventory)).toEqual(['scene-packs.json has no record for farm']);
  });

  test('a recorded runtime that differs from its build names the field', () => {
    const recorded = { kind: 'frame', file: 'index-a.js', bytes: 10, gzipBytes: 5, gzipMethod: 'bun-zlib', sha256: 'a'.repeat(64), modulesSha256: 'b'.repeat(64) };
    expect(compareRuntimeRecord(recorded, { ...recorded })).toEqual([]);
    expect(compareRuntimeRecord(recorded, { ...recorded, bytes: 11 })).toEqual(['runtime.bytes: catalog 10, build 11']);
    expect(compareRuntimeRecord(undefined, recorded)).toEqual(['the record has no runtime for this standalone build']);
  });

  test('the Farm record serves the r36 local review with repaired clothing and retained walking controls', () => {
    const record = scenePacks.farm;
    expect(record.release).toBe('r36-local-review');
    expect(record.base).toBe(`/scene-packs/farm/${record.release}/`);
    expect(record.source).toBe('.cache/site-inputs/farm/standalone');
    expect(record).toMatchObject({ sealedFiles: 34, sealedBytes: 7_133_727, packJsonSha256: '5d046aa2c04637436d7e3918db690f4f25f6684a58ae7a78d333dec9df428f48' });
    // The sealed asset pack keeps its original producer version when current runtime code advances.
    expect(record.three).toBe('0.186.0');
    expect(record.totalFiles).toBe(record.sealedFiles + 3);
    expect(record.totalBytes).toBeGreaterThan(record.sealedBytes);
    for (const digest of [record.packJsonSha256, record.sha256sumsSha256, record.noticesSha256]) expect(digest).toMatch(/^[0-9a-f]{64}$/);
    expect(farmScene.assetBase).toBe(record.base);
    expect(farmScene.pack).toBe(record);
    expect(stagedPackDirectory(record, '/site')).toBe(resolve('/site', 'public', 'scene-packs', 'farm', 'r36-local-review'));
    expect(() => stagedPackDirectory({ base: '/../escape/' }, '/site')).toThrow('Unexpected');
  });

  test('the Golden Gate code6 delivery repairs terrain text and retains its runtime inside the ceiling', () => {
    const record = scenePacks['golden-gate'];
    expect(record.release).toBe('g9-code6');
    expect(record.base).toBe('/scene-packs/golden-gate/g9-code6/');
    // Six plus/minus signs and one squared sign add seven UTF-8 bytes; models and runtime remain unchanged.
    expect(record).toMatchObject({ sealedFiles: 103, sealedBytes: 12_186_334, packJsonSha256: '68233d46076cbf86d57502ce612f09d63e8cc125f0b521f19f9eacbec419deb7', sha256sumsSha256: '615c3c3cd059cdffc00a84e29c43296c9a7e951150cdb0f887594450ce1debea' });
    expect(record.source).toBe('.cache/site-inputs/golden-gate/standalone');
    expect(record.three).toBe('0.186.0');
    expect(record.totalFiles).toBe(record.sealedFiles + 3);
    for (const digest of [record.packJsonSha256, record.sha256sumsSha256, record.noticesSha256, record.runtime.sha256, record.runtime.modulesSha256]) expect(digest).toMatch(/^[0-9a-f]{64}$/);
    expect(record.runtime).toMatchObject({ kind: 'frame', file: 'index-DhpWxFro.js', bytes: 1_708_928, gzipBytes: 512_680, sha256: '1a01a81a912157936f05a2060f1df377c418607a83567753e4db2b0257bdb556' });
    expect(checkCeiling('golden-gate', record.runtime).within).toBe(true);
    expect(record.runtime.bytes).toBeLessThanOrEqual(CEILINGS['golden-gate'].bytes);
    expect(goldenGateScene.assetBase).toBe(record.base);
    expect(stagedPackDirectory(record, '/site')).toBe(resolve('/site', 'public', 'scene-packs', 'golden-gate', 'g9-code6'));
  });

  test('the Foundry Floor code5 delivery retains the review2 payload with a verified initial closure inside its ceiling', () => {
    const record = scenePacks['foundry-floor'];
    expect(record.release).toBe('ff3-review2-code5');
    expect(record.base).toBe('/scene-packs/foundry-floor/ff3-review2-code5/');
    expect(record.source).toBe('.cache/site-inputs/foundry-floor/standalone');
    expect(record.three).toBe('0.186.0');
    expect(record.totalFiles).toBe(record.sealedFiles + 3);
    // Final frozen FF3 intake verifies 85 sealed files and every initial/deferred chunk.
    expect(record).toMatchObject({ sealedFiles: 85, sealedBytes: 11_519_818, packJsonSha256: '822be1171621273dfdf857fe6ca320ed41d16e03c49fc49860c13e7092be4836' });
    for (const digest of [record.packJsonSha256, record.sha256sumsSha256, record.noticesSha256, record.runtime.sha256, record.runtime.modulesSha256]) expect(digest).toMatch(/^[0-9a-f]{64}$/);
    expect(record.runtime).toMatchObject({ kind: 'frame', file: 'index-BpDIz-38.js', bytes: 1_710_132, gzipBytes: 519_928, initialLoad: { bytes: 1_532_295, gzipBytes: 448_748 } });
    expect(checkCeiling('foundry-floor', record.runtime).within).toBe(true);
    expect(foundryFloorScene.assetBase).toBe(record.base);
    expect(stagedPackDirectory(record, '/site')).toBe(resolve('/site', 'public', 'scene-packs', 'foundry-floor', 'ff3-review2-code5'));
  });

  // Owner decision 2026-10-26 (Matthew): these home-linked scene pages are indexed, whatever their availability says.
  test.each(['farm', 'golden-gate', 'foundry-floor'])('the %s scene page is indexable', async (id) => {
    const page = await readFile(new URL(`../src/pages/scenes/${id}.astro`, import.meta.url), 'utf8');
    expect(page).not.toMatch(/^\s*noindex(?:=\{[^}]*\})?\s*$/m);
    expect(page).not.toMatch(/^\s*nofollow\s*$/m);
  });
});