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

15.7 KB
Raw Blame
/**
 * Game bundle preflight and integrity verification.
 *
 * Resolves every bound asset to immutable, hash-pinned bytes. Native sprite
 * records use their current runtime-atlas pointer; imported prop/object
 * records use the runtime files already imported under atlas/. Character
 * references without a compiled atlas remain explicit blockers rather than
 * disappearing from a supposedly complete bundle.
 */

import { join } from 'path';
import {
  PATHS,
  readJSONFile,
  sha256File,
  sha256Text,
} from '../../lib/fileUtils.js';
import { canonicalStringify } from '../../lib/objects.js';
import { getAppById } from '../apps.js';
import { isSafeMusicFilename, statMusicTrack } from '../pipeline/musicLibrary.js';
import { getAtlasState } from '../sprites/atlas.js';
import {
  listRuntimeAtlasAssets,
  safeResolveSpriteAssetPath,
} from '../sprites/paths.js';
import { getRecord as getSpriteRecord } from '../sprites/records.js';
import { isValidSpriteId } from '../sprites/recordsLogic.js';
import { getTrack } from '../tracks/index.js';
import { getGame } from './records.js';
import { gameRecordDir } from './store.js';

export const BUNDLE_SCHEMA_VERSION = 3;

const issue = (assetType, assetId, name, code, message) => ({
  assetType,
  assetId,
  name,
  code,
  message,
});

/**
 * A resolver's failure result. Every blocked asset carries both an `issue` for
 * the blocker list and a matching `summary` row for the per-asset UI, built
 * from the same values here so the two can't drift — `shortMessage` is the
 * badge text when the full blocker sentence is too long for a row.
 */
const blocked = (assetType, identity, code, message, shortMessage = message) => ({
  problem: issue(assetType, identity.assetId, identity.name, code, message),
  summary: { ...identity, status: 'blocked', message: shortMessage },
});

// A null hash means "no verifiable bytes" — absent, or present but unreadable.
// The verdict is the same either way (it can never match a recorded hash), but
// the CAUSE is not: a permissions/descriptor failure on intact bytes reads to
// the user as corruption and sends them to recompile a perfectly good atlas.
// ENOENT is the expected case and stays quiet; anything else leaves a
// breadcrumb naming the real errno.
const hashIfPresent = (path) => sha256File(path).catch((err) => {
  if (err?.code !== 'ENOENT') {
    console.error(`❌ Unreadable game asset ${path}: ${err?.code || ''} ${err?.message || err}`);
  }
  return null;
});

async function resolveRuntimeAtlas(record, current) {
  const identity = { assetId: record.id, name: record.name, kind: record.kind };
  const required = [
    current?.atlasPath,
    current?.atlasSha256,
    current?.manifestPath,
    current?.manifestSha256,
  ];
  if (required.some((value) => typeof value !== 'string' || !value)) return null;

  const paths = [
    safeResolveSpriteAssetPath(record.id, current.atlasPath),
    safeResolveSpriteAssetPath(record.id, current.manifestPath),
  ];
  if (paths.some((path) => !path)) {
    return blocked(
      'sprite',
      identity,
      'SPRITE_ATLAS_INTEGRITY_FAILED',
      `The runtime atlas paths for "${record.name}" are invalid`,
      'Runtime atlas path invalid',
    );
  }

  const [atlasSha256, manifestSha256] = await Promise.all(paths.map(hashIfPresent));
  if (atlasSha256 !== current.atlasSha256 || manifestSha256 !== current.manifestSha256) {
    return blocked(
      'sprite',
      identity,
      'SPRITE_ATLAS_INTEGRITY_FAILED',
      `The runtime atlas for "${record.name}" is missing, unreadable, or does not match its recorded hash`,
      'Runtime atlas integrity failed',
    );
  }

  return {
    item: {
      spriteId: record.id,
      name: record.name,
      kind: record.kind,
      sourceType: 'runtime-atlas',
      atlasVersion: current.version,
      atlasPath: `sprites/${record.id}/${current.atlasPath}`,
      atlasSha256,
      manifestPath: `sprites/${record.id}/${current.manifestPath}`,
      manifestSha256,
      geometry: current.geometry,
    },
    summary: {
      ...identity,
      status: 'ready',
      sourceType: 'runtime-atlas',
      // The atlas sheet plus its manifest — the two files hashed above.
      fileCount: paths.length,
      message: `Runtime atlas v${current.version}`,
    },
  };
}

