Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

11.0 KB
Raw Blame
import 'dart:convert';
import 'dart:io';
import 'dart:typed_data';
import 'dart:ui' as ui;

import 'package:archive/archive.dart';
import 'package:path/path.dart' as p;

import 'loose_sheet.dart';

/// Why a dropped or chosen pet could not be turned into a PNG sheet. [message]
/// is shown to the user as is.
class PetSourceError implements Exception {
  PetSourceError(this.message);
  final String message;
  @override
  String toString() => 'PetSourceError: $message';
}

/// A sheet ready for the daemon: a PNG on disk and the pet's own name, if the
/// package had one. [cleanup] removes whatever this made in the temp folder
/// (never the user's files); call it once the daemon no longer needs the PNG.
///
/// [loose] marks a sheet the app laid out itself from any PNG or JPEG sprite
/// sheet: its row i holds the sheet's i-th row of frames, whatever the petdex
/// row is called. [defaultRows] is then the app's first guess at which row
/// (by petdex row name) plays each state (`rest`, `working`, `listening`,
/// `sending`, `asking`); null for a petdex sheet, whose rows the daemon maps.
class PetSource {
  const PetSource({
    required this.pngPath,
    this.name,
    required this.cleanup,
    this.loose = false,
    this.defaultRows,
  });
  final String pngPath;
  final String? name;
  final Future<void> Function() cleanup;
  final bool loose;
  final Map<String, String>? defaultRows;
}

const _sheetMessage =
    'The sheet must be 1536 × 1872 (8 × 9 cells of 192 × 208)';
const _maxWebp = 8 * 1024 * 1024;
const _maxZipBytes = 32 * 1024 * 1024;
const _maxZipEntries = 64;
const _maxJson = 64 * 1024;

Future<void> _noCleanup() async {}

/// Turns what the user picked into a PNG sheet. Accepts a petdex package
/// (folder, `pet.json`, or a zip of either), a `.webp`, or a `.png` / `.jpg`
/// sprite sheet: a PNG of the petdex size is used as is, any other is laid
/// out by [looseSheetSource]. Everything
/// from outside the app is untrusted: paths stay inside the package folder, a
/// zip is bounded in entries and size, and a WebP's size is read from its header
/// before any decoding.
Future<PetSource> resolvePetSource(String path) async {
  if (FileSystemEntity.isDirectorySync(path)) {
    return _fromDirectory(path, cleanup: _noCleanup);
  }
  switch (p.extension(path).toLowerCase()) {
    case '.png':
      if (_petdexSized(path)) {
        return PetSource(pngPath: path, cleanup: _noCleanup);
      }
      return looseSheetSource(path, name: p.basenameWithoutExtension(path));
    case '.jpg' || '.jpeg':
      return looseSheetSource(path, name: p.basenameWithoutExtension(path));
    case '.webp':
      return _fromWebp(path, name: p.basenameWithoutExtension(path));
    case '.json':
      return _fromDirectory(p.dirname(path), cleanup: _noCleanup);
    case '.zip':
      return _fromZip(path);
  }
  throw PetSourceError('Choose a pet folder, zip, pet.json, WebP, PNG or JPEG');
}

/// Whether the PNG at [path] has a petdex sheet's size, or a header this can't
/// read (the daemon then says what is wrong with it).
bool _petdexSized(String path) {
  final Uint8List head;
  try {
    final file = File(path).openSync();
    try {
      head = file.readSync(32);
    } finally {
      file.closeSync();
    }
  } on FileSystemException {
    return true;
  }
  final size = imageSize(head);
  return size == null || size == (1536, 1872) || size == (768, 936);
}

