#!/usr/bin/env python3 """Install a verified overlay using existing passwordless OpenSSH access. Original Coco 3 Plus contributions: Copyright (c) 2026 Brian K. Holman. Original component notices/terms retained; see COPYRIGHT.md and LICENSING.md. """ import argparse import datetime import json import os from pathlib import Path, PurePosixPath import re import shlex import subprocess import sys import uuid from release import ROOT, make_release, sha LAUNCHER = '_Computer/Coco 3 Plus.mgl' def q(value): return shlex.quote(str(value)) def atomic_json(path, value): """Keep the last complete receipt if a local update itself is interrupted.""" temporary = path.with_name(path.name + '.' + uuid.uuid4().hex + '.tmp') with temporary.open('x', encoding='utf-8', newline='\n') as file: json.dump(value, file, indent=2) file.write('\n') file.flush() os.fsync(file.fileno()) os.replace(temporary, path) class OpenSshTarget: def __init__(self, host, user): self.options = ['-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes', '-o', 'ConnectTimeout=10'] self.target = user + '@' + host def run(self, script): return subprocess.check_output( ['ssh', *self.options, self.target, 'sh -s'], input=('set -eu\n' + script + '\n').encode(), stderr=subprocess.STDOUT).decode() def preflight(self): return self.run('test -d /media/fat\ntest -w /media/fat\n' 'test -e /dev/MiSTer_cmd\ncommand -v sha256sum\nid') def prepare(self, stage, backup): self.run('test ! -e ' + q(PurePosixPath(stage).parent) + '\nmkdir -p ' + q(stage) + ' ' + q(backup)) def upload(self, fat, stage): # Raw argv paths are intentional: SFTP handles spaces without shell quotes. subprocess.run(['scp', *self.options, '-r', str(fat), self.target + ':' + stage + '/'], check=True) def verify(self, files): lines = [] for name, digest in files.items(): lines.append('test "$(sha256sum ' + q(name) + ' | cut -d " " -f 1)" = ' + q(digest)) self.run('\n'.join(lines)) def enter_menu(self): self.run("printf 'load_core /media/fat/menu.rbf\\n' > /dev/MiSTer_cmd\nsleep 2") def install_file(self, source, destination, backup, entry, temporary): # Copy/verify beside the destination, then rename within the same FAT # filesystem. The staged original remains available for recovery. lines = [ 'mkdir -p ' + q(PurePosixPath(destination).parent) + ' ' + q(PurePosixPath(backup).parent), 'if [ -e ' + q(destination) + ' ]; then', ' test -f ' + q(destination), ] if entry['policy'] == 'create-if-missing': lines += [" printf 'preserved\\n'", ' exit 0'] else: lines += [' cp ' + q(destination) + ' ' + q(backup)] lines += [ 'fi', 'test ! -e ' + q(temporary), 'cp ' + q(source) + ' ' + q(temporary), 'test "$(sha256sum ' + q(temporary) + ' | cut -d " " -f 1)" = ' + q(entry['sha256']), 'mv -f ' + q(temporary) + ' ' + q(destination), 'test "$(sha256sum ' + q(destination) + ' | cut -d " " -f 1)" = ' + q(entry['sha256']), "printf 'installed\\n'", ] result = self.run('\n'.join(lines)).splitlines() if not result or result[-1] not in ('installed', 'preserved'): raise RuntimeError('Missing remote install result: ' + destination) return result[-1] def activate_launcher(self, source, destination, backup, entry, temporary): return self.install_file(source, destination, backup, entry, temporary) def sync(self): self.run('sync') def load(self): self.run("printf 'load_core /media/fat/_Computer/Coco 3 Plus.mgl\\n' > /dev/MiSTer_cmd") def validated_manifest(package): manifest = json.loads((package / 'manifest.json').read_text()) if manifest.get('public_package'): raise RuntimeError('Public core/source package omits required ROMs. ' 'Build a complete local package with your verified ' 'ROM inputs; see docs/INSTALL.md.') for name, entry in manifest['files'].items(): path = PurePosixPath(name) if path.is_absolute() or '..' in path.parts or '\\' in name: raise RuntimeError('Unsafe manifest path') if entry['policy'] not in ('create-if-missing', 'backup-and-replace'): raise RuntimeError('Unsupported install policy: ' + name) file = package / 'fat' / name if (not file.is_file() or file.stat().st_size != entry['bytes'] or sha(file) != entry['sha256']): raise RuntimeError('Release changed: ' + name) if (LAUNCHER not in manifest['files'] or manifest['files'][LAUNCHER]['policy'] != 'backup-and-replace'): raise RuntimeError('A replaceable Coco 3 Plus launcher is required') return manifest def install_release(package, host, user='root', load=False, *, target=None, stamp=None): """Install support first and activate last; target injection is for tests.""" package = Path(package).resolve() manifest = validated_manifest(package) if (not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._-]*', host) or not re.fullmatch(r'[A-Za-z_][A-Za-z0-9_-]*', user)): raise ValueError('Use a plain hostname/IP and Unix username') stamp = stamp or datetime.datetime.now(datetime.timezone.utc).strftime('%Y%m%dT%H%M%S%fZ') if not re.fullmatch(r'[A-Za-z0-9_-]{1,80}', stamp): raise ValueError('Invalid installation attempt identifier') remote = '/media/fat/.coco3plus/install-' + stamp backup, stage = remote + '/backup', remote + '/stage' receipt_path = package / ('install-receipt-' + stamp + '.json') latest_path = package / 'install-receipt.json' if receipt_path.exists(): raise RuntimeError('Preserve existing installation attempt: ' + str(receipt_path)) previous = None if latest_path.exists(): previous = package / ('install-receipt-before-' + stamp + '.json') with previous.open('xb') as file: file.write(latest_path.read_bytes()) plans = { name: dict(source=stage + '/fat/' + name, destination='/media/fat/' + name, backup=backup + '/' + name, temporary='/media/fat/' + name + '.install-' + stamp + '.tmp', policy=entry['policy']) for name, entry in manifest['files'].items() } receipt = dict( host=host, user=user, attempt=stamp, status='planned', phase='planned', remote=remote, stage=stage, backup=backup, manifest=manifest, receipt=str(receipt_path), previous_receipt=str(previous) if previous else None, launcher='/media/fat/' + LAUNCHER, launcher_temporary='/media/fat/' + LAUNCHER + '.install-' + stamp + '.tmp', activation_attempted=False, launcher_activated=False, load_requested=load, loaded=False, planned_files=plans, active_file=None, completed_files=[], history=['planned'], recovery='Preserve stage and backup. Before activation the old launcher ' 'remains, but supporting files may already have changed. Restore ' 'their backed-up copies if rollback is needed. If activation ' 'was attempted but not confirmed, inspect the launcher before ' 'loading; restore the backed-up launcher if needed.') def save(): atomic_json(receipt_path, receipt) atomic_json(latest_path, receipt) def phase(name): receipt['status'] = 'in-progress' receipt['phase'] = name receipt['history'].append(name) save() # A durable local plan names all recovery locations before target mutation. save() print('Planned receipt: ' + str(receipt_path), flush=True) print('Remote stage: ' + stage, flush=True) print('Remote backup: ' + backup, flush=True) client = target if target is not None else OpenSshTarget(host, user) try: phase('preflight') receipt['preflight_output'] = client.preflight() phase('staging') client.prepare(stage, backup) client.upload(package / 'fat', stage) phase('staged-verification') client.verify({stage + '/fat/' + n: v['sha256'] for n, v in manifest['files'].items()}) phase('returning-to-menu') client.enter_menu() phase('supporting-assets') installed = {} for name in sorted(n for n in manifest['files'] if n != LAUNCHER): entry = manifest['files'][name] receipt['active_file'] = name save() destination = '/media/fat/' + name result = client.install_file( stage + '/fat/' + name, destination, backup + '/' + name, entry, destination + '.install-' + stamp + '.tmp') receipt['completed_files'].append(dict(path=name, result=result)) receipt['active_file'] = None if result == 'installed': installed[destination] = entry['sha256'] save() client.verify(installed) client.sync() phase('activating-launcher') receipt['activation_attempted'] = True receipt['active_file'] = LAUNCHER # A transport failure during rename can leave activation uncertain. receipt['launcher_activated'] = None save() client.activate_launcher( stage + '/fat/' + LAUNCHER, receipt['launcher'], backup + '/' + LAUNCHER, manifest['files'][LAUNCHER], receipt['launcher_temporary']) receipt['launcher_activated'] = True receipt['active_file'] = None phase('launcher-activated') client.sync() if load: phase('loading') receipt['loaded'] = None save() client.load() receipt['loaded'] = True receipt['status'] = 'complete' receipt['phase'] = 'complete' receipt['history'].append('complete') save() except BaseException as error: receipt['status'] = 'failed' receipt['history'].append('failed') receipt['error'] = dict(type=type(error).__name__, message=str(error)) output = getattr(error, 'output', None) if output: receipt['error']['output'] = ( output.decode(errors='replace') if isinstance(output, bytes) else str(output))[-8192:] try: save() except Exception as save_error: print('Could not update failure receipt; prior plan remains at ' + str(receipt_path) + ': ' + str(save_error), file=sys.stderr) raise print('Installed Coco 3 Plus; backup: ' + backup + '; RBF ' + manifest['rbf_sha256']) print('Receipt: ' + str(receipt_path)) return receipt def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument('--host', help='IP or DNS hostname; prompted when omitted') parser.add_argument('--user', default='root') parser.add_argument('--release', type=Path, help='Existing tools/release.py output; otherwise package defaults') parser.add_argument('--without-ssc', action='store_true') parser.add_argument('--load', action='store_true', help='Return to MENU then load the new launcher') args = parser.parse_args() args.host = args.host or input('MiSTer IP address or hostname: ').strip() stamp = datetime.datetime.now(datetime.timezone.utc).strftime('%Y%m%dT%H%M%S%fZ') package = args.release.resolve() if args.release else ROOT / 'dist' / ('install-' + stamp) if not args.release: make_release(package, ROOT / 'build/fpga', ROOT / 'build/roms', ROOT / 'roms/ssc', args.without_ssc) install_release(package, args.host, args.user, args.load, stamp=stamp) if __name__ == '__main__': main()