async function resolveImportedAssets(record) {
  const identity = { assetId: record.id, name: record.name, kind: record.kind };
  const runtimeAssets = await listRuntimeAtlasAssets(record.id);
  if (runtimeAssets.length === 0) return null;

  const assets = await Promise.all(runtimeAssets.map(async (asset) => ({
    path: `sprites/${record.id}/${asset.path}`,
    sha256: await hashIfPresent(safeResolveSpriteAssetPath(record.id, asset.path)),
    sizeBytes: asset.size,
  })));
  if (assets.some((asset) => !asset.sha256)) {
    return blocked(
      'sprite',
      identity,
      'SPRITE_ATLAS_INTEGRITY_FAILED',
      `An imported runtime asset for "${record.name}" is missing or unreadable`,
      'Imported asset integrity failed',
    );
  }

  return {
    item: {
      spriteId: record.id,
      name: record.name,
      kind: record.kind,
      sourceType: 'imported-assets',
      assets,
    },
    summary: {
      ...identity,
      status: 'ready',
      sourceType: 'imported-assets',
      fileCount: assets.length,
      message: `${assets.length} imported runtime ${assets.length === 1 ? 'file' : 'files'}`,
    },
  };
}

async function resolveSprite(binding) {
  // The atlas pointer is keyed on the same id as the record, so both reads can
  // start together — a missing record wastes one cheap pointer read rather than
  // serializing two round trips for every bound sprite on every preflight. The
  // id guard keeps a corrupt binding a SPRITE_MISSING row instead of a 400 out
  // of `spriteDir`.
  const [record, atlas] = await Promise.all([
    getSpriteRecord(binding.spriteId),
    isValidSpriteId(binding.spriteId) ? getAtlasState(binding.spriteId) : { current: null },
  ]);
  if (!record) {
    return blocked(
      'sprite',
      { assetId: binding.spriteId, name: binding.spriteId },
      'SPRITE_MISSING',
      `Bound sprite no longer exists: ${binding.spriteId}`,
    );
  }
  const identity = { assetId: record.id, name: record.name, kind: record.kind };

  const runtime = await resolveRuntimeAtlas(record, atlas.current);
  if (runtime) return runtime;

  const imported = await resolveImportedAssets(record);
  if (imported) return imported;

  return blocked(
    'sprite',
    identity,
    'SPRITE_ATLAS_REQUIRED',
    `Compile or import a runtime atlas for "${record.name}" before building the game bundle`,
    'Runtime atlas required',
  );
}

