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