Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

16.5 KB
Raw Blame
import { describe, expect, it } from 'vitest';
import {
  EXECUTION_LANE,
  OUTPUT_KIND,
  IMAGE_TO_3D_TARGETS,
  IMAGE_TO_3D_TARGET_IDS,
  DEFAULT_IMAGE_TO_3D_TARGET,
  getTarget,
  unavailableReason,
  isTargetAvailable,
  resolveTarget,
  listTargets,
  detectHostCapabilities,
  renderOptionSupportFor,
} from './targets.js';
import { DEFAULT_DETAIL_TIER, DETAIL_TIERS } from './renderOptions.js';

// A host that can run TRELLIS.2's local-MPS lane, and one that can't.
const APPLE_128GB = { appleSilicon: true, unifiedMemoryGb: 128, cuda: false, cudaProbe: 'absent' };
const APPLE_16GB = { appleSilicon: true, unifiedMemoryGb: 16, cuda: false, cudaProbe: 'absent' };
const INTEL_MAC = { appleSilicon: false, unifiedMemoryGb: 64, cuda: false, cudaProbe: 'absent' };
// A Linux box with a 24 GB card — the supported host for the local-CUDA lane.
const CUDA_BOX = {
  appleSilicon: false, unifiedMemoryGb: 64, linuxHost: true,
  cuda: true, cudaVramGb: 24, cudaProbe: 'available',
};

describe('image-to-3d target registry', () => {
  it('registers trellis2 as the default target with a stable descriptor shape', () => {
    expect(DEFAULT_IMAGE_TO_3D_TARGET).toBe('trellis2');
    expect(IMAGE_TO_3D_TARGET_IDS).toContain('trellis2');
    const t = getTarget('trellis2');
    expect(t).toMatchObject({
      id: 'trellis2',
      label: 'TRELLIS.2',
      executionLane: EXECUTION_LANE.LOCAL_MPS,
      outputKind: OUTPUT_KIND.GLB_MESH,
    });
    expect(t.requires).toMatchObject({ appleSilicon: true, minUnifiedMemoryGb: 24 });
    expect(t.gatedRepos).toEqual([
      {
        label: 'facebook/dinov3-vitl16-pretrain-lvd1689m',
        url: 'https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m',
      },
      {
        label: 'briaai/RMBG-2.0',
        url: 'https://huggingface.co/briaai/RMBG-2.0',
      },
    ]);
  });

  it('registers trellis2Cuda on the local-cuda lane with upstream’s stated floor', () => {
    expect(IMAGE_TO_3D_TARGET_IDS).toContain('trellis2Cuda');
    const t = getTarget('trellis2Cuda');
    expect(t).toMatchObject({
      id: 'trellis2Cuda',
      executionLane: EXECUTION_LANE.LOCAL_CUDA,
      outputKind: OUTPUT_KIND.GLB_MESH,
      upstream: 'https://github.com/microsoft/TRELLIS.2',
    });
    // Upstream: "An NVIDIA GPU with at least 24GB of memory is necessary" and
    // "currently tested only on Linux".
    expect(t.requires).toMatchObject({ cuda: true, minVramGb: 24, linuxHost: true });
    // Same gated repos as the MPS port: both lanes load microsoft/TRELLIS.2-4B, whose
    // pipeline.json names briaai/RMBG-2.0 as the rembg model, and `run()` preprocesses
    // by default. Omitting it here left a CUDA user's 401 at load time unexplained.
    expect(t.gatedRepos.map((r) => r.label))
      .toEqual(['facebook/dinov3-vitl16-pretrain-lvd1689m', 'briaai/RMBG-2.0']);
  });

  it('registers the Apple Silicon Pixal3D port as a separate local-MPS target', () => {
    expect(IMAGE_TO_3D_TARGET_IDS).toContain('pixal3dMps');
    const t = getTarget('pixal3dMps');
    expect(t).toMatchObject({
      id: 'pixal3dMps',
      label: 'Pixal3D (Apple Silicon)',
      executionLane: EXECUTION_LANE.LOCAL_MPS,
      outputKind: OUTPUT_KIND.GLB_MESH,
      upstream: 'https://github.com/TencentARC/Pixal3D',
      port: 'https://github.com/pawel-mazurkiewicz/Pixal3D-mac',
    });
    expect(t.requires).toMatchObject({ appleSilicon: true, minUnifiedMemoryGb: 24 });
    expect(t.gatedRepos).toBeUndefined();
  });

  it('leaves trellis2 (MPS) as the default target', () => {
    // Adding the CUDA lane must not change which target an unqualified request gets.
    expect(DEFAULT_IMAGE_TO_3D_TARGET).toBe('trellis2');
  });

  it('freezes the registry and its descriptors so a target cannot be mutated at runtime', () => {
    expect(Object.isFrozen(IMAGE_TO_3D_TARGETS)).toBe(true);
    expect(Object.isFrozen(IMAGE_TO_3D_TARGETS.trellis2)).toBe(true);
    expect(Object.isFrozen(IMAGE_TO_3D_TARGETS.trellis2.gatedRepos)).toBe(true);
    expect(Object.isFrozen(IMAGE_TO_3D_TARGETS.trellis2.gatedRepos[0])).toBe(true);
    expect(() => {
      IMAGE_TO_3D_TARGETS.trellis2.label = 'hacked';
    }).toThrow();
    expect(getTarget('trellis2').label).toBe('TRELLIS.2');
  });

  it('returns null for an unknown target id', () => {
    expect(getTarget('does-not-exist')).toBeNull();
    expect(getTarget('')).toBeNull();
    expect(getTarget(undefined)).toBeNull();
  });
});