Future<PetSource> _fromDirectory(
  String dir, {
  required Future<void> Function() cleanup,
}) async {
  final String root;
  try {
    root = Directory(dir).resolveSymbolicLinksSync();
  } on FileSystemException {
    throw PetSourceError('That folder can’t be read');
  }
  String? name;
  String? sheetRel;
  final json = File(p.join(root, 'pet.json'));
  if (json.existsSync()) {
    final meta = await _readMeta(json);
    name = meta.$1;
    sheetRel = meta.$2;
  }
  if (sheetRel == null) {
    final found = [
      for (final ext in ['webp', 'png'])
        if (File(p.join(root, 'spritesheet.$ext')).existsSync())
          'spritesheet.$ext',
    ];
    if (found.length != 1) {
      throw PetSourceError(
        found.isEmpty
            ? 'No pet found: expected pet.json or a spritesheet.webp / .png'
            : 'The folder holds both spritesheet.webp and spritesheet.png',
      );
    }
    sheetRel = found.single;
  }
  final sheet = _inside(root, sheetRel);
  final ext = p.extension(sheet).toLowerCase();
  if (ext == '.png') {
    return PetSource(pngPath: sheet, name: name, cleanup: cleanup);
  }
  if (ext != '.webp') {
    throw PetSourceError('The sprite sheet must be a WebP or PNG');
  }
  final decoded = await _fromWebp(
    sheet,
    name: name ?? p.basenameWithoutExtension(sheet),
  );
  return PetSource(
    pngPath: decoded.pngPath,
    name: decoded.name,
    cleanup: () async {
      await decoded.cleanup();
      await cleanup();
    },
  );
}

/// (name, spritesheetPath) from a petdex `pet.json`.
Future<(String?, String?)> _readMeta(File json) async {
  if (json.lengthSync() > _maxJson) {
    throw PetSourceError('pet.json is too large');
  }
  final Object? raw;
  try {
    raw = jsonDecode(await json.readAsString());
  } on FormatException {
    throw PetSourceError('pet.json isn’t valid JSON');
  }
  if (raw is! Map) throw PetSourceError('pet.json isn’t valid');
  String? text(Object? v) =>
      v is String && v.trim().isNotEmpty ? v.trim() : null;
  final sheet = raw['spritesheetPath'];
  if (sheet != null && text(sheet) == null) {
    throw PetSourceError('pet.json has no usable spritesheetPath');
  }
  return (text(raw['displayName']) ?? text(raw['id']), text(sheet));
}

