Files
CoCo3_Plus_MiSTer/tools/install_mister.py
T

283 lines
12 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
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()