describe('unavailableReason / isTargetAvailable (local-mps gating)', () => {
  it('is available on Apple Silicon with enough memory', () => {
    expect(unavailableReason('trellis2', APPLE_128GB)).toBeNull();
    expect(isTargetAvailable('trellis2', APPLE_128GB)).toBe(true);
  });

  it('is available at exactly the memory floor', () => {
    expect(isTargetAvailable('trellis2', { appleSilicon: true, unifiedMemoryGb: 24 })).toBe(true);
  });

  it('reports requires-apple-silicon on a non-Apple-Silicon host', () => {
    expect(unavailableReason('trellis2', INTEL_MAC)).toBe('requires-apple-silicon');
    expect(isTargetAvailable('trellis2', INTEL_MAC)).toBe(false);
  });

  it('reports insufficient-memory on an under-spec Apple Silicon host', () => {
    expect(unavailableReason('trellis2', APPLE_16GB)).toBe('insufficient-memory');
    expect(isTargetAvailable('trellis2', APPLE_16GB)).toBe(false);
  });

  it('reports unknown-target for an unregistered id', () => {
    expect(unavailableReason('nope', APPLE_128GB)).toBe('unknown-target');
    expect(isTargetAvailable('nope', APPLE_128GB)).toBe(false);
  });

  it('treats absent capabilities as un-runnable rather than throwing', () => {
    expect(unavailableReason('trellis2')).toBe('requires-apple-silicon');
    expect(isTargetAvailable('trellis2', {})).toBe(false);
  });
});

describe('resolveTarget', () => {
  it('resolves the requested target when available', () => {
    expect(resolveTarget('trellis2', APPLE_128GB)).toMatchObject({
      targetId: 'trellis2',
      available: true,
      reason: null,
    });
  });

  it('falls back to the default target id when none requested', () => {
    const r = resolveTarget(undefined, APPLE_128GB);
    expect(r.targetId).toBe(DEFAULT_IMAGE_TO_3D_TARGET);
    expect(r.available).toBe(true);
  });

  it('returns the target with an unavailable verdict rather than silently swapping models', () => {
    const r = resolveTarget('trellis2', APPLE_16GB);
    expect(r.targetId).toBe('trellis2');
    expect(r.target).not.toBeNull();
    expect(r.available).toBe(false);
    expect(r.reason).toBe('insufficient-memory');
  });

  it('reports unknown-target with a null descriptor for a bad id', () => {
    const r = resolveTarget('ghost', APPLE_128GB);
    expect(r).toMatchObject({ targetId: 'ghost', target: null, available: false, reason: 'unknown-target' });
  });

  it('honors a custom defaultId', () => {
    const r = resolveTarget(undefined, APPLE_128GB, { defaultId: 'trellis2' });
    expect(r.targetId).toBe('trellis2');
  });
});