/// [relative] resolved under [root]; refuses `..`, absolute paths and links
/// that lead out of [root].
String _inside(String root, String relative) {
  final parts = relative.split(RegExp(r'[\\/]'));
  if (relative.contains('\u0000') ||
      relative.startsWith('/') ||
      relative.startsWith(r'\') ||
      RegExp(r'^[A-Za-z]:').hasMatch(relative) ||
      parts.contains('..')) {
    throw PetSourceError('The sprite sheet path in pet.json isn’t allowed');
  }
  final file = File(p.joinAll([root, ...parts.where((s) => s.isNotEmpty)]));
  final String real;
  try {
    real = file.resolveSymbolicLinksSync();
  } on FileSystemException {
    throw PetSourceError('The sprite sheet “$relative” wasn’t found');
  }
  if (!p.isWithin(root, real) || !File(real).existsSync()) {
    throw PetSourceError('The sprite sheet path in pet.json isn’t allowed');
  }
  return real;
}

Future<PetSource> _fromZip(String path) async {
  final file = File(path);
  if (!file.existsSync()) throw PetSourceError('That file can’t be read');
  if (file.lengthSync() > _maxZipBytes) {
    throw PetSourceError('The zip is too large');
  }
  final Archive archive;
  try {
    archive = ZipDecoder().decodeBytes(await file.readAsBytes());
  } catch (_) {
    throw PetSourceError('That zip can’t be read');
  }
  final files = <(String, ArchiveFile)>[];
  var declared = 0;
  for (final entry in archive) {
    final name = entry.name.replaceAll('\\', '/');
    // Finder adds these; they are not part of the pet.
    if (name.startsWith('__MACOSX/') || name.endsWith('.DS_Store')) continue;
    if (name.contains('\u0000') ||
        name.startsWith('/') ||
        RegExp(r'^[A-Za-z]:').hasMatch(name) ||
        name.split('/').contains('..')) {
      throw PetSourceError('The zip has an entry outside its folder');
    }
    if (entry.isSymbolicLink) {
      throw PetSourceError('The zip holds a link, which isn’t allowed');
    }
    if (!entry.isFile) continue;
    files.add((name, entry));
    declared += entry.size;
    if (files.length > _maxZipEntries) {
      throw PetSourceError('The zip has too many files');
    }
    if (declared > _maxZipBytes) throw PetSourceError('The zip is too large');
  }
  final temp = await Directory.systemTemp.createTemp('harness-pet-');
  Future<void> cleanup() async {
    if (temp.existsSync()) await temp.delete(recursive: true);
  }

  try {
    var written = 0;
    for (final (name, entry) in files) {
      final bytes = entry.content as List<int>;
      written += bytes.length;
      if (written > _maxZipBytes) throw PetSourceError('The zip is too large');
      final target = File(p.joinAll([temp.path, ...name.split('/')]));
      await target.parent.create(recursive: true);
      await target.writeAsBytes(bytes);
    }
    var root = temp.resolveSymbolicLinksSync();
    bool holdsPet(String dir) =>
        File(p.join(dir, 'pet.json')).existsSync() ||
        File(p.join(dir, 'spritesheet.webp')).existsSync() ||
        File(p.join(dir, 'spritesheet.png')).existsSync();
    if (!holdsPet(root)) {
      final children = Directory(root).listSync();
      if (children.length == 1 && children.single is Directory) {
        root = children.single.path;
      }
    }
    return await _fromDirectory(root, cleanup: cleanup);
  } catch (_) {
    await cleanup();
    rethrow;
  }
}

/// (width, height) from a WebP's header, without decoding; null when [b] isn't
/// a WebP this can read.
(int, int)? webpSize(Uint8List b) {
  String tag(int at) =>
      at + 4 <= b.length ? String.fromCharCodes(b.sublist(at, at + 4)) : '';
  if (b.length < 30 || tag(0) != 'RIFF' || tag(8) != 'WEBP') return null;
  int le(int at, int n) {
    var v = 0;
    for (var i = n - 1; i >= 0; i--) {
      v = (v << 8) | b[at + i];
    }
    return v;
  }

  switch (tag(12)) {
    case 'VP8X':
      return (le(24, 3) + 1, le(27, 3) + 1);
    case 'VP8L':
      if (b[20] != 0x2f) return null;
      final bits = le(21, 4);
      return ((bits & 0x3fff) + 1, ((bits >> 14) & 0x3fff) + 1);
    case 'VP8 ':
      if (b[23] != 0x9d || b[24] != 0x01 || b[25] != 0x2a) return null;
      return (le(26, 2) & 0x3fff, le(28, 2) & 0x3fff);
  }
  return null;
}

Future<PetSource> _fromWebp(String path, {required String name}) async {
  final file = File(path);
  if (!file.existsSync()) throw PetSourceError('That file can’t be read');
  if (file.lengthSync() > _maxWebp) {
    throw PetSourceError('The WebP is larger than 8 MB');
  }
  final bytes = await file.readAsBytes();
  final size = webpSize(bytes);
  if (size == null) throw PetSourceError('That isn’t a WebP image');
  if (size != (1536, 1872) && size != (768, 936)) {
    throw PetSourceError(_sheetMessage);
  }
  final Uint8List png;
  try {
    final codec = await ui.instantiateImageCodec(bytes);
    try {
      final image = (await codec.getNextFrame()).image;
      try {
        final data = await image.toByteData(format: ui.ImageByteFormat.png);
        if (data == null) throw StateError('no PNG data');
        png = data.buffer.asUint8List(data.offsetInBytes, data.lengthInBytes);
      } finally {
        image.dispose();
      }
    } finally {
      codec.dispose();
    }
  } catch (_) {
    throw PetSourceError('The WebP can’t be decoded');
  }
  final temp = await Directory.systemTemp.createTemp('harness-pet-');
  final out = File(p.join(temp.path, 'sheet.png'));
  await out.writeAsBytes(png);
  return PetSource(
    pngPath: out.path,
    name: name,
    cleanup: () async {
      if (temp.existsSync()) await temp.delete(recursive: true);
    },
  );
}