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';
const state = vi.hoisted(() => ({
game: null,
records: {},
atlases: {},
assets: {},
manifest: null,
// On-disk bytes, keyed by the suffix `sha256File` is asked for. Tests mutate
// this to simulate a file whose bytes changed under a recorded hash, or that
// vanished (`null`) — without it the mock always echoes the hash the fixture
// pointer declares, so the mismatch comparison can never be false and a
// regression that inverted it would ship green.
hashes: {},
// Distinct from `hashes[path] === null` (missing): an unreadable file, which
// must produce the same verdict but a different diagnosis.
unreadable: new Set(),
}));
vi.mock('./records.js', () => ({
getGame: vi.fn(async () => state.game),
}));
vi.mock('./store.js', () => ({
gameRecordDir: (id) => `/tmp/games/${id}`,
}));
vi.mock('../apps.js', () => ({
getAppById: vi.fn(async () => ({ id: 'app-1', name: 'Example App' })),
}));
vi.mock('../sprites/records.js', () => ({
getRecord: vi.fn(async (id) => state.records[id] || null),
}));
vi.mock('../sprites/atlas.js', () => ({
getAtlasState: vi.fn(async (id) => ({
current: state.atlases[id] || null,
publications: [],
})),
}));
vi.mock('../sprites/paths.js', () => ({
listRuntimeAtlasAssets: vi.fn(async (id) => state.assets[id] || []),
safeResolveSpriteAssetPath: vi.fn((id, path) => `/tmp/sprites/${id}/${path}`),
}));
vi.mock('../sprites/recordsLogic.js', () => ({
isValidSpriteId: vi.fn((id) => !String(id).includes('/')),
}));
vi.mock('../tracks/index.js', () => ({
getTrack: vi.fn(async (id) => ({
id,
title: 'Example Theme',
audioFilename: 'example-theme.ogg',
})),
}));
vi.mock('../pipeline/musicLibrary.js', () => ({
statMusicTrack: vi.fn(async () => ({ sizeBytes: 128 })),
isSafeMusicFilename: vi.fn((name) => /\.(?:mp3|wav|m4a|ogg|flac)$/i.test(String(name || ''))),
}));
vi.mock('../../lib/fileUtils.js', () => ({
PATHS: { images: '/tmp/images', music: '/tmp/music' },
readJSONFile: vi.fn(async () => state.manifest),
// Content-exact, not length-based — a canonical-stringify change that happened
// to preserve length must still register as a changed input.
sha256Text: vi.fn((value) => `text-sha:${String(value)}`),
// Mirrors the real `sha256File`: REJECTS on a file it can't read (the caller
// owns the catch), so a test can drive the missing/unreadable branches.
sha256File: vi.fn(async (path) => {
const key = Object.keys(state.hashes).find((suffix) => path.endsWith(suffix));
if (state.unreadable.has(key)) {
throw Object.assign(new Error(`EACCES: permission denied, open '${path}'`), { code: 'EACCES' });
}
const hash = key ? state.hashes[key] : null;
if (hash === null || hash === undefined) {
throw Object.assign(new Error(`ENOENT: no such file, open '${path}'`), { code: 'ENOENT' });
}
return hash;
}),
}));
import { getGameIntegrity, resolveGameAssets } from './integrity.js';
const baseGame = () => ({
id: 'game-1',
appId: 'app-1',
name: 'Example Game',
spriteBindings: [
{ spriteId: 'native' },
{ spriteId: 'props' },
{ spriteId: 'draft-character' },
],
musicBindings: [{ id: 'music-1', trackId: 'theme' }],
artworkBindings: [],
compiledManifest: null,
});
describe('Game bundle integrity', () => {
beforeEach(() => {
state.game = baseGame();
state.records = {
native: { id: 'native', name: 'Native Hero', kind: 'character' },
props: { id: 'props', name: 'Imported Props', kind: 'props' },
'draft-character': { id: 'draft-character', name: 'Draft Character', kind: 'character' },
};
state.atlases = {
native: {
version: 4,
atlasPath: 'runtime/v4/native.png',
atlasSha256: 'native-atlas-sha',
manifestPath: 'runtime/v4/native.json',
manifestSha256: 'native-manifest-sha',
geometry: { cellSize: 96 },
},
};
state.assets = {
props: [{ path: 'atlas/props.png', size: 512 }],
};
// Every file present and matching what its pointer records.
state.hashes = {
'native.png': 'native-atlas-sha',
'native.json': 'native-manifest-sha',
'props.png': 'props-sha',
'example-theme.ogg': 'music-sha',
'game-assets-v3.json': 'bundle-sha',
};
state.unreadable = new Set();
state.manifest = null;
});
it('accepts native and imported runtime assets while preserving draft blockers', async () => {
const resolved = await resolveGameAssets(state.game);
expect(resolved.sprites.map((sprite) => [sprite.spriteId, sprite.sourceType])).toEqual([
['native', 'runtime-atlas'],
['props', 'imported-assets'],
]);
expect(resolved.music).toHaveLength(1);
expect(resolved.issues).toEqual([
expect.objectContaining({
assetId: 'draft-character',
code: 'SPRITE_ATLAS_REQUIRED',
}),
]);
expect(resolved.summaries.sprites).toEqual(expect.arrayContaining([
expect.objectContaining({ assetId: 'props', status: 'ready', fileCount: 1 }),
expect.objectContaining({ assetId: 'draft-character', status: 'blocked' }),
]));
});
it('hashes gallery artwork and reports whether publishing is current', async () => {
state.game.spriteBindings = [];
state.game.musicBindings = [];
state.game.artworkBindings = [{
id: 'artwork-1',
imageFilename: 'title.png',
label: 'Title Key Art',
role: 'title-key-art',
destinationPath: 'game/assets/art/title.png',
publication: null,
}];
state.hashes['title.png'] = 'title-sha';
const pending = await resolveGameAssets(state.game);
expect(pending.artwork).toEqual([
expect.objectContaining({
bindingId: 'artwork-1',
sourceSha256: 'title-sha',
destinationPath: 'game/assets/art/title.png',
}),
]);
expect(pending.summaries.artwork[0]).toMatchObject({
status: 'ready',
publicationStatus: 'pending',
fileCount: 1,
});
state.game.artworkBindings[0].publication = {
sourceSha256: 'title-sha',
destinationSha256: 'title-sha',
destinationPath: 'game/assets/art/title.png',
publishedAt: '2026-01-01T00:00:00.000Z',
};
const current = await resolveGameAssets(state.game);
expect(current.summaries.artwork[0].publicationStatus).toBe('current');
expect(current.verifiedFileCount).toBe(1);
});
it('reports music publish state without disturbing destination-less bindings', async () => {
state.game.spriteBindings = [];
// A binding with no destination (pre-publish record, or an older peer)
// keeps the exact manifest-item shape it always hashed — an upgrade alone
// must not flip an existing bundle to "stale".
const legacy = await resolveGameAssets(state.game);
expect(legacy.music[0]).not.toHaveProperty('destinationPath');
expect(legacy.music[0]).not.toHaveProperty('publishedSha256');
expect(legacy.summaries.music[0]).toMatchObject({ status: 'ready', message: 'Audio ready' });
expect(legacy.summaries.music[0].publicationStatus).toBeUndefined();
state.game.musicBindings = [{
id: 'music-1',
trackId: 'theme',
destinationPath: 'game/assets/music/example-theme.ogg',
publication: null,
}];
const pending = await resolveGameAssets(state.game);
expect(pending.music[0]).toMatchObject({
destinationPath: 'game/assets/music/example-theme.ogg',
publishedSha256: null,
});
expect(pending.summaries.music[0]).toMatchObject({
publicationStatus: 'pending',
message: 'Audio verified · publish pending',
});
state.game.musicBindings[0].publication = {
sourceSha256: 'music-sha',
destinationSha256: 'music-sha',
destinationPath: 'game/assets/music/example-theme.ogg',
publishedAt: '2026-01-01T00:00:00.000Z',
};
const current = await resolveGameAssets(state.game);
expect(current.music[0].publishedSha256).toBe('music-sha');
expect(current.summaries.music[0].publicationStatus).toBe('current');
});
it('blocks missing gallery artwork without failing the whole preflight', async () => {
state.game.spriteBindings = [];
state.game.musicBindings = [];
state.game.artworkBindings = [{
id: 'artwork-missing',
imageFilename: 'missing.png',
label: 'Missing Art',
role: 'loading-screen',
destinationPath: 'game/assets/art/loading.png',
publication: null,
}];
const resolved = await resolveGameAssets(state.game);
expect(resolved.artwork).toEqual([]);
expect(resolved.issues[0]).toMatchObject({
assetType: 'artwork',
code: 'ARTWORK_MISSING',
});
});
it('reports a corrupt binding id as a blocked asset instead of throwing', async () => {
// The atlas pointer read is issued in parallel with the record read, so a
// binding whose id is not a valid slug must be gated — `spriteDir` throws a
// 400 on one, which would fail the whole preflight instead of naming the
// one bad binding.
state.game.spriteBindings = [{ spriteId: '../escape' }];
const resolved = await resolveGameAssets(state.game);
expect(resolved.sprites).toEqual([]);
expect(resolved.issues).toEqual([
expect.objectContaining({ assetId: '../escape', code: 'SPRITE_MISSING' }),
]);
expect(resolved.summaries.sprites[0]).toMatchObject({ status: 'blocked' });
});
it('marks a complete hash-matching manifest current and launchable', async () => {
state.game.spriteBindings = state.game.spriteBindings.filter(
(binding) => binding.spriteId !== 'draft-character',
);
const resolved = await resolveGameAssets(state.game);
state.game.compiledManifest = {
version: 3,
manifestPath: 'manifests/game-assets-v3.json',
manifestSha256: 'bundle-sha',
inputSha256: resolved.inputSha256,
};
state.manifest = {
kind: 'portos-game-assets',
game: { id: 'game-1' },
version: 3,
};
const integrity = await getGameIntegrity('game-1');
expect(integrity.bundle.status).toBe('current');
expect(integrity.readyToCompile).toBe(true);
expect(integrity.canLaunch).toBe(true);
expect(integrity.counts).toMatchObject({
spriteReady: 2,
spriteTotal: 2,
musicReady: 1,
musicTotal: 1,
verifiedFiles: 4,
});
});
// A "verified" bundle is only worth the hash comparisons behind it. These
// drive the branches that decide missing / unreadable / changed bytes — the
// detection the whole feature exists for.
describe('hash verification', () => {
const buildableGame = () => {
state.game.spriteBindings = [{ spriteId: 'native' }];
state.game.musicBindings = [];
};
it('blocks a sprite whose atlas bytes changed under its recorded hash', async () => {
buildableGame();
state.hashes['native.png'] = 'someone-recompressed-the-png';
const resolved = await resolveGameAssets(state.game);
expect(resolved.sprites).toEqual([]);
expect(resolved.issues).toEqual([
expect.objectContaining({
assetId: 'native',
code: 'SPRITE_ATLAS_INTEGRITY_FAILED',
}),
]);
});
it('blocks a sprite whose atlas file is gone', async () => {
buildableGame();
state.hashes['native.png'] = null;
const resolved = await resolveGameAssets(state.game);
expect(resolved.issues[0]).toMatchObject({ code: 'SPRITE_ATLAS_INTEGRITY_FAILED' });
});
it('blocks a sprite whose atlas file is present but unreadable', async () => {
// Same verdict as missing (no verifiable bytes), but the cause is a
// permissions failure on intact bytes — `hashIfPresent` must not let the
// EACCES escape and fail the whole read-only sweep.
buildableGame();
state.unreadable.add('native.png');
const resolved = await resolveGameAssets(state.game);
expect(resolved.issues[0]).toMatchObject({ code: 'SPRITE_ATLAS_INTEGRITY_FAILED' });
});
it('blocks an imported runtime asset that is unreadable', async () => {
state.game.spriteBindings = [{ spriteId: 'props' }];
state.game.musicBindings = [];
state.unreadable.add('props.png');
const resolved = await resolveGameAssets(state.game);
expect(resolved.sprites).toEqual([]);
expect(resolved.issues[0]).toMatchObject({
assetId: 'props',
code: 'SPRITE_ATLAS_INTEGRITY_FAILED',
});
});
it('distinguishes missing, malformed, and missing-file track audio', async () => {
// `sanitizeTrack` only trims the top-level audioFilename, so a legacy or
// peer-synced track can carry one `statMusicTrack` would THROW a 400 on.
// It has to become one blocked row, not a failed preflight.
state.game.spriteBindings = [];
const { getTrack } = await import('../tracks/index.js');
const { statMusicTrack } = await import('../pipeline/musicLibrary.js');
getTrack.mockResolvedValueOnce({ id: 'theme', title: 'No Audio' });
const missingName = await resolveGameAssets(state.game);
expect(missingName.issues).toEqual([
expect.objectContaining({
code: 'TRACK_AUDIO_REQUIRED',
message: expect.stringContaining('Render or upload audio'),
}),
]);
getTrack.mockResolvedValueOnce({
id: 'theme',
title: 'Legacy Theme',
audioFilename: 'theme.opus',
});
const malformedName = await resolveGameAssets(state.game);
expect(malformedName.issues).toEqual([
expect.objectContaining({
code: 'TRACK_AUDIO_INTEGRITY_FAILED',
message: 'The rendered audio path for "Legacy Theme" is invalid',
}),
]);
getTrack.mockResolvedValueOnce({
id: 'theme',
title: 'Missing Theme',
audioFilename: 'missing-theme.ogg',
});
statMusicTrack.mockResolvedValueOnce(null);
const missingFile = await resolveGameAssets(state.game);
expect(missingFile.issues).toEqual([
expect.objectContaining({
code: 'TRACK_AUDIO_MISSING',
message: 'The rendered audio for "Missing Theme" is missing or unreadable',
}),
]);
});
});
describe('bundle status', () => {
const withBuiltBundle = async (overrides = {}) => {
state.game.spriteBindings = [{ spriteId: 'native' }];
state.game.musicBindings = [];
const resolved = await resolveGameAssets(state.game);
state.game.compiledManifest = {
version: 3,
manifestPath: 'manifests/game-assets-v3.json',
manifestSha256: 'bundle-sha',
inputSha256: resolved.inputSha256,
...overrides,
};
state.manifest = { kind: 'portos-game-assets', game: { id: 'game-1' }, version: 3 };
return resolved;
};
it('goes stale when a bound asset changes after the build', async () => {
await withBuiltBundle();
// Re-point the sprite at a new atlas version: same files, different
// recorded hashes, so the resolved input no longer matches the pointer.
state.atlases.native = { ...state.atlases.native, version: 5 };
state.hashes['native.png'] = 'v5-atlas-sha';
state.atlases.native.atlasSha256 = 'v5-atlas-sha';
const integrity = await getGameIntegrity('game-1');
expect(integrity.bundle.status).toBe('stale');
expect(integrity.canLaunch).toBe(false);
});
it('goes stale when a bound asset is blocked, without launching', async () => {
await withBuiltBundle();
state.hashes['native.png'] = null;
const integrity = await getGameIntegrity('game-1');
expect(integrity.bundle.status).toBe('stale');
expect(integrity.canLaunch).toBe(false);
});
it('is corrupt when the manifest file no longer matches its recorded hash', async () => {
await withBuiltBundle();
state.hashes['game-assets-v3.json'] = 'edited-by-hand';
const integrity = await getGameIntegrity('game-1');
expect(integrity.bundle.status).toBe('corrupt');
expect(integrity.canLaunch).toBe(false);
});
it('is corrupt when the manifest file is gone', async () => {
await withBuiltBundle();
state.hashes['game-assets-v3.json'] = null;
const integrity = await getGameIntegrity('game-1');
expect(integrity.bundle.status).toBe('corrupt');
});
it('is corrupt when the manifest describes a different game or version', async () => {
await withBuiltBundle();
state.manifest = { kind: 'portos-game-assets', game: { id: 'other-game' }, version: 3 };
expect((await getGameIntegrity('game-1')).bundle.status).toBe('corrupt');
state.manifest = { kind: 'portos-game-assets', game: { id: 'game-1' }, version: 9 };
expect((await getGameIntegrity('game-1')).bundle.status).toBe('corrupt');
state.manifest = { kind: 'something-else', game: { id: 'game-1' }, version: 3 };
expect((await getGameIntegrity('game-1')).bundle.status).toBe('corrupt');
});
it('is corrupt when the pointer records no manifest path at all', async () => {
await withBuiltBundle({ manifestPath: '' });
expect((await getGameIntegrity('game-1')).bundle.status).toBe('corrupt');
});
it('keeps a byte-perfect bundle current when only the managed app is missing', async () => {
// The app blocker is not asset drift. Reporting `stale` here would tell
// the user "Bound assets changed after this bundle was built" — false —
// and pair a "Needs rebuild" badge with a disabled Rebuild button.
await withBuiltBundle();
const { getAppById } = await import('../apps.js');
getAppById.mockResolvedValueOnce(null);
const integrity = await getGameIntegrity('game-1');
expect(integrity.bundle.status).toBe('current');
expect(integrity.issues).toEqual([
expect.objectContaining({ code: 'APP_MISSING', assetType: 'app' }),
]);
expect(integrity.readyToCompile).toBe(false);
expect(integrity.canLaunch).toBe(false);
});
});
});