describe('listTargets', () => {
  it('annotates every registered target with availability for the host', () => {
    const available = listTargets(APPLE_128GB);
    expect(available.find((t) => t.id === 'trellis2')).toMatchObject({
      available: true,
      unavailableReason: null,
      gatedRepos: IMAGE_TO_3D_TARGETS.trellis2.gatedRepos,
    });

    // A blocked-but-listed target keeps its reason for the UI to render.
    const blocked = listTargets({ ...CUDA_BOX, linuxHost: false });
    expect(blocked.find((t) => t.id === 'trellis2Cuda')).toMatchObject({
      available: false,
      unavailableReason: 'requires-linux-host',
    });
  });

  it('hides a target blocked for hardware the host simply does not have', () => {
    // A Mac has no NVIDIA GPU and never will — a permanently-red CUDA card is noise.
    expect(listTargets(APPLE_128GB).map((t) => t.id)).toEqual(['trellis2', 'pixal3dMps']);
  });

  it('applies that hiding symmetrically, not just to the newer lane', () => {
    // The mirror of the case above: an NVIDIA box is no more able to grow an Apple
    // Silicon chip than a Mac is to grow a GPU, so neither gets a dead card. Asserted
    // as "no MPS target" rather than an exact list, so registering another CUDA target
    // doesn't churn this test — the property under test is the hiding, not the roster.
    const ids = listTargets(CUDA_BOX).map((t) => t.id);
    expect(ids).not.toContain('trellis2');
    expect(ids).toContain('trellis2Cuda');
  });

  it('lists the CUDA targets independently, per their diverged VRAM floors', () => {
    // The two CUDA lanes no longer share a floor: TRELLIS.2 needs 24 GB, while
    // Pixal3D's low-VRAM mode renders from 12. A 16 GB card must therefore see
    // exactly one of them — the whole reason `insufficient-vram` stopped naming a
    // single GB figure.
    const small = listTargets({ ...CUDA_BOX, cudaVramGb: 16 }).map((t) => t.id);
    expect(small).toContain('pixal3dCuda');
    expect(small).not.toContain('trellis2Cuda');

    const big = listTargets({ ...CUDA_BOX, cudaVramGb: 48 }).map((t) => t.id);
    expect(big).toEqual(expect.arrayContaining(['trellis2Cuda', 'pixal3dCuda']));
  });

  it('still SHOWS a target when the blocker is one the user can fix', () => {
    // Windows + a qualifying card: the lane is reachable via WSL2, so the card must
    // appear with that actionable reason rather than vanish.
    const shown = listTargets({ ...CUDA_BOX, linuxHost: false });
    expect(shown.find((t) => t.id === 'trellis2Cuda')).toMatchObject({
      available: false,
      unavailableReason: 'requires-linux-host',
    });
  });

  it('shows a target whose GPU could not be probed rather than hiding it', () => {
    // "Couldn't tell" is worth surfacing — it only arises on a host that has a driver.
    const shown = listTargets({
      appleSilicon: false, linuxHost: true, cuda: false, cudaProbe: 'unknown',
    });
    expect(shown.find((t) => t.id === 'trellis2Cuda')?.unavailableReason).toBe('cuda-probe-failed');
  });

  it('lists the CUDA target as available on a supported Linux + 24 GB host', () => {
    expect(listTargets(CUDA_BOX).find((t) => t.id === 'trellis2Cuda')).toMatchObject({
      available: true,
      unavailableReason: null,
    });
  });
});

describe('unavailableReason (local-cuda gating)', () => {
  it('is available on a Linux host with a 24 GB card', () => {
    expect(unavailableReason('trellis2Cuda', CUDA_BOX)).toBeNull();
    expect(isTargetAvailable('trellis2Cuda', CUDA_BOX)).toBe(true);
  });

  it('is available at exactly the VRAM floor', () => {
    expect(isTargetAvailable('trellis2Cuda', { ...CUDA_BOX, cudaVramGb: 24 })).toBe(true);
  });

  it('reports requires-cuda on a host with no NVIDIA GPU', () => {
    expect(unavailableReason('trellis2Cuda', APPLE_128GB)).toBe('requires-cuda');
  });

  it('reports the missing GPU before the missing Linux host', () => {
    // A Mac needs to hear "you need an NVIDIA GPU" (final), not "you need Linux"
    // (true, but not the thing standing in the way).
    expect(unavailableReason('trellis2Cuda', { ...APPLE_128GB, linuxHost: false })).toBe('requires-cuda');
  });

  it('reports requires-linux-host on Windows WITH a qualifying card', () => {
    // Upstream builds CUDA extensions against a POSIX toolchain; WSL2 is the route.
    expect(unavailableReason('trellis2Cuda', { ...CUDA_BOX, linuxHost: false }))
      .toBe('requires-linux-host');
  });

  it('reports insufficient-vram for an under-spec card', () => {
    expect(unavailableReason('trellis2Cuda', { ...CUDA_BOX, cudaVramGb: 12 }))
      .toBe('insufficient-vram');
  });

  it('reports cuda-probe-failed — never requires-cuda — when the probe could not run', () => {
    // "We failed to look" must not be reported as "there is no GPU".
    expect(unavailableReason('trellis2Cuda', {
      appleSilicon: false, linuxHost: true, cuda: false, cudaProbe: 'unknown',
    })).toBe('cuda-probe-failed');
  });

  it('reports cuda-probe-failed — never insufficient-vram — for a card of unknown size', () => {
    // A [N/A] VRAM reading is a failed measurement, not a small card; telling the
    // user to buy a bigger GPU they may already own would be wrong.
    expect(unavailableReason('trellis2Cuda', { ...CUDA_BOX, cudaVramGb: null }))
      .toBe('cuda-probe-failed');
  });
});

