Harden release packaging and recoverable installation after review

This commit is contained in:
bholman committed 2026-11-18 16:26:25 -07:00
1 parent cb40fed3b9
commit 8088c1fbf6
14 files changed
+933 -101

No files matched your search

+280 -52
View File
@@ -1,54 +1,282 @@
#!/usr/bin/env python3
"""Install a verified overlay using existing passwordless OpenSSH access."""
import argparse,datetime,json,re,shlex,subprocess
from pathlib import Path,PurePosixPath
from release import ROOT,make_release,sha
def q(s):return shlex.quote(str(s))
def main():
p=argparse.ArgumentParser(description=__doc__)
p.add_argument('--host',help='IP or DNS hostname; prompted when omitted')
p.add_argument('--user',default='root')
p.add_argument('--release',type=Path,help='Existing tools/release.py output; otherwise package defaults')
p.add_argument('--without-ssc',action='store_true')
p.add_argument('--load',action='store_true',help='Return to MENU then load the new launcher')
a=p.parse_args();a.host=a.host or input('MiSTer IP address or hostname: ').strip()
if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._-]*',a.host) or not re.fullmatch(r'[A-Za-z_][A-Za-z0-9_-]*',a.user):p.error('Use a plain hostname/IP and Unix username')
stamp=datetime.datetime.now(datetime.timezone.utc).strftime('%Y%m%dT%H%M%S%fZ')
release=a.release.resolve() if a.release else ROOT/'dist'/('install-'+stamp)
if not a.release:make_release(release,ROOT/'build/fpga',ROOT/'build/roms',ROOT/'roms/ssc',a.without_ssc)
manifest=json.loads((release/'manifest.json').read_text());fat=release/'fat'
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 n,v in manifest['files'].items():
path=PurePosixPath(n)
if path.is_absolute() or '..' in path.parts or '\\' in n:raise RuntimeError('Unsafe manifest path')
file=fat/n
if not file.is_file() or file.stat().st_size!=v['bytes'] or sha(file)!=v['sha256']:raise RuntimeError('Release changed: '+n)
args=['-o','BatchMode=yes','-o','StrictHostKeyChecking=yes','-o','ConnectTimeout=10']
target=a.user+'@'+a.host
def ssh(script):return subprocess.check_output(['ssh',*args,target,'sh -s'],input=script.encode(),stderr=subprocess.STDOUT).decode()
# No target writes before all local hashes and this read-only preflight pass.
print(ssh('set -eu\ntest -d /media/fat\ntest -w /media/fat\ntest -e /dev/MiSTer_cmd\ncommand -v sha256sum\nid\n').strip())
remote='/media/fat/.coco3plus/install-'+stamp;backup=remote+'/backup';stage=remote+'/stage'
ssh('set -eu\nmkdir -p '+q(stage)+' '+q(backup)+'\n')
# Raw argv paths are intentional: OpenSSH SFTP handles spaces without shell quoting.
subprocess.run(['scp',*args,'-r',str(fat),target+':'+stage+'/'],check=True)
lines=['set -eu']
for n,v in manifest['files'].items():lines.append('test "$(sha256sum '+q(stage+'/fat/'+n)+' | cut -d " " -f 1)" = '+q(v['sha256']))
lines.append("printf 'load_core /media/fat/menu.rbf\\n' > /dev/MiSTer_cmd")
lines.append('sleep 2')
for n,v in manifest['files'].items():
src=stage+'/fat/'+n;dest='/media/fat/'+n;old=backup+'/'+n
lines.append('mkdir -p '+q(str(PurePosixPath(dest).parent))+' '+q(str(PurePosixPath(old).parent)))
if v['policy']=='create-if-missing':lines.append('if [ ! -e '+q(dest)+' ]; then cp '+q(src)+' '+q(dest)+'; fi')
"""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.append('if [ -e '+q(dest)+' ]; then cp '+q(dest)+' '+q(old)+'; fi')
lines.append('cp '+q(src)+' '+q(dest))
lines.append('test "$(sha256sum '+q(dest)+' | cut -d " " -f 1)" = '+q(v['sha256']))
lines.append('sync')
if a.load:lines.append("printf 'load_core /media/fat/_Computer/Coco 3 Plus.mgl\\n' > /dev/MiSTer_cmd")
result=ssh('\n'.join(lines)+'\n')
receipt=dict(host=a.host,user=a.user,backup=backup,manifest=manifest,loaded=a.load,remote_output=result)
(release/'install-receipt.json').write_text(json.dumps(receipt,indent=2)+'\n')
print('Installed Coco 3 Plus; backup: '+backup+'; RBF '+manifest['rbf_sha256'])
print('Receipt: '+str(release/'install-receipt.json'))
if __name__=='__main__':main()
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()
+82 -13
View File
@@ -1,8 +1,23 @@
#!/usr/bin/env python3
"""Create a checked, copyable MiSTer FAT-volume overlay from a standalone build."""
import argparse,datetime,hashlib,json,shutil,subprocess,zipfile
from pathlib import Path
from pathlib import Path,PurePosixPath
ROOT=Path(__file__).resolve().parents[1]
# Reviewed source-package content. The repository retains all upstream history;
# a source-review ZIP deliberately omits historical RBFs, Office files and PDFs.
SOURCE_ROOT_FILES={'.gitattributes','.gitignore','AGENTS.md','CHANGELOG.md',
'COPYRIGHT.md','LICENSING.md','NOTICE.md','README.md','CoCo3.qpf','CoCo3.qsf',
'CoCo3.sv','CoCo3FPGA.sdc','build_id_num.v','changes.txt','external-io.sdc',
'files.qip','pll.xml','reset-cpu.sdc','uart-reset.sdc'}
SOURCE_SUFFIXES={
'docs':{'.md','.vhd'},'roms':{'.md'},
'rtl':{'.sv','.v','.vh','.vhd','.mif','.hex','.qip','.qsys','.ip','.tcl','.sdc',
'.ppf','.sip','.spd'},
'sys':{'.sv','.v','.vh','.vhd','.mif','.hex','.qip','.qsys','.ip','.tcl','.sdc'},
'scripts':{'.py','.tcl'},'tests':{'.py','.sv'},'tools':{'.py','.json'},
'validation':{'.json'},'windows':{'.ps1'}}
SOURCE_REPOSITORY='https://vccplus-git.brianholman.com/VCCPlus/CoCo3_Plus_MiSTer.git'
NON_HASHED_BUILD_FILES={'.gitignore','README.md','changes.txt'}
SSC={'pic-7040-510.bin':(4096,'0013cd78482cc5f2360fdf584e9ba51d34861e8ccd9d88247f1a54039c16c365'),
'sp0256-al2.bin':(2048,'98c280fd082169c54081e503dfe7d7d9a6fd46d4ffcc973e199ea0e1d9bc1ac9')}
BOOT={'boot0.rom':(32768,'ad358430568250eb8330a37f85361d9ce67e5ae6d5a28c17b31802cd3953a5d2'),
@@ -11,6 +26,43 @@ def sha(p):return hashlib.sha256(p.read_bytes()).hexdigest()
def checked(p,size,digest):
if not p.is_file() or p.stat().st_size!=size or sha(p)!=digest:raise RuntimeError('Missing or incorrect input: '+str(p))
return p
def qualify_inputs(record):
inventory_path=ROOT/'tools/project_inputs.json'
if 'project_inventory_sha256' not in record:
raise RuntimeError('Legacy FPGA receipt lacks project_inventory_sha256; preserve it unchanged and run a fresh independently qualified build. Do not backfill fit evidence.')
if record['project_inventory_sha256']!=sha(inventory_path):
raise RuntimeError('FPGA receipt does not qualify the current tools/project_inputs.json')
names=json.loads(inventory_path.read_text())['files']
if not isinstance(names,list) or len(names)!=len(set(names)):
raise RuntimeError('Invalid or duplicate project input inventory')
for name in names:
path=PurePosixPath(name)
if path.is_absolute() or '..' in path.parts or '\\' in name or ':' in name:
raise RuntimeError('Unsafe project input: '+name)
expected=set(names)-NON_HASHED_BUILD_FILES
actual=record.get('inputs')
if not isinstance(actual,dict) or set(actual)!=expected:
raise RuntimeError('FPGA receipt must qualify the exact current project input set')
for name,digest in actual.items():
path=ROOT/name
if not path.is_file() or path.is_symlink() or sha(path)!=digest:
raise RuntimeError('Source differs from built input: '+name)
def committed_tree(revision):
tree={}
for entry in subprocess.check_output(['git','ls-tree','-rz','--full-tree',revision],cwd=ROOT).split(b'\0'):
if not entry:continue
metadata,name=entry.split(b'\t',1)
mode,kind,object_id=metadata.split()
if kind==b'blob' and mode in (b'100644',b'100755'):
tree[name.decode('utf-8')]=object_id.decode('ascii')
return tree
def committed_blob(object_id):
return subprocess.check_output(['git','cat-file','blob',object_id],cwd=ROOT)
def source_member(name):
path=PurePosixPath(name)
if name in SOURCE_ROOT_FILES or name=='rtl/ssc/LICENSE':return True
if len(path.parts)==2 and path.parts[0]=='LICENSES':return True
return len(path.parts)>1 and path.suffix.lower() in SOURCE_SUFFIXES.get(path.parts[0],set())
def default_config(ssc):
# Main serializes cur_status[16] in byte order, low bits first.
# Audio / SDC / ROM / Floppy, startup Slot4, 512K; migrated-layout marker.
@@ -21,23 +73,24 @@ def make_release(output,build,roms,ssc,without_ssc=False,public=False):
record=json.loads((build/'build.json').read_text())
if not record.get('passed'):raise RuntimeError('Successful standalone FPGA build required')
rbf=checked(build/'project/output_files/CoCo3.rbf',record['rbf_bytes'],record['rbf_sha256'])
for n,h in record['inputs'].items():
if sha(ROOT/n)!=h:raise RuntimeError('Source differs from built input: '+n)
qualify_inputs(record)
inputs={} if public else {f'games/coco3plus/{n}':checked(roms/n,*identity) for n,identity in BOOT.items()}
if not without_ssc and not public:inputs.update({f'games/coco3plus/{n}':checked(ssc/n,*v) for n,v in SSC.items()})
if subprocess.check_output(['git','status','--porcelain','--untracked-files=no'],cwd=ROOT).strip():raise RuntimeError('Commit reviewed changes before creating a distributable source package')
source_revision=subprocess.check_output(['git','rev-parse','HEAD'],cwd=ROOT).decode().strip()
tree=committed_tree(source_revision)
notice_names={'NOTICE.md','LICENSING.md','COPYRIGHT.md','rtl/ssc/LICENSE'}
notice_names.update(name for name in tree if len(PurePosixPath(name).parts)==2 and name.startswith('LICENSES/'))
if not notice_names<=tree.keys():raise RuntimeError('Required committed license notices missing')
if output.exists():raise RuntimeError('Preserve previous release: '+str(output))
fat=output/'fat';fat.mkdir(parents=True)
core=f'_Computer/.coco3plus/{record["rbf_sha256"][:12]}/coco3plus.rbf';inputs[core]=rbf
for name in ('NOTICE.md','LICENSING.md','COPYRIGHT.md'):
inputs['games/coco3plus/licenses/'+name]=ROOT/name
for folder in (ROOT/'LICENSES',):
for file in folder.glob('*'):
if file.is_file():inputs['games/coco3plus/licenses/'+file.name]=file
inputs['games/coco3plus/licenses/SSC-BSD-3-Clause.txt']=ROOT/'rtl/ssc/LICENSE'
for n,p in inputs.items():
target=fat/n;target.parent.mkdir(parents=True,exist_ok=True);shutil.copyfile(p,target)
for name in sorted(notice_names):
leaf='SSC-BSD-3-Clause.txt' if name=='rtl/ssc/LICENSE' else PurePosixPath(name).name
target=fat/'games/coco3plus/licenses'/leaf;target.parent.mkdir(parents=True,exist_ok=True)
target.write_bytes(committed_blob(tree[name]))
launcher=fat/'_Computer/Coco 3 Plus.mgl';launcher.parent.mkdir(exist_ok=True)
launcher.write_text(f'<mistergamedescription>\n <rbf>{core[:-4]}</rbf>\n <setname>coco3plus</setname>\n</mistergamedescription>\n',newline='\n')
config=fat/'config';config.mkdir()
@@ -56,11 +109,27 @@ def make_release(output,build,roms,ssc,without_ssc=False,public=False):
(output/'README.txt').write_text('Coco 3 Plus FAT-volume overlay. This is not a bootable disk image.\nCopy fat/ CONTENTS to the MiSTer FAT-volume root with MiSTer shut down.\nPreserve existing config/coco3plus_v51.CFG. Back up files before replacing.\nOriginal CoCo3 and other cores are not replaced. Start Computer/Coco 3 Plus.\nSSC ROMs, when included, are separately supplied local inputs; do not redistribute without permission.\n')
if public:
with (output/'README.txt').open('a') as file:file.write('PUBLIC CORE/SOURCE PACKAGE: no CoCo boot or SSC ROMs included.\nBefore launching, supply boot0.rom and boot1.rom in games/coco3plus and the SSC ROMs if using SSC.\nSee roms/README.md and docs/INSTALL.md in corresponding-source.zip for exact identities and source-build installation.\nThis incomplete-ROM public package is not accepted directly by the SSH installer. Build a complete local package using your own verified ROM inputs.\n')
# Git's reviewed committed tree is the only source-export allowlist. Untracked
# notes, .env files and ignored ROM/cache inputs can never enter this archive.
with (output/'corresponding-source.zip').open('xb') as file:
subprocess.run(['git','archive','--format=zip','--prefix=coco3plus/',source_revision],cwd=ROOT,stdout=file,check=True)
# Use reviewed paths AND committed bytes. This ZIP has no .git metadata; the
# supported build route is a pinned full clone, not an extracted archive.
source_names=sorted(name for name in tree if source_member(name))
with zipfile.ZipFile(output/'corresponding-source.zip','x',zipfile.ZIP_DEFLATED) as archive:
for name in source_names:archive.writestr('coco3plus/'+name,committed_blob(tree[name]))
checkout=('SOURCE REVIEW ARCHIVE: no Git metadata or historical binary/manual artifacts.\n'
'Build tools require Git metadata and the full maintained project inventory.\n'
'Use Git for Windows, Python 3.10+ and the pinned Quartus toolchain.\n'
'Clone the full repository (do not use --depth), then detach at this exact revision:\n'
f'git clone {SOURCE_REPOSITORY} coco3plus\n'
'cd coco3plus\n'
f'git checkout --detach {source_revision}\n'
'git rev-parse HEAD\n'
'Follow docs/BUILD_WINDOWS.md in that checkout. Repository access is required.\n'
'The source review ZIP alone is not a standalone build checkout.\n')
(output/'SOURCE-CHECKOUT.txt').write_text(checkout)
with (output/'README.txt').open('a') as file:file.write('For the supported pinned Git build route, see SOURCE-CHECKOUT.txt. The source-review ZIP alone cannot run the build scripts.\n')
manifest['source_revision']=source_revision
manifest['project_inventory_sha256']=record['project_inventory_sha256']
manifest['source_files']=source_names
manifest['source_build_route']='Pinned full Git checkout; see SOURCE-CHECKOUT.txt'
manifest['corresponding_source_sha256']=sha(output/'corresponding-source.zip')
(output/'manifest.json').write_text(json.dumps(manifest,indent=2)+'\n')
archive_path=output.with_name(output.name+'.zip')