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.

17.8 KB
Raw Blame
import { expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { mkdtemp, readFile, rm, readdir } from 'node:fs/promises';
import { join, resolve } from 'node:path';
import { tmpdir } from 'node:os';
import { decodeAssetBundle } from './assets';
import { BACKDROPS } from './views/background';
import { PAD } from './views/grid';
import { decodePng } from './views/png';

test('CLI saves, exports, imports, and restores a revision across independent stores', async () => {
  const root = await mkdtemp(join(tmpdir(), 'kiln-asset-cli-'));
  const cli = resolve('src/cli.ts');
  const run = (workspace: string, args: string[]) =>
    spawnSync(process.execPath, [cli, ...args], {
      cwd: root,
      env: {
        ...process.env,
        KILN_RENDER: 'cpu',
        KILN_EVALUATOR_MODE: 'in-process',
        KILN_PROGRAM_STORE: join(root, workspace, '.kiln', 'programs'),
        KILN_COLLECTIONS: JSON.stringify({ project: join(root, workspace, 'collection') }),
      },
      encoding: 'utf8',
      windowsHide: true,
    });
  try {
    const saved = run('first', [
      'save',
      resolve('src/__tests__/fixtures/crate.kiln.js'),
      '--name',
      'Crate',
      '--model',
      'example-model',
      '--harness',
      'example-harness',
      '--author',
      'Original author',
      '--render',
      'cpu',
    ]);
    expect(saved.status).toBe(0);
    // Name the failure. A `save` that exits 0 with empty stdout is the silent
    // early-exit this suite mistook for flakiness for weeks; assert the output
    // exists before parsing, so a regression reports the command rather than a
    // JSON syntax error several frames away from the cause.
    expect(saved.stdout.length).toBeGreaterThan(0);
    const asset = JSON.parse(saved.stdout).asset;
    const file = join(root, 'crate.zip');
    expect(run('first', ['export', asset.assetId, asset.revisionId, '--out', file]).status).toBe(0);
    const again = run('first', ['export', asset.assetId, asset.revisionId, '--out', file]);
    expect(again.status).toBe(1);
    expect(again.stderr).toContain(`${file} already exists and is never replaced`);
    expect(decodeAssetBundle(new Uint8Array(await readFile(file)))[0]!.manifest.revisionId).toBe(
      asset.revisionId,
    );
    expect(
      decodeAssetBundle(new Uint8Array(await readFile(file)))[0]!.manifest.attribution,
    ).toEqual({
      model: 'example-model',
      harness: 'example-harness',
      author: 'Original author',
    });
    const importedRun = run('second', ['import', file]);
    expect(importedRun.status).toBe(0);
    // Import names where the copy landed, so a surprising root is visible at once.
    const imported = JSON.parse(importedRun.stdout);
    const secondCollection = join(root, 'second', 'collection');
    expect(imported.collection).toBe('project');
    expect(imported.directory).toBe(secondCollection);
    expect(imported.assets).toHaveLength(1);
    expect(imported.assets[0]).toMatchObject({
      assetId: asset.assetId,
      revisionId: asset.revisionId,
      path: join(secondCollection, asset.assetId, 'revisions', asset.revisionId),
    });
    expect(await readdir(imported.assets[0].path)).toContain('manifest.json');
    const restored = run('second', ['asset', asset.assetId, asset.revisionId, '--restore']);
    expect(restored.status).toBe(0);
    expect(JSON.parse(restored.stdout).programRef).toMatch(/^p_/);
    expect(run('second', ['import', file]).status).toBe(0);
    // Commands that print JSON already accept --json and ignore it; view prints none.
    expect(JSON.parse(run('second', ['assets', '--json']).stdout).assets.length).toBe(1);
    const view = run('second', ['view', '--json']);
    expect(view.status).toBe(2);
    expect(view.stderr).toContain('service status|reprobe');
    const canonical = decodeAssetBundle(new Uint8Array(await readFile(file)))[0]!.files[
      'asset.glb'
    ]!;
    const editable = join(root, 'editable.glb');
    const sha256 = (bytes: Uint8Array) =>
      `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
    const editableRun = run('first', [
      'export',
      asset.assetId,
      asset.revisionId,
      '--out',
      editable,
      '--format',
      'glb',
      '--profile',
      'editable',
      '--json',
    ]);
    expect(editableRun.status).toBe(0);
    expect(JSON.parse(editableRun.stdout)).toEqual({
      ok: true,
      collection: 'project',
      assetId: asset.assetId,
      revisionId: asset.revisionId,
      profile: 'editable',
      format: 'glb',
      files: [{ kind: 'glb', path: editable, bytes: canonical.length, sha256: sha256(canonical) }],
      drawDiagnostics: expect.objectContaining({
        version: 'kiln.draw-diagnostics.v1',
        status: 'assessed',
        currentDraws: expect.any(Number),
      }),
    });
    expect(new Uint8Array(await readFile(editable))).toEqual(Uint8Array.from(canonical));
    const runtime = join(root, 'runtime.glb');
    const runtimeRun = run('first', [
      'export',
      asset.assetId,
      asset.revisionId,
      '--out',
      runtime,
      '--profile',
      'runtime',
      '--json',
    ]);
    expect(runtimeRun.status).toBe(0);
    const metadataPath = join(root, 'runtime.kiln-metadata.json');
    const receipt = JSON.parse(runtimeRun.stdout);
    expect(receipt).toMatchObject({ ok: true, profile: 'runtime', format: 'glb' });
    expect(receipt.drawDiagnostics).toMatchObject({
      version: 'kiln.draw-diagnostics.v1',
      status: 'assessed',
      currentDraws: expect.any(Number),
    });
    expect(receipt.files).toEqual(
      await Promise.all(
        [
          ['glb', runtime],
          ['metadata', metadataPath],
        ].map(async ([kind, path]) => {
          const bytes = new Uint8Array(await readFile(path!));
          return { kind, path, bytes: bytes.length, sha256: sha256(bytes) };
        }),
      ),
    );
    const metadata = JSON.parse(await readFile(metadataPath, 'utf8'));
    expect(metadata.version).toBe('kiln.runtime-metadata.v1');
    expect(metadata.source.revisionId).toBe(asset.revisionId);
    const runtimeBefore = await readFile(runtime);
    expect(
      run('first', [
        'export',
        asset.assetId,
        asset.revisionId,
        '--out',
        runtime,
        '--profile',
        'runtime',
      ]).status,
    ).toBe(1);
    expect(await readFile(runtime)).toEqual(runtimeBefore);
    // The three.js runtime target: derived GLB plus a sidecar with its delivery facts.
    const three = join(root, 'three.glb');
    const threeRun = run('first', [
      'export',
      asset.assetId,
      asset.revisionId,
      '--out',
      three,
      '--profile',
      'runtime',
      '--target',
      'three',
      '--json',
    ]);
    expect(threeRun.status).toBe(0);
    expect(JSON.parse(threeRun.stdout)).toMatchObject({
      ok: true,
      profile: 'runtime',
      target: 'three',
      format: 'glb',
    });
    expect(
      JSON.parse(await readFile(join(root, 'three.kiln-metadata.json'), 'utf8')),
    ).toMatchObject({
      version: 'kiln.runtime-metadata.v1',
      target: 'three',
      delivery: {
        target: 'three',
        extensionsRequired: expect.arrayContaining(['EXT_meshopt_compression']),
        ktx2: { status: 'skipped' },
      },
    });
    // Without Meshopt for loaders that have no decoder; the sidecar records the choice.
    const plain = join(root, 'plain.glb');
    const plainRun = run('first', [
      'export',
      asset.assetId,
      asset.revisionId,
      '--out',
      plain,
      '--profile',
      'runtime',
      '--target',
      'three',
      '--compression',
      'none',
      '--json',
    ]);
    expect(plainRun.status).toBe(0);
    expect(JSON.parse(plainRun.stdout)).toMatchObject({ target: 'three', compression: 'none' });
    const plainDelivery = JSON.parse(
      await readFile(join(root, 'plain.kiln-metadata.json'), 'utf8'),
    ).delivery;
    expect(plainDelivery.compression).toEqual({ extension: 'none' });
    expect(plainDelivery.extensionsRequired).not.toContain('EXT_meshopt_compression');
    // #196: --max-lod passes through to the sidecar, which records the choice.
    const lod0Run = run('first', [
      'export',
      asset.assetId,
      asset.revisionId,
      '--out',
      join(root, 'lod0.glb'),
      '--profile',
      'runtime',
      '--target',
      'three',
      '--max-lod',
      '0',
      '--json',
    ]);
    expect(lod0Run.status, lod0Run.stderr).toBe(0);
    expect(JSON.parse(lod0Run.stdout)).toMatchObject({ target: 'three', maxLod: 0 });
    expect(
      JSON.parse(await readFile(join(root, 'lod0.kiln-metadata.json'), 'utf8')).delivery.lod,
    ).toMatchObject({ maxLod: 0, budgetTiersOmitted: [] });
    // #197: --position-bits reaches the sidecar, which reports the grid step it produced.
    const floatRun = run('first', [
      'export',
      asset.assetId,
      asset.revisionId,
      '--out',
      join(root, 'float.glb'),
      '--profile',
      'runtime',
      '--target',
      'three',
      '--position-bits',
      'float',
      '--json',
    ]);
    expect(floatRun.status, floatRun.stderr).toBe(0);
    expect(JSON.parse(floatRun.stdout)).toMatchObject({ target: 'three', positionBits: 'float' });
    expect(
      JSON.parse(await readFile(join(root, 'float.kiln-metadata.json'), 'utf8')).delivery
        .quantization,
    ).toMatchObject({ bits: { position: 'float32' }, maxPositionStep: 0 });
    // --draws minimal derives the reduced runtime file and states what it did.
    const drawsRun = run('first', [
      'export',
      asset.assetId,
      asset.revisionId,
      '--out',
      join(root, 'draws.glb'),
      '--profile',
      'runtime',
      '--draws',
      'minimal',
      '--draw-cell',
      '30',
      '--json',
    ]);
    expect(drawsRun.status, drawsRun.stderr).toBe(0);
    expect(JSON.parse(drawsRun.stdout)).toMatchObject({ draws: 'minimal', drawCellSize: 30 });
    expect(
      JSON.parse(await readFile(join(root, 'draws.kiln-metadata.json'), 'utf8')).drawReduction,
    ).toMatchObject({ cellSize: 30 });
    for (const flags of [
      ['--draws', 'minimal'],
      ['--profile', 'runtime', '--draws', 'max'],
      ['--profile', 'runtime', '--draw-cell', '15'],
      ['--profile', 'runtime', '--draws', 'minimal', '--draw-cell', '0'],
      ['--profile', 'runtime', '--position-bits', '16'],
      ['--profile', 'runtime', '--target', 'three', '--position-bits', '7'],
      ['--profile', 'runtime', '--target', 'three', '--position-bits', '17'],
      ['--profile', 'runtime', '--target', 'three', '--position-bits', 'half'],
      ['--profile', 'runtime', '--max-lod', '0'],
      ['--profile', 'runtime', '--target', 'three', '--max-lod', '-1'],
      ['--profile', 'runtime', '--target', 'three', '--max-lod', '1.5'],
      ['--profile', 'runtime', '--target', 'three', '--max-lod', 'all'],
      ['--profile', 'editable', '--target', 'three'],
      ['--profile', 'runtime', '--target', 'unity'],
      ['--profile', 'runtime', '--compression', 'none'],
      ['--profile', 'runtime', '--target', 'three', '--compression', 'zstd'],
      ['--profile', 'unknown'],
      ['--profile', 'runtime', '--format', 'bundle'],
      ['--profile', 'runtime', '--format', 'source'],
    ]) {
      expect(
        run('first', [
          'export',
          asset.assetId,
          asset.revisionId,
          '--out',
          join(root, 'bad.glb'),
          ...flags,
        ]).status,
      ).toBe(1);
    }
    expect(await readdir(root)).not.toContain('bad.glb');
  } finally {
    await rm(root, { recursive: true, force: true });
  }
}, 120_000); // Many compiled-CLI runs: 6.9 to 9.6 s in the gates of 2 October 2026, 18.9 s in a fresh clone's gate beside two live sessions, and past 30 s in the final gate's test step on a host at 97% CPU (10.7 s in that run's coverage step).

test('CLI collections name each directory, and add refuses a Windows root without a drive', async () => {
  const root = await mkdtemp(join(tmpdir(), 'kiln-collections-cli-'));
  const env: Record<string, string | undefined> = {
    ...process.env,
    KILN_WORKSPACE: root,
    KILN_PROGRAM_STORE: join(root, '.kiln', 'programs'),
    XDG_DATA_HOME: join(root, 'user-data'),
  };
  delete env.KILN_COLLECTIONS;
  const run = (args: string[]) =>
    spawnSync(process.execPath, [resolve('src/cli.ts'), ...args], {
      cwd: root,
      env,
      encoding: 'utf8',
      windowsHide: true,
    });
  const listed = () => JSON.parse(run(['collections']).stdout).collections;
  try {
    expect(listed()).toEqual([
      { id: 'project', label: 'Workspace storage', directory: join(root, 'assets', 'kiln') },
      {
        id: 'library',
        label: 'User library storage',
        directory: join(root, 'user-data', 'kiln', 'library'),
      },
    ]);
    // A relative directory is the caller's: it resolves against the working directory.
    expect(run(['collections', 'add', 'game', 'game-assets']).status).toBe(0);
    expect(listed().at(-1)).toEqual({
      id: 'game',
      label: 'game',
      directory: join(root, 'game-assets'),
    });
    if (process.platform === 'win32') {
      const refused = run(['collections', 'add', 'shell', '/c/Users/example/kiln']);
      expect(refused.status).toBe(1);
      expect(refused.stderr).toContain('Collection shell directory "/c/Users/example/kiln"');
      expect(refused.stderr).toContain('Write it as C:/Users/example/kiln.');
      expect(listed().map((collection: { id: string }) => collection.id)).toEqual([
        'project',
        'library',
        'game',
      ]);
    }
  } finally {
    await rm(root, { recursive: true, force: true });
  }
}, 30000);

test('CLI save paints its preview on the named backdrop and records it, like kiln_save', async () => {
  const root = await mkdtemp(join(tmpdir(), 'kiln-asset-cli-backdrop-'));
  const cli = resolve('src/cli.ts');
  const run = (args: string[]) =>
    spawnSync(process.execPath, [cli, ...args], {
      cwd: root,
      env: {
        ...process.env,
        KILN_RENDER: 'cpu',
        KILN_EVALUATOR_MODE: 'in-process',
        KILN_PROGRAM_STORE: join(root, '.kiln', 'programs'),
        KILN_COLLECTIONS: JSON.stringify({ project: join(root, 'collection') }),
      },
      encoding: 'utf8',
      windowsHide: true,
    });
  try {
    const saved = run([
      'save',
      resolve('src/__tests__/fixtures/crate.kiln.js'),
      '--name',
      'Crate',
      '--render',
      'cpu',
      '--backdrop',
      'dark',
    ]);
    expect(saved.status).toBe(0);
    expect(saved.stdout.length).toBeGreaterThan(0);
    const asset = JSON.parse(saved.stdout).asset;
    const file = join(root, 'crate.zip');
    expect(run(['export', asset.assetId, asset.revisionId, '--out', file]).status).toBe(0);
    const [entry] = decodeAssetBundle(new Uint8Array(await readFile(file)));
    expect(entry!.manifest.preview?.backdrop).toBe('dark');
    const png = decodePng(entry!.files['preview.png']!);
    // A corner inside the sheet's padding is backdrop, whatever the asset is.
    const at = ((PAD + 1) * png.width + (png.width - PAD - 2)) * 3;
    expect([...png.rgb.subarray(at, at + 3)]).toEqual([...BACKDROPS.dark.rgb]);

    // A free colour is refused by the same validation the tool applies.
    const free = run([
      'save',
      resolve('src/__tests__/fixtures/crate.kiln.js'),
      '--name',
      'Crate',
      '--backdrop',
      '#000000',
    ]);
    expect(free.status).not.toBe(0);
  } finally {
    await rm(root, { recursive: true, force: true });
  }
}, 30000);

// Decision 28 of 2 October 2026: `kiln asset <id>` without a revision reads the newest one,
// as `kiln_assets get` does, and `kiln save --help` prints the save usage alone (a blind
// OpenCode run read 16,077 characters of global usage for it).
test('CLI asset without a revision reads the newest one, and save --help prints its own usage', async () => {
  const root = await mkdtemp(join(tmpdir(), 'kiln-asset-cli-newest-'));
  const cli = resolve('src/cli.ts');
  const run = (args: string[]) =>
    spawnSync(process.execPath, [cli, ...args], {
      cwd: root,
      env: {
        ...process.env,
        KILN_RENDER: 'cpu',
        KILN_EVALUATOR_MODE: 'in-process',
        KILN_PROGRAM_STORE: join(root, '.kiln', 'programs'),
        KILN_COLLECTIONS: JSON.stringify({ project: join(root, 'collection') }),
      },
      encoding: 'utf8',
      windowsHide: true,
    });
  try {
    const help = run(['save', '--help']);
    expect(help.status).toBe(0);
    expect(help.stdout).toContain('kiln save <source.js|programRef>');
    expect(help.stdout).not.toContain('kiln view');
    expect(help.stdout.length).toBeLessThan(1500);
    const crate = resolve('src/__tests__/fixtures/crate.kiln.js');
    const first = run(['save', crate, '--name', 'Crate', '--render', 'cpu']);
    expect(first.status).toBe(0);
    const parent = JSON.parse(first.stdout).asset;
    const second = run([
      'save',
      crate,
      '--name',
      'Crate',
      '--render',
      'cpu',
      '--asset',
      parent.assetId,
      '--parent',
      parent.revisionId,
    ]);
    expect(second.status).toBe(0);
    const child = JSON.parse(second.stdout).asset;
    expect(child.revisionId).not.toBe(parent.revisionId);
    const newest = run(['asset', parent.assetId]);
    expect(newest.status).toBe(0);
    expect(JSON.parse(newest.stdout).revisionId).toBe(child.revisionId);
    const named = run(['asset', parent.assetId, parent.revisionId]);
    expect(named.status).toBe(0);
    expect(JSON.parse(named.stdout).revisionId).toBe(parent.revisionId);
    // An export hands off one exact revision and still names it.
    const exported = run(['export', parent.assetId, '--out', join(root, 'crate.zip')]);
    expect(exported.status).not.toBe(0);
    expect(exported.stderr).toContain('revision ID');
  } finally {
    await rm(root, { recursive: true, force: true });
  }
}, 120_000); // Six compiled-CLI runs, two of them CPU saves: the round trip above ran 10 to 30 s on this host and past 30 s at 97% CPU on 2 October 2026, so its 120 s budget applies here.