describe('detectHostCapabilities', () => {
  it('rounds unified memory to whole GB and normalizes flags', async () => {
    const caps = await detectHostCapabilities({
      appleSilicon: true,
      totalMemBytes: 128 * 1024 ** 3,
      linuxHost: false,
      cuda: false,
    });
    expect(caps).toEqual({
      appleSilicon: true,
      unifiedMemoryGb: 128,
      linuxHost: false,
      cuda: false,
      cudaVramGb: null,
      cudaProbe: 'absent',
    });
  });

  it('rounds a hair-under-marketed RAM reading up to the marketed size', async () => {
    // Physical RAM on a "24 GB" Mac reads slightly under 24*1024^3.
    const caps = await detectHostCapabilities({
      appleSilicon: true,
      totalMemBytes: 24 * 1024 ** 3 - 50 * 1024 ** 2,
      cuda: false,
    });
    expect(caps.unifiedMemoryGb).toBe(24);
    expect(isTargetAvailable('trellis2', caps)).toBe(true);
  });

  it('coerces truthy non-boolean overrides to strict booleans', async () => {
    const caps = await detectHostCapabilities({
      appleSilicon: 1, totalMemBytes: 8 * 1024 ** 3, cuda: 'yes',
    });
    expect(caps.appleSilicon).toBe(true);
    expect(caps.cuda).toBe(true);
  });

  it('carries an injected CUDA card straight through to the CUDA lane gate', async () => {
    const caps = await detectHostCapabilities({
      appleSilicon: false,
      totalMemBytes: 64 * 1024 ** 3,
      linuxHost: true,
      cuda: true,
      cudaVramGb: 24,
    });
    expect(caps).toMatchObject({ cuda: true, cudaVramGb: 24, cudaProbe: 'available' });
    expect(isTargetAvailable('trellis2Cuda', caps)).toBe(true);
  });

  it('does not probe the machine when the caller states the CUDA answer', async () => {
    // An injected `cuda` must skip the nvidia-smi subprocess entirely — that is what
    // keeps this deterministic on any CI host, with or without a GPU.
    const caps = await detectHostCapabilities({ cuda: false, totalMemBytes: 8 * 1024 ** 3 });
    expect(caps.cudaProbe).toBe('absent');
    expect(caps.cudaVramGb).toBeNull();
  });
});

describe('renderOptionSupportFor', () => {
  it('reports the unsupported knobs a target declares', () => {
    // Pixal3D's runner drops `steps`; the descriptor is what tells the UI to disable
    // the control and `beginRender` to record null instead of the requested value.
    // `detail` is declared unsupported even though the lane HAS 1024/1536
    // resolutions — they are picked from the card's VRAM, so honoring a caller's
    // choice could hand a 12 GB card a config that OOMs mid-render.
    expect(renderOptionSupportFor('pixal3dCuda'))
      .toEqual({ steps: false, detail: false, alphaMode: false, normalMap: false });
    // The Apple port has a shared 1024 default and no alpha/normal-map CLI controls;
    // sampler steps remain supported and therefore are intentionally absent here.
    expect(renderOptionSupportFor('pixal3dMps'))
      .toEqual({ detail: false, alphaMode: false, normalMap: false });
    // Upstream's CUDA entrypoint takes no pipeline-type override at all.
    expect(renderOptionSupportFor('trellis2Cuda'))
      .toEqual({ detail: false, alphaMode: false, normalMap: false });
  });

  it('returns null for a target that honors every knob, and for an unknown id', () => {
    // Absent must mean "all supported", so existing targets need no descriptor entry
    // and an unknown id can't be mistaken for "supports nothing".
    expect(renderOptionSupportFor('trellis2')).toBeNull();
    expect(renderOptionSupportFor('nope')).toBeNull();
    expect(renderOptionSupportFor(undefined)).toBeNull();
  });

  // Guards the contract between the abstract tier and each lane's own vocabulary:
  // a target that declares detail support must be able to resolve every tier, and
  // one that declares it unsupported must not carry a half-filled mapping.
  it('pairs detail support with a complete tier mapping', () => {
    for (const id of IMAGE_TO_3D_TARGET_IDS) {
      const target = IMAGE_TO_3D_TARGETS[id];
      const supportsDetail = target.supportsRenderOptions?.detail !== false;
      if (supportsDetail) {
        expect(target.detailTiers, id).toBeDefined();
        // Every non-auto tier must map, or picking it would silently fall back.
        for (const tier of DETAIL_TIERS.filter((t) => t !== DEFAULT_DETAIL_TIER)) {
          expect(target.detailTiers[tier], `${id}.${tier}`).toBeTruthy();
        }
      } else {
        expect(target.detailTiers, id).toBeUndefined();
      }
    }
  });
});