kangshifu-board/scripts/package-workshop-docs-update.py

"""Build the nine-file public update from the accepted r2 archive and tested candidate."""
from pathlib import Path
import argparse
import hashlib
import json
import zipfile

ROOT = Path(__file__).resolve().parents[1]
OUT = ROOT / 'docs/workshop-skill-release-20261109-r3'
NAME = 'ksf-workshop-skill-update-20261109-r3'
OLD = ROOT / 'docs/workshop-skill-release-20261108-r2/ksf-workshop-unified-20261108-r2.zip'
sha = lambda b: hashlib.sha256(b).hexdigest()
encode = lambda obj: (json.dumps(obj, ensure_ascii=False, indent=2) + '\n').encode('utf-8')


def stage():
    assert sha(OLD.read_bytes()) == '65660a366589d1b7a6c93b333e9ab1017a487e4b3f5c7399f225c38aedb9e844'
    with zipfile.ZipFile(OLD) as z:
        old = json.loads(z.read('release.json'))
        baseline = old['candidate']
        # These exact bytes are only for isolated rehearsal, never included in the update.
        for n, h in baseline.items():
            body = z.read('skill/' + n)
            assert sha(body) == h
            p = OUT / 'rehearsal-baseline' / n
            p.parent.mkdir(parents=True, exist_ok=True)
            p.write_bytes(body)
        expected = json.loads(z.read('expected-agent-read.json'))
    assert len(baseline) == 38
    skill = ROOT / 'skills/ksf-workshop-runtime'
    candidate = {}
    for line in (skill / 'FILES.sha256').read_text(encoding='utf-8').splitlines():
        h, n = line.split('  ', 1)
        assert '..' not in Path(n).parts and not Path(n).is_absolute() and n not in candidate
        assert sha((skill / n).read_bytes()) == h
        candidate[n] = h
    assert len(candidate) == 38
    candidate['FILES.sha256'] = sha((skill / 'FILES.sha256').read_bytes())
    assert candidate['SKILL.md'] == 'd8f3c5bd3ba8cd24a40aad37a19f9e2b3404201726070abc9fef9ade552e06e0'
    delta = {n: h for n, h in candidate.items() if baseline.get(n) != h}
    assert len(delta) == 9 and len(set(candidate) - set(baseline)) == 1
    assert not set(baseline) - set(candidate)
    assert all(n in ('SKILL.md', 'FILES.sha256') or n.startswith('references/workshop-') and n.endswith('.md') for n in delta)
    assert all(candidate[n] == h for n, h in baseline.items() if n.startswith('scripts/') or n == 'runtime-lock.json')
    expected['skillFingerprint'] = candidate['SKILL.md']
    expected['generationPolicy'] = 'Pin current contract generation; compare every read and board to it.'
    release = {'schema': 'ksf.workshop-docs-update.v1', 'releaseId': NAME,
               'baselineRelease': old['releaseId'], 'baselineArchiveSha256': sha(OLD.read_bytes()),
               'baseline': baseline, 'candidate': candidate,
               'researchEntryNames': [n for n in old['legacyManifestPolicy']['entryNames'] if n != 'SKILL.md'],
               'researchRuntimePins': old['legacyManifestPolicy']['verifiedRuntimeEntries'],
               'plannedChanges': [{'path': n, 'action': 'update' if n in baseline else 'create',
                                   'beforeSha256': baseline.get(n), 'afterSha256': h} for n, h in delta.items()],
               'runtimeReplacementAllowed': False, 'businessWritesDuringUpgrade': False,
               'serviceRestartAllowed': False, 'credentialsIncluded': False}
    acceptance_path = ROOT / 'docs/workshop-skill-retest-20261109-r2/retest-acceptance.json'
    acceptance = json.loads(acceptance_path.read_bytes())
    integrity = json.loads((acceptance_path.parent / 'skill-integrity.json').read_bytes())
    assert integrity['ok'] and integrity['skillSha256'] == candidate['SKILL.md']
    assert integrity['manifestSha256'] == candidate['FILES.sha256']
    assert acceptance['interfaceAcceptance']['failed'] == 0 and acceptance['regression']['failed'] == 0
    compact = {'schema': 'ksf.workshop-local-acceptance-summary.v1',
               'skillSha256': candidate['SKILL.md'], 'manifestSha256': candidate['FILES.sha256'],
               'sourceReceiptSha256': sha(acceptance_path.read_bytes()),
               'scope': 'isolated constructed case; no production calls or writes',
               'courseModules': 13, 'reports': 21, 'opportunityEntities': 5,
               'interfaceChecksPassed': acceptance['interfaceAcceptance']['passed'],
               'regressionPassed': acceptance['regression']['passed'],
               'browserReportViewportChecks': acceptance['browser']['totalReportViewportChecks'],
               'viewportWidths': acceptance['browser']['viewportWidths'],
               'manifestEntries': integrity['manifestEntries'], 'relativeLinks': integrity['relativeLinks'],
               'independentContextGenerationAndReview': True, 'actualDifferentModelReview': False,
               'productionDatabaseWrites': 0, 'paidCalls': 0, 'originalLiveCaseResumed': False,
               'notPerformed': acceptance['notPerformed']}
    files = {'payload/' + n: (skill / n).read_bytes() for n in delta}
    files.update({'release.json': encode(release), 'expected-agent-read.json': encode(expected),
                  'update-skill.mjs': (ROOT / 'scripts/update-workshop-docs.mjs').read_bytes(),
                  'run-update.py': (ROOT / 'scripts/run-workshop-docs-update.py').read_bytes(),
                  'probe-agent-library-read.py': (ROOT / 'scripts/probe-agent-library-read.py').read_bytes(),
                  'README.md': (OUT / 'README.md').read_bytes(), 'CHANGES.md': (OUT / 'CHANGES.md').read_bytes(),
                  'local-acceptance.json': encode(compact)})
    validation = OUT / 'installer-validation.json'
    if validation.exists():
        v = json.loads(validation.read_bytes())
        assert v['ok'] and v['updaterSha256'] == sha(files['update-skill.mjs'])
        assert v['runnerSha256'] == sha(files['run-update.py'])
        files['installer-validation.json'] = validation.read_bytes()
    for n in files:
        assert not any(t in n.lower() for t in ('credential-binding', 'private.pem', 'envelope', 'channel-config'))
    files['FILES.sha256'] = ''.join(sha(raw) + '  ' + n + '\n' for n, raw in sorted(files.items())).encode()
    for n, raw in files.items():
        p = OUT / 'package' / n
        p.parent.mkdir(parents=True, exist_ok=True)
        p.write_bytes(raw)
    return files, release


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('--pack', action='store_true')
    args = parser.parse_args()
    files, release = stage()
    if not args.pack:
        print(json.dumps({'ok': True, 'staged': len(files), 'changes': 9, 'packageDir': str(OUT / 'package')}))
        return
    assert 'installer-validation.json' in files, 'Run installer tests before packaging'
    dest = OUT / (NAME + '.zip')
    assert not dest.exists(), 'Do not overwrite a released ZIP; choose a new revision'
    with zipfile.ZipFile(dest, 'x', zipfile.ZIP_DEFLATED) as z:
        for n, raw in sorted(files.items()):
            info = zipfile.ZipInfo(n, (2026, 11, 9, 0, 0, 0))
            info.external_attr = 0o100600 << 16
            z.writestr(info, raw, compress_type=zipfile.ZIP_DEFLATED)
    with zipfile.ZipFile(dest) as z:
        assert z.testzip() is None and set(z.namelist()) == set(files)
        for n, raw in files.items():
            assert z.read(n) == raw
    receipt = {'ok': True, 'releaseId': NAME, 'filename': dest.name,
               'bytes': dest.stat().st_size, 'sha256': sha(dest.read_bytes()),
               'packageEntries': len(files), 'outerManifestEntries': len(files) - 1,
               'payloadFiles': 9, 'targetPublicFiles': 39, 'targetManifestEntries': 38,
               'updates': 8, 'creates': 1, 'runtimeFilesChanged': 0,
               'candidateSkillSha256': release['candidate']['SKILL.md'],
               'candidateManifestSha256': release['candidate']['FILES.sha256'],
               'credentialsIncluded': False, 'remoteInstalled': False, 'paidCalls': 0}
    (OUT / 'package-receipt.json').write_bytes(encode(receipt))
    print(json.dumps(receipt, ensure_ascii=False, indent=2))


if __name__ == '__main__':
    main()