async function resolveMusic(binding) {
  const track = await getTrack(binding.trackId);
  if (!track) {
    return blocked(
      'music',
      { assetId: binding.trackId, bindingId: binding.id, name: binding.trackId },
      'TRACK_MISSING',
      `Bound music track no longer exists: ${binding.trackId}`,
    );
  }
  const identity = { assetId: track.id, bindingId: binding.id, name: track.title };

  // `statMusicTrack` THROWS a 400 on an unsupported filename, and `sanitizeTrack`
  // only trims the top-level `audioFilename` — so a legacy or peer-synced track
  // can reach here with one. Screen it first, or one bad track fails the whole
  // read-only preflight instead of naming itself (same reason the sprite path
  // guards on `isValidSpriteId`).
  if (!track.audioFilename) {
    return blocked(
      'music',
      identity,
      'TRACK_AUDIO_REQUIRED',
      `Render or upload audio for "${track.title}" before building the game bundle`,
      'Audio render required',
    );
  }

  if (!isSafeMusicFilename(track.audioFilename)) {
    return blocked(
      'music',
      identity,
      'TRACK_AUDIO_INTEGRITY_FAILED',
      `The rendered audio path for "${track.title}" is invalid`,
      'Audio path invalid',
    );
  }

  if (!(await statMusicTrack(track.audioFilename))) {
    return blocked(
      'music',
      identity,
      'TRACK_AUDIO_MISSING',
      `The rendered audio for "${track.title}" is missing or unreadable`,
      'Audio integrity failed',
    );
  }

  const audioSha256 = await hashIfPresent(join(PATHS.music, track.audioFilename));
  if (!audioSha256) {
    return blocked(
      'music',
      identity,
      'TRACK_AUDIO_INTEGRITY_FAILED',
      `The rendered audio for "${track.title}" is missing or unreadable`,
      'Audio integrity failed',
    );
  }

  // Publish state mirrors the artwork lane — but only for bindings that HAVE a
  // destination. The conditional spread is load-bearing: destination-less
  // bindings (pre-publish records, older peers) keep the exact item shape they
  // hashed before, so upgrading PortOS alone can't flip an existing bundle to
  // "stale" for music that never opted into publishing.
  const publicationCurrent = Boolean(binding.destinationPath)
    && binding.publication?.sourceSha256 === audioSha256
    && binding.publication?.destinationPath === binding.destinationPath;
  return {
    item: {
      bindingId: binding.id,
      trackId: track.id,
      title: track.title,
      audioPath: `music/${track.audioFilename}`,
      audioSha256,
      ...(binding.destinationPath ? {
        destinationPath: binding.destinationPath,
        publishedSha256: publicationCurrent ? audioSha256 : null,
      } : {}),
    },
    summary: {
      ...identity,
      status: 'ready',
      fileCount: 1,
      ...(binding.destinationPath ? {
        destinationPath: binding.destinationPath,
        publicationStatus: publicationCurrent ? 'current' : 'pending',
        message: publicationCurrent ? 'Audio verified · published' : 'Audio verified · publish pending',
      } : { message: 'Audio ready' }),
    },
  };
}

const safeArtworkFilename = (filename) =>
  typeof filename === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]*\.png$/i.test(filename);

async function resolveArtwork(binding) {
  const identity = {
    assetId: binding.id,
    bindingId: binding.id,
    name: binding.label,
    role: binding.role,
  };
  if (!safeArtworkFilename(binding.imageFilename)) {
    return blocked(
      'artwork',
      identity,
      'ARTWORK_PATH_INVALID',
      `The gallery path for "${binding.label}" is invalid`,
      'Gallery path invalid',
    );
  }
  const sourceSha256 = await hashIfPresent(join(PATHS.images, binding.imageFilename));
  if (!sourceSha256) {
    return blocked(
      'artwork',
      identity,
      'ARTWORK_MISSING',
      `The gallery artwork for "${binding.label}" is missing or unreadable`,
      'Gallery artwork missing',
    );
  }
  const publicationCurrent = binding.publication?.sourceSha256 === sourceSha256
    && binding.publication?.destinationPath === binding.destinationPath;
  return {
    item: {
      bindingId: binding.id,
      label: binding.label,
      role: binding.role,
      imagePath: `images/${binding.imageFilename}`,
      sourceSha256,
      destinationPath: binding.destinationPath,
      publishedSha256: publicationCurrent ? sourceSha256 : null,
    },
    summary: {
      ...identity,
      imageFilename: binding.imageFilename,
      destinationPath: binding.destinationPath,
      status: 'ready',
      fileCount: 1,
      publicationStatus: publicationCurrent ? 'current' : 'pending',
      message: publicationCurrent ? 'Gallery source verified · published' : 'Gallery source verified · publish pending',
    },
  };
}

