Files

338 lines
15 KiB
Python

#!/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
import xml.etree.ElementTree as ET
from release import BOOT, SSC, ROOT, default_config, 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):
"""Require a coherent, ROM-complete local package before any target call."""
manifest = json.loads((package / 'manifest.json').read_text())
if not isinstance(manifest, dict) or type(manifest.get('format')) is not int or manifest['format'] != 1:
raise RuntimeError('Unsupported release manifest format')
if manifest.get('public_package') is not False or manifest.get('roms_required_separately') is not False:
raise RuntimeError('A complete local package with verified ROM inputs is required; see docs/INSTALL.md')
if type(manifest.get('ssc_included')) is not bool:
raise RuntimeError('Explicit SSC inclusion state is required')
digest = manifest.get('rbf_sha256')
if not isinstance(digest, str) or not re.fullmatch(r'[0-9a-f]{64}', digest):
raise RuntimeError('Invalid RBF SHA-256')
files = manifest.get('files')
if not isinstance(files, dict):
raise RuntimeError('Manifest file inventory is required')
for name, entry in files.items():
if not isinstance(name, str):
raise RuntimeError('Invalid manifest path')
path = PurePosixPath(name)
if (not name or path.is_absolute() or '..' in path.parts or
'\\' in name or ':' in name or path.as_posix() != name):
raise RuntimeError('Unsafe manifest path')
if (not isinstance(entry, dict) or type(entry.get('bytes')) is not int or
entry['bytes'] < 1 or not isinstance(entry.get('sha256'), str) or
not re.fullmatch(r'[0-9a-f]{64}', entry['sha256'])):
raise RuntimeError('Invalid file identity: ' + name)
if entry.get('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.is_symlink() or file.stat().st_size != entry['bytes'] or
sha(file) != entry['sha256']):
raise RuntimeError('Release changed: ' + name)
def require(name, identity=None, policy='backup-and-replace', content=None):
entry = files.get(name)
if entry is None or entry['policy'] != policy:
raise RuntimeError('Required package member/policy missing: ' + name)
if identity is not None and (entry['bytes'], entry['sha256']) != identity:
raise RuntimeError('Incorrect required identity: ' + name)
if content is not None and (package / 'fat' / name).read_bytes() != content:
raise RuntimeError('Incorrect required content: ' + name)
core = '_Computer/.coco3plus/' + digest[:12] + '/coco3plus.rbf'
require(core)
if files[core]['sha256'] != digest:
raise RuntimeError('RBF member contradicts top-level SHA-256')
require(LAUNCHER)
try:
launcher = ET.fromstring((package / 'fat' / LAUNCHER).read_bytes())
except ET.ParseError as error:
raise RuntimeError('Invalid Coco 3 Plus launcher XML') from error
if (launcher.tag != 'mistergamedescription' or launcher.attrib or
len(launcher) != 2 or len(launcher.findall('rbf')) != 1 or
len(launcher.findall('setname')) != 1 or
any(child.attrib or len(child) for child in launcher) or
launcher.findtext('rbf') != core[:-4] or
launcher.findtext('setname') != 'coco3plus'):
raise RuntimeError('Launcher RBF reference/setname contradicts package')
for name, identity in BOOT.items():
require('games/coco3plus/' + name, identity)
ssc = manifest['ssc_included']
require('config/coco3plus_v51.CFG', policy='create-if-missing',
content=default_config(ssc))
ssc_members = {'games/coco3plus/' + name for name in SSC}
ssc_members.update(('config/coco3plus.f4', 'config/coco3plus.f5'))
if ssc:
for name, identity in SSC.items():
require('games/coco3plus/' + name, identity)
for index, name in ((4, 'pic-7040-510.bin'), (5, 'sp0256-al2.bin')):
content = ('/media/fat/games/coco3plus/' + name).encode().ljust(1024, b'\0')
require('config/coco3plus.f' + str(index), content=content)
elif ssc_members.intersection(files):
raise RuntimeError('SSC files contradict disabled SSC package state')
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,
load_command_sent=False, startup_observed=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['load_command_sent'] = None
save()
client.load()
receipt['load_command_sent'] = 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()