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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { beforeEach, describe, expect, it, vi } from 'vitest';
import express from 'express';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import { writeFile, rm } from 'node:fs/promises';
import { request } from '../lib/testHelper.js';
import { errorMiddleware } from '../lib/errorHandler.js';
// Mock the services so the route test is deterministic regardless of the test
// host's real arch/memory and never touches a real subprocess.
const TRELLIS2_TARGET = {
id: 'trellis2',
label: 'TRELLIS.2',
executionLane: 'local-mps',
outputKind: 'glb-mesh',
unavailableReason: null,
gatedRepos: [
{
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' },
],
};
// Partial mock: the resolver/probe functions are stubbed so the route tests stay
// hardware-independent, but the reason→label map + `unavailableReasonLabel` come
// from the real module, so the refusal message asserted below is the exact string
// a user would see.
vi.mock('../services/imageTo3d/targets.js', async (importOriginal) => ({
...(await importOriginal()),
detectHostCapabilities: vi.fn(() => ({ appleSilicon: true, unifiedMemoryGb: 128, cuda: false })),
getTarget: vi.fn((id) => (id === 'trellis2' ? TRELLIS2_TARGET : null)),
listTargets: vi.fn((caps) => [
{ ...TRELLIS2_TARGET, available: caps.appleSilicon && caps.unifiedMemoryGb >= 24 },
]),
unavailableReason: vi.fn(() => null),
IMAGE_TO_3D_TARGET_IDS: ['trellis2'],
}));
vi.mock('../services/imageTo3d/trellis2.js', async (importOriginal) => ({
// The pure half (`resolveDegradedBakeRemedy`, the `TRELLIS2_*` constants) comes through
// REAL — the adapter's `degraded` projection is asserted below, so stubbing it would
// test the stub.
...(await importOriginal()),
isTrellis2Installed: vi.fn(() => false),
trellis2Root: vi.fn(() => '/tmp/trellis2'),
installTrellis2: vi.fn(({ onEvent }) => {
onEvent({ type: 'stage', stage: 'clone', message: 'git clone …' });
onEvent({ type: 'complete', message: 'TRELLIS.2 installed.' });
return { promise: Promise.resolve({ ok: true }), kill: vi.fn() };
}),
// Not exercised by these route-level tests (render dispatch is covered in
// models.test.js), but the adapter registry imports it — an incomplete mock
// here would 'no export defined' at import time.
runTrellis2Generate: vi.fn(),
// Both probes shell out (venv python / `xcrun metal`). Mocked to the healthy
// result so the suite never touches the host toolchain; individual tests below
// override them to drive the degraded-install branches (#2952).
probeTrellis2TextureBake: vi.fn(async () => ({
quality: 'metal', modules: {}, missing: [], degradedQuality: [],
})),
probeMetalToolchain: vi.fn(async () => ({ available: true })),
}));
// The install route resolves the central HF child env (#3032).
// Mock it so the suite never reads the host's real settings.json or
// ~/.cache/huggingface/token, and so the resolution-failure branch is drivable.
vi.mock('../services/hfToken.js', () => ({
hfChildEnv: vi.fn(async () => ({ HF_TOKEN: 'hf_test', HUGGINGFACE_HUB_TOKEN: 'hf_test' })),
}));
vi.mock('../services/imageTo3d/models.js', () => ({
listModels: vi.fn(),
getModel: vi.fn(),
createModel: vi.fn(),
startGeneration: vi.fn(),
deleteModel: vi.fn(),
getModelAsset: vi.fn(),
getModelFullMesh: vi.fn(),
getModelUsdz: vi.fn(),
saveModelUsdz: vi.fn(),
USDZ_MAX_BYTES: 64 * 1024 * 1024,
}));
import * as targets from '../services/imageTo3d/targets.js';
import * as trellis2 from '../services/imageTo3d/trellis2.js';
import * as models from '../services/imageTo3d/models.js';
import { hfChildEnv } from '../services/hfToken.js';
import routes from './imageTo3d.js';
const makeApp = () => {
const app = express();
app.use(express.json());
app.use('/api/image-to-3d', routes);
app.use(errorMiddleware);
return app;
};
// Parse `data: {json}\n\n` SSE frames out of a buffered response body.
const sseFrames = (text) => text
.split('\n')
.filter((l) => l.startsWith('data: '))
.map((l) => JSON.parse(l.slice(6)));
describe('image-to-3d routes', () => {
it('GET /targets returns host capabilities and annotated targets', async () => {
const res = await request(makeApp()).get('/api/image-to-3d/targets');
expect(res.status).toBe(200);
expect(res.body.capabilities).toMatchObject({ appleSilicon: true, unifiedMemoryGb: 128 });
expect(Array.isArray(res.body.targets)).toBe(true);
expect(res.body.targets[0]).toMatchObject({
id: 'trellis2',
available: true,
installed: false,
gatedRepos: [
{
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' },
],
});
});
// #2952: an installed TRELLIS.2 whose Metal bake is missing still renders, but
// the surface comes out scrambled — the client needs that distinction to avoid
// showing a flat "Ready".
it('GET /targets annotates an installed trellis2 with its texture-bake quality', async () => {
trellis2.isTrellis2Installed.mockReturnValueOnce(true);
trellis2.probeTrellis2TextureBake.mockResolvedValueOnce({
quality: 'fallback', missing: ['mtldiffrast'], degradedQuality: [], modules: {}, help: 'fix it',
});
const res = await request(makeApp()).get('/api/image-to-3d/targets');
expect(res.body.targets[0].textureBake).toMatchObject({ quality: 'fallback', help: 'fix it' });
});
// #3041: the card must offer the right remedy — Repair install fetches the
// toolchain, but on a Command-Line-Tools-only host nothing PortOS runs can fix it.
it('GET /targets marks a degraded bake repairable when the toolchain is merely missing', async () => {
trellis2.isTrellis2Installed.mockReturnValueOnce(true);
trellis2.probeTrellis2TextureBake.mockResolvedValueOnce({
quality: 'fallback', missing: ['mtldiffrast'], degradedQuality: [], modules: {}, help: 'fix it',
});
trellis2.probeMetalToolchain.mockResolvedValueOnce({ available: false, installable: true });
const res = await request(makeApp()).get('/api/image-to-3d/targets');
expect(res.body.targets[0].textureBake).toMatchObject({ repairable: true, help: 'fix it' });
});
it('GET /targets marks a degraded bake NOT repairable when only Command Line Tools are active', async () => {
trellis2.isTrellis2Installed.mockReturnValueOnce(true);
trellis2.probeTrellis2TextureBake.mockResolvedValueOnce({
quality: 'fallback', missing: ['mtldiffrast'], degradedQuality: [], modules: {}, help: 'fix it',
});
trellis2.probeMetalToolchain.mockResolvedValueOnce({
available: false, installable: false, blocker: 'requires-xcode', hint: 'install Xcode',
});
const res = await request(makeApp()).get('/api/image-to-3d/targets');
expect(res.body.targets[0].textureBake).toMatchObject({
repairable: false, blocker: 'requires-xcode', help: 'install Xcode',
});
});
it('GET /targets does not probe the toolchain for a healthy bake', async () => {
trellis2.probeMetalToolchain.mockClear();
trellis2.isTrellis2Installed.mockReturnValueOnce(true);
const res = await request(makeApp()).get('/api/image-to-3d/targets');
expect(res.body.targets[0].textureBake).toMatchObject({ quality: 'metal' });
expect(res.body.targets[0].textureBake.repairable).toBeUndefined();
// A healthy bake names no modules — and reports no degradation at all.
expect(res.body.targets[0].degraded).toBeUndefined();
expect(trellis2.probeMetalToolchain).not.toHaveBeenCalled();
});
// FINDING: the render-option projection had no route coverage at all, and the client
// does `setRecord(next)` with the POST bodies — so a create/re-render response that
// omitted the field blanked the disabled Quality control until the next poll.
describe('supportsRenderOptions projection', () => {
const record = (target) => ({ id: 'image3d-1', target, status: 'ready', runs: [] });
it('projects the field onto GET, create, and re-render responses', async () => {
const app = makeApp();
models.getModel.mockResolvedValue(record('pixal3dCuda'));
models.createModel.mockResolvedValue(record('pixal3dCuda'));
models.startGeneration.mockResolvedValue(record('pixal3dCuda'));
// Read from the registry rather than restated, so adding a knob to a
// descriptor does not need an edit here to stay honest.
const expected = targets.renderOptionSupportFor('pixal3dCuda');
const get = await request(app).get('/api/image-to-3d/models/image3d-1');
expect(get.body.supportsRenderOptions).toEqual(expected);
const created = await request(app).post('/api/image-to-3d/models')
.send({ filename: 'example.png', name: 'x' });
expect(created.body.supportsRenderOptions).toEqual(expected);
const regen = await request(app).post('/api/image-to-3d/models/image3d-1/generate').send({});
expect(regen.body.supportsRenderOptions).toEqual(expected);
});
it('tells the client the detail control is unusable on a VRAM-derived lane', () => {
// Pixal3D picks 1024/1536 from the card's VRAM, so a rendered-but-ignored
// Detail control would be a lie about what the render will do.
expect(targets.renderOptionSupportFor('pixal3dCuda').detail).toBe(false);
expect(targets.renderOptionSupportFor('trellis2Cuda').detail).toBe(false);
// The MPS lane is the one that honors it.
expect(targets.renderOptionSupportFor('trellis2')).toBeNull();
});
it('omits the field for a target that honors every knob', async () => {
// Absent must mean "all supported" so existing targets need no descriptor entry.
models.getModel.mockResolvedValue(record('trellis2'));
const res = await request(makeApp()).get('/api/image-to-3d/models/image3d-1');
expect(res.body.supportsRenderOptions).toBeUndefined();
});
});
// The `degraded` projection is what the CLIENT actually renders (badge, help panel,
// Repair button); `textureBake` above is retained only for API back-compat and has no
// in-repo reader. These cases pin the live contract, which was previously untested.
it('GET /targets projects a degraded bake into the normalized `degraded` shape', async () => {
trellis2.isTrellis2Installed.mockReturnValueOnce(true);
trellis2.probeTrellis2TextureBake.mockResolvedValueOnce({
quality: 'fallback', missing: ['mtldiffrast'], degradedQuality: [], modules: {}, help: 'fix it',
});
const res = await request(makeApp()).get('/api/image-to-3d/targets');
expect(res.body.targets[0].degraded).toEqual({
label: 'degraded textures',
help: 'fix it',
repairable: true,
// #4636: `help` names the remedy, `detail` names what is actually missing —
// without it a Repair that keeps failing only ever reprints the same sentence.
detail: 'Missing: mtldiffrast',
});
});
it('GET /targets carries repairable:false into `degraded` when nothing PortOS runs can fix it', async () => {
trellis2.isTrellis2Installed.mockReturnValueOnce(true);
trellis2.probeTrellis2TextureBake.mockResolvedValueOnce({
quality: 'fallback', missing: ['mtldiffrast'], degradedQuality: [], modules: {}, help: 'fix it',
});
trellis2.probeMetalToolchain.mockResolvedValueOnce({
available: false, installable: false, blocker: 'requires-xcode', hint: 'install Xcode',
});
const res = await request(makeApp()).get('/api/image-to-3d/targets');
// The inversion here (`repairable !== false`) is easy to get backwards, and getting
// it backwards offers a Repair button that cannot work.
expect(res.body.targets[0].degraded).toMatchObject({ repairable: false, help: 'install Xcode' });
});
it('GET /targets omits `degraded` when the bake probe could not determine anything', async () => {
// The sentinel that matters: 'unknown' must NOT read as degraded, or a probe that
// simply failed makes a healthy install look broken.
trellis2.isTrellis2Installed.mockReturnValueOnce(true);
trellis2.probeTrellis2TextureBake.mockResolvedValueOnce({
quality: 'unknown', missing: [], degradedQuality: [], modules: {},
});
const res = await request(makeApp()).get('/api/image-to-3d/targets');
expect(res.body.targets[0].degraded).toBeUndefined();
});
it('GET /targets omits `degraded` for a healthy bake', async () => {
trellis2.isTrellis2Installed.mockReturnValueOnce(true);
const res = await request(makeApp()).get('/api/image-to-3d/targets');
expect(res.body.targets[0].degraded).toBeUndefined();
});
it('GET /targets skips the bake probe entirely when trellis2 is not installed', async () => {
trellis2.probeTrellis2TextureBake.mockClear();
trellis2.isTrellis2Installed.mockReturnValueOnce(false);
const res = await request(makeApp()).get('/api/image-to-3d/targets');
expect(res.body.targets[0].textureBake).toBeUndefined();
expect(trellis2.probeTrellis2TextureBake).not.toHaveBeenCalled();
});
});
describe('POST /trellis2/install (SSE)', () => {
it('keeps both GET install URLs read-only and returns target status', async () => {
trellis2.installTrellis2.mockClear();
trellis2.isTrellis2Installed.mockReturnValue(false);
const canonical = await request(makeApp()).get('/api/image-to-3d/targets/trellis2/install');
const legacy = await request(makeApp()).get('/api/image-to-3d/trellis2/install');
expect(canonical.status).toBe(200);
expect(canonical.body.target).toMatchObject({ id: 'trellis2', installed: false });
expect(legacy.body.target).toMatchObject({ id: 'trellis2', installed: false });
expect(trellis2.installTrellis2).not.toHaveBeenCalled();
});
it('streams the canonical POST target install route', async () => {
trellis2.isTrellis2Installed.mockReturnValueOnce(false);
const res = await request(makeApp()).post('/api/image-to-3d/targets/trellis2/install');
expect(sseFrames(res.text).at(-1)).toMatchObject({ type: 'complete' });
});
it('streams stage → complete on the happy path', async () => {
trellis2.isTrellis2Installed.mockReturnValueOnce(false);
const res = await request(makeApp()).post('/api/image-to-3d/trellis2/install');
const frames = sseFrames(res.text);
expect(frames).toContainEqual({ type: 'stage', stage: 'clone', message: 'git clone …' });
expect(frames.at(-1)).toMatchObject({ type: 'complete' });
expect(trellis2.installTrellis2).toHaveBeenCalled();
});
// #3041: a missing-but-fetchable toolchain becomes a step of the install itself,
// rather than a command printed for the user to run.
it('tells the install to download the Metal Toolchain when it is missing but fetchable', async () => {
trellis2.installTrellis2.mockClear();
trellis2.isTrellis2Installed.mockReturnValueOnce(false);
trellis2.probeMetalToolchain.mockResolvedValueOnce({
available: false, installable: true, hint: 'it will be downloaded',
});
const res = await request(makeApp()).post('/api/image-to-3d/trellis2/install');
expect(trellis2.installTrellis2).toHaveBeenCalledWith(
expect.objectContaining({ installMetalToolchain: true }),
);
expect(sseFrames(res.text).find((f) => f.stage === 'preflight')?.message).toContain('it will be downloaded');
});
// Without this the user waits out a ~15 GB install and an hour-long render before
// discovering the Metal backends could never have built on this host (#2952).
it('warns but still installs when the toolchain cannot be fetched (Command Line Tools only)', async () => {
trellis2.installTrellis2.mockClear();
trellis2.isTrellis2Installed.mockReturnValueOnce(false);
trellis2.probeMetalToolchain.mockResolvedValueOnce({
available: false, installable: false, blocker: 'requires-xcode', hint: 'install Xcode',
});
const res = await request(makeApp()).post('/api/image-to-3d/trellis2/install');
expect(sseFrames(res.text).find((f) => f.stage === 'preflight')?.message).toContain('install Xcode');
// A warning, not a refusal — geometry is unaffected — and no step that would fail.
expect(trellis2.installTrellis2).toHaveBeenCalledWith(
expect.objectContaining({ installMetalToolchain: false }),
);
});
it('adds no toolchain step or warning when it is already present', async () => {
trellis2.installTrellis2.mockClear();
trellis2.isTrellis2Installed.mockReturnValueOnce(false);
const res = await request(makeApp()).post('/api/image-to-3d/trellis2/install');
expect(sseFrames(res.text).find((f) => f.stage === 'preflight')).toBeUndefined();
expect(trellis2.installTrellis2).toHaveBeenCalledWith(
expect.objectContaining({ installMetalToolchain: false }),
);
});
it('re-runs setup.sh on ?repair=1 instead of short-circuiting on "already installed"', async () => {
// The Repair install button's whole purpose: rebuild the Metal backends over an
// existing install once the Metal Toolchain is present (#2952).
trellis2.installTrellis2.mockClear();
trellis2.isTrellis2Installed.mockReturnValueOnce(true);
const res = await request(makeApp()).post('/api/image-to-3d/trellis2/install?repair=1');
expect(trellis2.installTrellis2).toHaveBeenCalled();
expect(sseFrames(res.text).at(-1)).toMatchObject({ type: 'complete' });
});
it('reports a degraded bake on an already-installed host instead of a bare "nothing to do"', async () => {
trellis2.isTrellis2Installed.mockReturnValueOnce(true);
trellis2.probeTrellis2TextureBake.mockResolvedValueOnce({
quality: 'fallback', missing: ['mtldiffrast'], degradedQuality: [], modules: {}, help: 'repair me',
});
const res = await request(makeApp()).post('/api/image-to-3d/trellis2/install');
const frames = sseFrames(res.text);
const warning = frames.find((f) => f.stage === 'verify' && f.type === 'log')?.message;
expect(warning).toContain('repair me');
// #4636: this lane writes the SAME `verify` stage the install's own hook does, so it
// has to name the culprit too — otherwise one condition emits two different frames
// depending on whether the caller hit the short-circuit or ran the install.
expect(warning).toContain('Missing: mtldiffrast.');
expect(frames.at(-1)).toMatchObject({ type: 'complete' });
});
it('hands the resolved HF token env to the install child', async () => {
// #3032: the install must carry the CENTRAL token (settings-stored included),
// not just whatever the server process happened to be launched with.
trellis2.installTrellis2.mockClear();
trellis2.isTrellis2Installed.mockReturnValueOnce(false);
await request(makeApp()).post('/api/image-to-3d/trellis2/install');
expect(trellis2.installTrellis2).toHaveBeenCalledWith(expect.objectContaining({
env: expect.objectContaining({ HF_TOKEN: 'hf_test', HUGGINGFACE_HUB_TOKEN: 'hf_test' }),
}));
});
it('emits a terminal error frame — not a half-open stream — when the env cannot be resolved', async () => {
// The SSE headers are already flushed by this point, so a throw here can't
// reach the error middleware as JSON; it has to surface as an error frame.
trellis2.installTrellis2.mockClear();
trellis2.isTrellis2Installed.mockReturnValueOnce(false);
hfChildEnv.mockRejectedValueOnce(new Error('settings.json is not valid JSON'));
const res = await request(makeApp()).post('/api/image-to-3d/trellis2/install');
const frames = sseFrames(res.text);
expect(frames.at(-1)).toMatchObject({
type: 'error',
message: expect.stringMatching(/could not prepare.*install environment.*settings\.json is not valid JSON/i),
});
// And no multi-GB install is started on a failed resolve.
expect(trellis2.installTrellis2).not.toHaveBeenCalled();
});
it('short-circuits with complete when already installed (no install spawned)', async () => {
trellis2.installTrellis2.mockClear();
trellis2.isTrellis2Installed.mockReturnValueOnce(true);
const res = await request(makeApp()).post('/api/image-to-3d/trellis2/install');
const frames = sseFrames(res.text);
expect(frames.at(-1)).toMatchObject({ type: 'complete', message: expect.stringMatching(/already/i) });
expect(trellis2.installTrellis2).not.toHaveBeenCalled();
});
it('appends a resume hint when the install fails with a transient network error', async () => {
trellis2.isTrellis2Installed.mockReturnValueOnce(false);
trellis2.installTrellis2.mockImplementationOnce(() => ({
promise: Promise.reject(Object.assign(
new Error("TRELLIS.2 install step 'setup' exited 128"),
{ code: 'TRELLIS2_INSTALL_FAILED', stage: 'setup', transient: true },
)),
kill: vi.fn(),
}));
const res = await request(makeApp()).post('/api/image-to-3d/trellis2/install');
const frames = sseFrames(res.text);
expect(frames.at(-1)).toMatchObject({
type: 'error',
stage: 'setup',
message: expect.stringMatching(/exited 128.*network hiccup — click Install again to resume/is),
});
});
it('does NOT append the resume hint for a non-transient failure', async () => {
trellis2.isTrellis2Installed.mockReturnValueOnce(false);
trellis2.installTrellis2.mockImplementationOnce(() => ({
promise: Promise.reject(Object.assign(
new Error('TRELLIS.2 install step \'setup\' exited 1'),
{ code: 'TRELLIS2_INSTALL_FAILED', stage: 'setup', transient: false },
)),
kill: vi.fn(),
}));
const res = await request(makeApp()).post('/api/image-to-3d/trellis2/install');
const frames = sseFrames(res.text);
expect(frames.at(-1)).toMatchObject({ type: 'error', message: expect.stringMatching(/exited 1$/) });
expect(frames.at(-1).message).not.toMatch(/network hiccup/i);
});
it('refuses on unsupported hardware', async () => {
trellis2.installTrellis2.mockClear();
trellis2.isTrellis2Installed.mockReturnValueOnce(false);
targets.unavailableReason.mockReturnValueOnce('requires-apple-silicon');
const res = await request(makeApp()).post('/api/image-to-3d/trellis2/install');
const frames = sseFrames(res.text);
// The human label, not the raw kebab-case reason code (#3579).
expect(frames.at(-1)).toMatchObject({ type: 'error', message: expect.stringMatching(/Requires an Apple Silicon Mac/) });
expect(frames.at(-1).message).not.toMatch(/requires-apple-silicon/);
expect(trellis2.installTrellis2).not.toHaveBeenCalled();
});
});
describe('image-to-3d model records', () => {
beforeEach(() => vi.clearAllMocks());
it('GET /models lists records', async () => {
models.listModels.mockResolvedValue([{ id: 'image3d-1', status: 'ready' }]);
const res = await request(makeApp()).get('/api/image-to-3d/models');
expect(res.status).toBe(200);
expect(res.body).toEqual([{ id: 'image3d-1', status: 'ready' }]);
});
it('POST /models creates a record (202) from a validated gallery image', async () => {
models.createModel.mockResolvedValue({ id: 'image3d-1', status: 'generating' });
const res = await request(makeApp())
.post('/api/image-to-3d/models')
.send({ name: 'Beacon', filename: 'shot.png' });
expect(res.status).toBe(202);
expect(res.body).toMatchObject({ id: 'image3d-1', status: 'generating' });
expect(models.createModel).toHaveBeenCalledWith(expect.objectContaining({ name: 'Beacon', filename: 'shot.png' }));
});
it('POST /models 400s on a non-image filename', async () => {
const res = await request(makeApp())
.post('/api/image-to-3d/models')
.send({ name: 'Beacon', filename: 'not-an-image.txt' });
expect(res.status).toBe(400);
expect(models.createModel).not.toHaveBeenCalled();
});
it('POST /models 400s on a path-traversal filename', async () => {
const res = await request(makeApp())
.post('/api/image-to-3d/models')
.send({ name: 'Beacon', filename: '../secrets.png' });
expect(res.status).toBe(400);
expect(models.createModel).not.toHaveBeenCalled();
});
it('GET /models/:id 404s when absent', async () => {
models.getModel.mockResolvedValue(null);
const res = await request(makeApp()).get('/api/image-to-3d/models/nope');
expect(res.status).toBe(404);
});
it('POST /models/:id/generate re-renders (202)', async () => {
models.startGeneration.mockResolvedValue({ id: 'image3d-1', status: 'generating' });
const res = await request(makeApp()).post('/api/image-to-3d/models/image3d-1/generate');
expect(res.status).toBe(202);
// A bodiless re-render forwards empty options — stored renderOptions apply.
expect(models.startGeneration).toHaveBeenCalledWith('image3d-1', { options: {} });
});
it('POST /models/:id/generate forwards per-run options and rejects invalid ones', async () => {
models.startGeneration.mockResolvedValue({ id: 'image3d-1', status: 'generating' });
const res = await request(makeApp())
.post('/api/image-to-3d/models/image3d-1/generate')
.send({ steps: 24, seed: 7, keyBackground: false });
expect(res.status).toBe(202);
expect(models.startGeneration).toHaveBeenCalledWith(
'image3d-1',
{ options: { steps: 24, seed: 7, keyBackground: false } },
);
const bad = await request(makeApp())
.post('/api/image-to-3d/models/image3d-1/generate')
.send({ steps: 999 });
expect(bad.status).toBe(400);
});
it('POST /models/:id/generate takes a subject scale in (0, 1] and 400s outside it', async () => {
models.startGeneration.mockResolvedValue({ id: 'image3d-1', status: 'generating' });
const ok = await request(makeApp())
.post('/api/image-to-3d/models/image3d-1/generate')
.send({ subjectScale: 0.65 });
expect(ok.status).toBe(202);
expect(models.startGeneration).toHaveBeenCalledWith('image3d-1', { options: { subjectScale: 0.65 } });
// 0 scales the subject out of existence; above 1 crops it — which is the exact
// failure the knob exists to prevent, so it must not be reachable by accident.
for (const subjectScale of [0, -0.5, 1.5]) {
// eslint-disable-next-line no-await-in-loop
const bad = await request(makeApp())
.post('/api/image-to-3d/models/image3d-1/generate')
.send({ subjectScale });
expect(bad.status, `subjectScale ${subjectScale}`).toBe(400);
}
});
it('DELETE /models/:id soft-deletes', async () => {
models.deleteModel.mockResolvedValue({ ok: true });
const res = await request(makeApp()).delete('/api/image-to-3d/models/image3d-1');
expect(res.status).toBe(200);
expect(res.body).toEqual({ ok: true });
});
it('GET /models/:id/asset streams the GLB with a download filename', async () => {
const tmp = join(tmpdir(), `it-asset-${process.pid}.glb`);
await writeFile(tmp, 'GLB-BYTES');
models.getModelAsset.mockResolvedValue({ path: tmp, filename: 'beacon.glb' });
const res = await request(makeApp()).get('/api/image-to-3d/models/image3d-1/asset');
expect(res.status).toBe(200);
expect(res.headers['content-type']).toMatch(/model\/gltf-binary/);
expect(res.headers['content-disposition']).toMatch(/beacon\.glb/);
expect(res.text).toBe('GLB-BYTES');
await rm(tmp, { force: true });
});
it('GET /models/:id/asset 409s when the mesh is not ready', async () => {
const { ServerError } = await import('../lib/errorHandler.js');
models.getModelAsset.mockRejectedValue(new ServerError('not ready', { status: 409, code: 'MODEL_NOT_READY' }));
const res = await request(makeApp()).get('/api/image-to-3d/models/image3d-1/asset');
expect(res.status).toBe(409);
});
it('GET /models/:id/full-mesh streams the pre-decimation OBJ', async () => {
const tmp = join(tmpdir(), `it-full-${process.pid}.obj`);
await writeFile(tmp, 'v 0 0 0\nf 1 1 1\n');
models.getModelFullMesh.mockResolvedValue({ path: tmp, filename: 'beacon-full.obj' });
const res = await request(makeApp()).get('/api/image-to-3d/models/image3d-1/full-mesh');
expect(res.status).toBe(200);
expect(res.headers['content-type']).toMatch(/model\/obj/);
expect(res.headers['content-disposition']).toMatch(/beacon-full\.obj/);
await rm(tmp, { force: true });
});
it('GET /models/:id/full-mesh 404s when the sidecar was never written', async () => {
// A missing OBJ is NOT a broken record — older renders simply have none, so it
// must not read as the model being unavailable.
const { ServerError } = await import('../lib/errorHandler.js');
models.getModelFullMesh.mockRejectedValue(
new ServerError('no full mesh', { status: 404, code: 'FULL_MESH_MISSING' }),
);
const res = await request(makeApp()).get('/api/image-to-3d/models/image3d-1/full-mesh');
expect(res.status).toBe(404);
expect(res.body?.error?.code || res.body?.code).toBe('FULL_MESH_MISSING');
});
// ── AR Quick Look (USDZ) ────────────────────────────────────────────────
// The bytes are produced in the browser, so the route's whole job is to accept a
// raw body past the app-wide JSON parser, persist it, and re-serve it with the
// exact content type + disposition AR Quick Look requires.
// A minimal stored-zip header — USDZ is an uncompressed zip, and the service
// gates on that magic rather than trusting the request's content type.
const ZIP_BYTES = Buffer.from([0x50, 0x4b, 0x03, 0x04, 0x00, 0x00]);
it('POST /models/:id/usdz accepts a raw USDZ body past the JSON parser', async () => {
models.saveModelUsdz.mockResolvedValue({
id: 'image3d-1', status: 'ready', usdzPath: '/data/image-to-3d/image3d-1/model.usdz',
});
const res = await request(makeApp())
.post('/api/image-to-3d/models/image3d-1/usdz')
.set('Content-Type', 'model/vnd.usdz+zip')
.send(ZIP_BYTES);
expect(res.status).toBe(201);
expect(res.body.usdzPath).toBe('/data/image-to-3d/image3d-1/model.usdz');
const [id, body] = models.saveModelUsdz.mock.calls.at(-1);
expect(id).toBe('image3d-1');
expect(Buffer.from(body).equals(ZIP_BYTES)).toBe(true);
});
it('POST /models/:id/usdz surfaces the service refusal for a non-USDZ payload', async () => {
const { ServerError } = await import('../lib/errorHandler.js');
models.saveModelUsdz.mockRejectedValue(
new ServerError('Payload is not a USDZ archive', { status: 400, code: 'USDZ_INVALID' }),
);
const res = await request(makeApp())
.post('/api/image-to-3d/models/image3d-1/usdz')
.set('Content-Type', 'application/octet-stream')
.send(Buffer.from('not a zip'));
expect(res.status).toBe(400);
expect(res.body?.error?.code || res.body?.code).toBe('USDZ_INVALID');
});
it('GET /models/:id/usdz serves inline with the AR Quick Look content type', async () => {
// `inline`, not `attachment`: Safari will not engage AR Quick Look on an
// attachment response, so this header pair IS the feature.
const tmp = join(tmpdir(), `it-usdz-${process.pid}.usdz`);
await writeFile(tmp, ZIP_BYTES);
models.getModelUsdz.mockResolvedValue({ path: tmp, filename: 'beacon.usdz' });
const res = await request(makeApp()).get('/api/image-to-3d/models/image3d-1/usdz');
expect(res.status).toBe(200);
expect(res.headers['content-type']).toMatch(/model\/vnd\.usdz\+zip/);
expect(res.headers['content-disposition']).toMatch(/^inline; filename="beacon\.usdz"$/);
await rm(tmp, { force: true });
});
it('GET /models/:id/usdz 404s when the model was never exported for AR', async () => {
const { ServerError } = await import('../lib/errorHandler.js');
models.getModelUsdz.mockRejectedValue(
new ServerError('not exported', { status: 404, code: 'USDZ_MISSING' }),
);
const res = await request(makeApp()).get('/api/image-to-3d/models/image3d-1/usdz');
expect(res.status).toBe(404);
expect(res.body?.error?.code || res.body?.code).toBe('USDZ_MISSING');
});
it('routes /full-mesh to its own handler with the record id', async () => {
// Deliberately NOT claiming this proves route ordering: Express's `:id` matches a
// single path segment, so `/models/x/full-mesh` can never match `/models/:id`
// regardless of registration order. What it does pin is that the id is parsed
// from the right segment and reaches the handler.
models.getModelFullMesh.mockRejectedValue(new Error('boom'));
await request(makeApp()).get('/api/image-to-3d/models/image3d-1/full-mesh');
expect(models.getModelFullMesh).toHaveBeenCalledWith('image3d-1');
});
});