export async function resolveGameAssets(game) {
  const [spriteResults, musicResults, artworkResults] = await Promise.all([
    Promise.all([...game.spriteBindings]
      .sort((a, b) => a.spriteId.localeCompare(b.spriteId))
      .map(resolveSprite)),
    Promise.all([...game.musicBindings]
      .sort((a, b) => a.trackId.localeCompare(b.trackId) || a.id.localeCompare(b.id))
      .map(resolveMusic)),
    Promise.all([...(game.artworkBindings || [])]
      .sort((a, b) => a.role.localeCompare(b.role) || a.id.localeCompare(b.id))
      .map(resolveArtwork)),
  ]);
  const issues = [...spriteResults, ...musicResults, ...artworkResults]
    .map((result) => result.problem)
    .filter(Boolean);
  const sprites = spriteResults.map((result) => result.item).filter(Boolean);
  const music = musicResults.map((result) => result.item).filter(Boolean);
  const artwork = artworkResults.map((result) => result.item).filter(Boolean);
  const summaries = {
    sprites: spriteResults.map((result) => result.summary),
    music: musicResults.map((result) => result.summary),
    artwork: artworkResults.map((result) => result.summary),
  };
  const inputs = {
    schemaVersion: BUNDLE_SCHEMA_VERSION,
    gameId: game.id,
    appId: game.appId,
    sprites,
    music,
    artwork,
  };
  return {
    schemaVersion: BUNDLE_SCHEMA_VERSION,
    sprites,
    music,
    artwork,
    issues,
    inputSha256: sha256Text(canonicalStringify(inputs)),
    summaries,
    // "How many files does this asset contribute" is answered once, by the
    // resolver that hashed them. The compiled manifest pointer and the
    // preflight both read this, so a new source type can't make the two
    // numbers disagree on screen.
    verifiedFileCount: [...summaries.sprites, ...summaries.music, ...summaries.artwork]
      .reduce((sum, asset) => sum + (asset.fileCount || 0), 0),
  };
}

async function inspectCurrentBundle(game, resolved) {
  const current = game.compiledManifest;
  if (!current) return { status: 'missing', message: 'No bundle has been built yet' };
  const corrupt = {
    status: 'corrupt',
    message: 'The current bundle manifest is missing or failed integrity verification',
  };
  if (!current.manifestPath) return corrupt;
  const path = join(gameRecordDir(game.id), current.manifestPath);
  const [actualSha256, manifest] = await Promise.all([
    hashIfPresent(path),
    readJSONFile(path, null, { logError: false }),
  ]);
  if (!actualSha256
    || actualSha256 !== current.manifestSha256
    || manifest?.kind !== 'portos-game-assets'
    || manifest?.game?.id !== game.id
    || manifest?.version !== current.version) {
    return corrupt;
  }
  if (current.inputSha256 !== resolved.inputSha256 || resolved.issues.length > 0) {
    return {
      status: 'stale',
      message: 'Bound assets changed after this bundle was built',
    };
  }
  return {
    status: 'current',
    message: 'Bundle manifest and every bound asset hash are verified',
  };
}

export async function getGameIntegrity(id) {
  const game = await getGame(id);
  if (!game) return null;
  // The app lookup is independent of the hashing sweep — don't make it wait.
  const [app, resolved] = await Promise.all([
    getAppById(game.appId),
    resolveGameAssets(game),
  ]);
  // Inspect the bundle against the ASSET issues only, BEFORE the app blocker is
  // appended: `inspectCurrentBundle` reads a non-empty issue list as evidence
  // the bound assets drifted, so a missing managed app would otherwise report a
  // byte-perfect bundle as `stale` — "Bound assets changed after this bundle was
  // built" — which is a false statement about the assets, and pairs an amber
  // "Needs rebuild" badge with a disabled Rebuild button.
  const bundle = await inspectCurrentBundle(game, resolved);
  if (!app) {
    resolved.issues.push(issue(
      'app',
      game.appId,
      game.name,
      'APP_MISSING',
      'The bound managed app no longer exists',
    ));
  }
  const readyToCompile = resolved.issues.length === 0 && Boolean(app);
  return {
    schemaVersion: BUNDLE_SCHEMA_VERSION,
    readyToCompile,
    canLaunch: readyToCompile && bundle.status === 'current',
    bundle,
    issues: resolved.issues,
    assets: resolved.summaries,
    counts: {
      spriteReady: resolved.sprites.length,
      spriteTotal: game.spriteBindings.length,
      musicReady: resolved.music.length,
      musicTotal: game.musicBindings.length,
      artworkReady: resolved.artwork.length,
      artworkTotal: (game.artworkBindings || []).length,
      verifiedFiles: resolved.verifiedFileCount,
    },
  };
}