Publish Bone Quest player manual and release sources

This commit is contained in:
Brian Holman committed 2026-11-11 23:49:29 -07:00
1 parent 2ceb44a48c
commit ea87321e61
22 files changed
+996 -3

No files matched your search

+190
View File
@@ -0,0 +1,190 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-or-later
"""Create deterministic Bone Quest release packages from reviewed local inputs.
Does not publish, mutate Git, run a game or modify source inputs. The optional
qualification rebuilds an extracted starter in fresh configuration directories.
Use --libraries-only to freeze the companion URL before finalizing the manual.
"""
import argparse
import hashlib
import json
import os
from pathlib import Path
import re
import shutil
import subprocess
import tempfile
from zipfile import ZIP_DEFLATED, ZipFile, ZipInfo
ROOT=Path(__file__).resolve().parents[1]
APPROVED_DISK='373a3f387daf541b1eb4edd3421a125dd57094e600ee48d162802ac22f65ceba'
EDITION='2026-11-11'
BASE='https://vccplus.brianholman.com/dl/software/CoCoLibrary/'
PROJECT='https://vccplus-git.brianholman.com/VCCPlusApps/BoneQuest'
ROOT_FILES=('AGENTS.md','LICENSE','Makefile','README.md','.gitignore','.gitattributes','vccplus-project.json','main.c')
DIRECTORIES=('src','data','assets','tests','tools','docs/manual')
EXTRA_FILES=('docs/PROVENANCE.md','docs/PUBLIC_RELEASE.md','docs/ANATOMY.md','docs/IMPLEMENTATION.md')
BAD_SUFFIXES={'.dsk','.rom','.bin','.o','.a','.pdf','.zip','.pyc','.map','.link','.lst','.log','.ecb_o','.dylib','.so','.exe'}
def sha(data):return hashlib.sha256(data).hexdigest()
def dump(path,value):path.write_text(json.dumps(value,indent=2)+'\n')
def record(path):return dict(bytes=path.stat().st_size,sha256=sha(path.read_bytes()))
def write_zip(path,files):
if path.exists():raise ValueError('Retain completed packages unchanged; choose a fresh output: '+str(path))
with ZipFile(path,'x',ZIP_DEFLATED,compresslevel=9) as archive:
for name,data in sorted(files.items()):
info=ZipInfo(name,date_time=(1980,1,1,0,0,0));info.create_system=3
info.external_attr=0o100644<<16;info.compress_type=ZIP_DEFLATED;info._compresslevel=9
archive.writestr(info,data)
def regular(path):
if path.is_symlink() or not path.is_file():raise ValueError('Expected a regular file: '+str(path))
return path.read_bytes()
def source_files(root):
names=set(ROOT_FILES+EXTRA_FILES)
names.update(p.name for p in root.glob('*.h'))
for directory in DIRECTORIES:
folder=root/directory
if not folder.is_dir():raise ValueError('Missing source directory: '+directory)
for path in folder.rglob('*'):
if path.is_symlink():raise ValueError('Source symlink is not permitted: '+str(path))
if path.is_dir():continue
if '__pycache__' in path.parts or path.name=='.DS_Store':continue
names.add(path.relative_to(root).as_posix())
result={}
for name in sorted(names):
path=root/name
if any(word in name.casefold() for word in ('connection','vccgrant')):raise ValueError('Private connection filename: '+name)
if path.suffix.casefold() in BAD_SUFFIXES:raise ValueError('Generated/private binary is not starter source: '+name)
result['BoneQuest/'+name]=regular(path)
return result
def library_files(root):
inventory=json.loads(regular(root/'SOURCE_INVENTORY.json'))
expected=inventory['sourceFilesSHA256']
for name,value in expected.items():
if sha(regular(root/name))!=value:raise ValueError('Library source input changed: '+name)
result={}
for path in sorted(root.rglob('*')):
if path.is_dir():continue
name=path.relative_to(root).as_posix()
if '__pycache__' in path.parts or path.name=='.DS_Store':continue
if path.suffix.casefold() in BAD_SUFFIXES:raise ValueError('Compiled/private companion input: '+name)
if name!='SOURCE_INVENTORY.json' and name not in expected:raise ValueError('Unrecorded library source input: '+name)
result['BoneQuest-Library-Sources/'+name]=regular(path)
return result
def url(area,digest,name):return BASE+area+'/Exclusives/BoneQuest/'+EDITION+'/'+digest[:12]+'/'+name
def resource(path,area):
r=record(path);return dict(url=url(area,r['sha256'],path.name),sha256=r['sha256'],byte_size=r['bytes'])
def qualify(source_zip,out,toolchain):
reports=[];env=dict(os.environ,PATH=str(toolchain/'bin')+':/usr/bin:/bin',LC_ALL='C',
DEVELOPER_DIR='/no-host-developer-tools',SDKROOT='/no-host-sdk')
for config in ('Release','Debug','Test'):
folder=out/('qualify-'+config);folder.mkdir()
with ZipFile(source_zip) as archive:archive.extractall(folder)
project=folder/'BoneQuest'
with (folder/'build.log').open('w') as log:
subprocess.run([str(toolchain/'bin/make'),'-j4','VCC_CONFIGURATION='+config,'disk'],cwd=project,env=env,stdout=log,stderr=subprocess.STDOUT,check=True)
disk=project/'build/BONEQ.dsk';mp=(project/'build/BONEQ.map').read_text()
end=re.search(r'Symbol: program_end .*?= ([0-9A-Fa-f]+)',mp)[1]
r=dict(configuration=config,programEnd=end,diskSHA256=sha(disk.read_bytes()),ordinaryBuildWithoutAuthoringTools=True)
if config=='Release' and r['diskSHA256']!=APPROVED_DISK:raise ValueError('Extracted Release differs from approved disk')
reports.append(r)
return reports
def main():
p=argparse.ArgumentParser(description=__doc__)
p.add_argument('--source-root',type=Path,default=ROOT)
p.add_argument('--library-sources',type=Path,required=True)
p.add_argument('--output',type=Path,required=True,help='A fresh retained output directory')
p.add_argument('--revision',help='Exact reviewed source revision, recorded in publication descriptor')
p.add_argument('--pdf',type=Path,help='Reviewed final manual PDF, required for a full release')
p.add_argument('--cover',type=Path,help='Unmodified guest title PNG (defaults to docs/manual/images/title.png)')
p.add_argument('--libraries-only',action='store_true')
p.add_argument('--qualify',action='store_true',help='Rebuild extracted starter in all three configurations')
p.add_argument('--toolchain',type=Path,default=Path('/Applications/VCC Plus.app/Contents/Resources/Toolchain'))
a=p.parse_args();root=a.source_root.resolve();out=a.output.resolve();libraries=a.library_sources.resolve()
if out.exists():p.error('Use a fresh output directory; retain completed outputs unchanged')
if root==out or out in root.parents:p.error('Output must not contain the source checkout')
if root in out.parents and out.relative_to(root).parts[0] not in ('test-output','.release'):
p.error('Keep package output outside the source tree or beneath ignored test-output/.release')
if not a.libraries_only and (not a.pdf or not a.revision):p.error('Full release needs --pdf and --revision')
if a.revision and not re.fullmatch(r'[0-9a-f]{40}',a.revision):p.error('Use a full 40-character source commit')
out.mkdir(parents=True)
library_zip=out/'Bone-Quest-Library-Sources.zip';write_zip(library_zip,library_files(libraries))
library_resource=resource(library_zip,'Sources')
if a.libraries_only:
dump(out/'ARTIFACTS.json',{library_zip.name:record(library_zip)})
print(json.dumps(library_resource,indent=2));return
disk_bytes=regular(root/'BONEQ.DSK')
if sha(disk_bytes)!=APPROVED_DISK:raise ValueError('Approved BONEQ.DSK identity changed')
(out/'BONEQ.DSK').write_bytes(disk_bytes)
source_zip=out/'Bone-Quest-Source.zip';files=source_files(root);write_zip(source_zip,files)
r=record(source_zip)
manifest=dict(schemaVersion=1,projectDirectory='BoneQuest',configurationFile='BoneQuest/vccplus-project.json',entrySource='main.c',
archive=source_zip.name,byteSize=r['bytes'],sha256=r['sha256'],
files=[dict(path=name,byteSize=len(data),sha256=sha(data)) for name,data in sorted(files.items())])
dump(out/'Bone-Quest-Source.manifest.json',manifest)
source_resource=resource(source_zip,'Sources')
notice=('Bone Quest for CoCo - dated edition '+EDITION+'\n\n'
'Designed by Brian Holman with assistance from ChatGPT/Codex.\n'
'Game and manual: GPL-3.0-or-later. Preserve component-specific terms.\n'
'Project: '+PROJECT+'\n'
'Game source starter: '+source_resource['url']+'\n'
'Matching library sources: '+library_resource['url']+'\n'
'Player manual: https://vccplus.brianholman.com/games/bone-quest/\n\n'
'Skeleton: Mariana Ruiz Villarreal (LadyofHats), author\'s public-domain\n'
'dedication via Wikimedia Commons: https://commons.wikimedia.org/wiki/File:Human_skeleton_front_en.svg\n'
'Adaptations remove labels, fit the CoCo pixel aspect, preserve linework,\n'
'assign 28 structure regions, add detail views and relax the left thumb pose.\n'
'The original SVG and source hash are retained; no endorsement is implied.\n\n'
'Font and boot helper: Pierre Sarrazin, public-domain notices retained.\n'
'BControl retains its original keyboard implementation and file-specific\n'
'Color Basic exception. CMOC/VCC Plus SDK sources retain their GPL terms;\n'
'the ROM-backed decbfile library retains its public-domain dedication.\n'
'No ROM or optional standalone Disk BASIC-derived driver is included.\n\n'
'Use a 512 KB CoCo 3, RGB, FD-502 Disk BASIC. Insert BONEQ.DSK in drive 0,\n'
'Cold Restart, then DOS. Q/Escape/Break quit to BASIC; blank Enter reveals.\n'
'This disk is read-only in play; scores are not saved.\n')
(out/'NOTICE.txt').write_text(notice)
native=out/'Bone-Quest.zip';write_zip(native,{'BONEQ.DSK':disk_bytes,'NOTICE.txt':notice.encode()})
pdf_bytes=regular(a.pdf.resolve())
if not pdf_bytes.startswith(b'%PDF-'):raise ValueError('Expected the reviewed PDF')
(out/'Bone-Quest-Manual.pdf').write_bytes(pdf_bytes)
cover=regular((a.cover or root/'docs/manual/images/title.png').resolve())
if not cover.startswith(b'\x89PNG\r\n\x1a\n'):raise ValueError('Expected actual guest PNG cover')
for name in ('cover.png','hero.png'):(out/name).write_bytes(cover)
native_r=record(native);cover_r=resource(out/'cover.png','Artwork/Thumbnails');hero_r=resource(out/'hero.png','Artwork/Thumbnails')
descriptor=dict(schema_version=1,id='vccplus.bone-quest',title='Bone Quest for CoCo',release_id='vccplus.bone-quest.'+EDITION,
game_version=EDITION,publication_status='approved',getting_started=True,browse_categories=['Educational','Games'],primary_browse_category='Educational',category_featured=True,
provenance=dict(kind='project-owned',collection='vccplus-exclusive',author='Brian Holman',license='GPL-3.0-or-later; skeleton public domain; component terms retained',project_url=PROJECT),
disk_package=dict(url=BASE+'Exclusives/BoneQuest/'+EDITION+'/'+APPROVED_DISK[:12]+'/'+native.name,sha256=native_r['sha256'],byte_size=native_r['bytes']),
disk=dict(path='BONEQ.DSK',sha256=APPROVED_DISK,byte_size=len(disk_bytes)),
setup=dict(configuration=dict(profile='disk-basic',processor='6809',ram_kib=512),selected_members=[dict(path='BONEQ.DSK',target='disk0')],command='DOS\r',
validation=dict(scope='runtime-verified',disk_sha256=APPROVED_DISK,app='VCC Plus 3.6.1 (54)',video='RGB',controller='FD-502 Disk BASIC')),
first_play=dict(mode='cold-restart-dos'),links=dict(manual_online='https://vccplus.brianholman.com/games/bone-quest/',manual_pdf=resource(out/'Bone-Quest-Manual.pdf','Documents/Manuals'),source_repository=PROJECT),
source=dict(package=source_resource,project_directory='BoneQuest',configuration_file='BoneQuest/vccplus-project.json',entry_source='main.c',
license_files=['BoneQuest/'+n for n in ('LICENSE','assets/CREDITS.md','assets/BCONTROL-NOTICE.txt','assets/HIRESTXT-NOTICE.txt','assets/VCC-Guest-SDK-NOTICE.txt')]),
artwork=dict(cover=cover_r,hero=hero_r),library_sources=library_resource,source_revision=a.revision,minimum_source_app=dict(version='3.6.1',build=54))
dump(out/'exclusive-title.json',descriptor)
if a.qualify:dump(out/'source-qualification.json',qualify(source_zip,out,a.toolchain.resolve()))
# Only delivery files belong in this inventory, not generated build trees.
dump(out/'ARTIFACTS.json',{p.name:record(p) for p in sorted(out.iterdir()) if p.is_file() and p.name!='ARTIFACTS.json'})
print(json.dumps({'output':str(out),'diskSHA256':APPROVED_DISK,'sourceRevision':a.revision,'librarySources':library_resource},indent=2))
if __name__=='__main__':main()