Files
VCCPlusOSS/platforms/macos/App/SoftwareLibraryCatalog.swift

680 lines
40 KiB
Swift

// SPDX-License-Identifier: GPL-3.0-or-later
import Foundation
import SQLite3
// Immutable snapshots cross from the loading task to the native browser. The
// bundled database is opened read-only; no user state is ever written into it.
struct SoftwareLibraryCatalog: Codable, Sendable {
let titles: [SoftwareLibraryTitle]
let metadata: [String: String]
var releaseCount: Int { titles.reduce(0) { $0 + $1.releases.count } }
var releases: [SoftwareLibraryRelease] { titles.flatMap(\.releases) }
var categories: [String] { Array(Set(releases.filter { $0.ownedGame == nil }.map(\.category))).sorted() }
static func bundledURL(in bundle: Bundle = .main) -> URL? {
bundle.url(forResource: "catalog", withExtension: "sqlite", subdirectory: "SoftwareLibrary")
?? bundle.url(forResource: "app-catalog", withExtension: "sqlite")
}
static func load(from url: URL) async throws -> Self {
try await Task.detached(priority: .userInitiated) { try read(from: url) }.value
}
static func loadBundled(in bundle: Bundle = .main) async throws -> Self {
guard let url = bundledURL(in: bundle) else { throw Failure.missing }
return try await load(from: url)
}
enum Failure: LocalizedError {
case missing, invalid(String), unsupported
var errorDescription: String? {
switch self {
case .missing: return "This build does not contain a Software Library catalog. Rebuild with the prepared catalog or install a build that includes it."
case .invalid(let reason): return "The Software Library catalog could not be read: \(reason). Replace the catalog with a newly prepared copy and rebuild the app. Your favorites and installed media are separate and have not been changed."
case .unsupported: return "This catalog uses an unsupported version. Install a matching VCC Plus build or rebuild with a compatible catalog."
}
}
}
private static func read(from url: URL) throws -> Self {
guard url.isFileURL, FileManager.default.fileExists(atPath: url.path) else { throw Failure.missing }
let db = try LibrarySQLite(url: url)
guard try db.rows("PRAGMA user_version").first?["user_version"] == "1" else { throw Failure.unsupported }
try db.execute("PRAGMA query_only=ON")
try db.execute("PRAGMA trusted_schema=OFF")
// Older macOS SQLite builds do not mark json_valid() innocuous, so
// executing the catalog's CHECK(json_valid(...)) during quick_check
// fails with trusted_schema=OFF. Skip schema CHECK expressions here;
// keep schema trust disabled and validate consumed JSON/byte sizes in
// Swift below. Physical, NOT NULL and foreign-key checks still run.
try db.execute("PRAGMA ignore_check_constraints=ON")
guard try db.rows("PRAGMA quick_check").first?.values.first == "ok" else { throw Failure.invalid("database integrity check failed") }
try db.execute("PRAGMA ignore_check_constraints=OFF")
guard try db.rows("PRAGMA foreign_key_check").isEmpty else { throw Failure.invalid("broken catalog relationships") }
var metadata: [String: String] = [:]
for row in try db.rows("SELECT key,value FROM metadata") { metadata[try row.required("key")] = try row.required("value") }
guard metadata["schema_version"] == "1", metadata["recipe_contract"] == "2" else { throw Failure.unsupported }
var assets: [String: [SoftwareLibraryAsset]] = [:]
let hasDelivery = !(try db.rows("SELECT name FROM sqlite_master WHERE type='table' AND name='asset_delivery'")).isEmpty
let assetSQL = hasDelivery
? "SELECT ra.release_id,ra.status,ra.reason,a.*,d.manual_url,d.thumbnail_url,d.thumbnail_sha256,d.thumbnail_byte_size FROM release_asset ra JOIN asset a ON a.id=ra.asset_id LEFT JOIN asset_delivery d ON d.asset_id=a.id ORDER BY COALESCE(d.priority,99),a.name,a.id"
: "SELECT ra.release_id,ra.status,ra.reason,a.* FROM release_asset ra JOIN asset a ON a.id=ra.asset_id ORDER BY a.kind,a.name,a.id"
for row in try db.rows(assetSQL) {
var asset = SoftwareLibraryAsset(id: try row.required("id"), name: try row.required("name"),
kind: try row.required("kind"), sourceURL: try row.webURL("source_url"), sha256: row["sha256"],
byteSize: row["byte_size"].flatMap(Int64.init), credit: try row.required("credit"),
matchStatus: try row.required("status"), matchReason: try row.required("reason"))
if row["manual_url"] != nil { asset.manualURL = try row.webURL("manual_url") }
if row["thumbnail_url"] != nil { asset.thumbnailURL = try row.webURL("thumbnail_url") }
asset.thumbnailSHA256 = row["thumbnail_sha256"]
asset.thumbnailByteSize = row["thumbnail_byte_size"].flatMap(Int64.init)
assets[try row.required("release_id"), default: []].append(asset)
}
var downloads: [String: [URL]] = [:]
for row in try db.rows("SELECT * FROM download_location ORDER BY priority,url") {
downloads[try row.required("package_sha256"), default: []].append(try row.webURL("url"))
}
var grouped: [String: [SoftwareLibraryRelease]] = [:]
var names: [String: (String, String)] = [:]
let query = """
SELECT r.*,t.name AS title_name,t.identity_status,p.byte_size,s.status,s.command,s.instructions,
s.configuration_json,s.selected_members_json,s.reasons_json,s.validation_json
FROM release r JOIN title t ON t.id=r.title_id JOIN package p ON p.sha256=r.package_sha256
JOIN setup s ON s.release_id=r.id ORDER BY r.name COLLATE NOCASE,r.id
"""
for row in try db.rows(query) {
let id = try row.required("id"), titleID = try row.required("title_id"), sha = try row.required("package_sha256")
guard sha.count == 64, sha.allSatisfy({ $0.isHexDigit }),
let bytes = row["byte_size"].flatMap(Int64.init), bytes >= 0 else { throw Failure.invalid("invalid package fingerprint") }
let config: LibraryJSON = try row.json("configuration_json")
let setup = SoftwareLibrarySetup(status: try row.required("status"), command: row["command"],
instructions: try row.required("instructions"), configuration: config,
selectedMembers: try row.json("selected_members_json"), reasons: try row.json("reasons_json"),
validation: try row.json("validation_json"))
let release = SoftwareLibraryRelease(id: id, titleID: titleID, name: try row.required("name"),
category: try row.required("category").trimmingCharacters(in: CharacterSet(charactersIn: "/")),
mediaType: try row.required("media_type"), contentRole: try row.required("content_role"),
sourceURL: try row.webURL("source_url"), modifiedAt: row["modified_at"],
modifiedPrecision: row["modified_precision"], modifiedTimezone: row["modified_timezone"],
packageSHA256: sha, byteSize: bytes, languageStatus: try row.required("language_status"),
metadata: try row.json("metadata_json"), setup: setup, assets: assets[id] ?? [], downloadURLs: downloads[sha] ?? [])
try release.validatePresentationMetadata()
grouped[titleID, default: []].append(release)
names[titleID] = (try row.required("title_name"), try row.required("identity_status"))
}
let storedCount = try db.rows("SELECT count(*) AS count FROM release").first?["count"].flatMap(Int.init)
guard storedCount == grouped.values.reduce(0, { $0 + $1.count }) else { throw Failure.invalid("a release is missing its setup or title") }
let titles = grouped.map { id, releases in
SoftwareLibraryTitle(id: id, name: names[id]!.0, identityStatus: names[id]!.1, releases: releases)
}.sorted { a, b in
let order = a.name.localizedStandardCompare(b.name)
return order == .orderedSame ? a.id < b.id : order == .orderedAscending
}
return Self(titles: titles, metadata: metadata)
}
}
struct SoftwareLibraryTitle: Identifiable, Codable, Sendable {
let id: String
let name: String
let identityStatus: String
let releases: [SoftwareLibraryRelease]
init(id: String, name: String, identityStatus: String, releases: [SoftwareLibraryRelease]) {
self.id = id; self.name = name; self.identityStatus = identityStatus
self.releases = Self.orderedOwnedEditions(releases)
}
var searchText: String { ([name] + releases.map(\.searchText)).joined(separator: " ") }
/// Archive edition ordering is curated independently. Only a wholly owned
/// title defaults to its newest dated edition; a user's saved choice still
/// takes precedence in SoftwareLibraryModel.selectedRelease.
private static func orderedOwnedEditions(_ releases: [SoftwareLibraryRelease]) -> [SoftwareLibraryRelease] {
guard releases.count > 1, releases.allSatisfy({ $0.ownedGame != nil }) else { return releases }
let dated = releases.enumerated().map { index, release in
let publication = release.metadata["owned_publication"]
let verified = publication["state"].string == "verified"
let version = verified ? release.ownedGameVersion.flatMap(calendarDate) : nil
let published = verified ? publication["verified_at"].string.flatMap(absoluteDate) : nil
return (index: index, release: release, edition: version ?? published, published: published)
}
return dated.sorted { first, second in
if first.edition != second.edition {
if let a = first.edition, let b = second.edition { return a > b }
return first.edition != nil
}
if first.published != second.published {
if let a = first.published, let b = second.published { return a > b }
return first.published != nil
}
return first.index < second.index
}.map(\.release)
}
private static func calendarDate(_ text: String) -> Date? {
guard text.range(of: #"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"#, options: .regularExpression) != nil else { return nil }
let formatter = DateFormatter()
formatter.locale = Locale(identifier: "en_US_POSIX")
formatter.calendar = Calendar(identifier: .gregorian)
formatter.timeZone = TimeZone(secondsFromGMT: 0)
formatter.dateFormat = "yyyy-MM-dd"; formatter.isLenient = false
guard let date = formatter.date(from: text), formatter.string(from: date) == text else { return nil }
return date
}
private static func absoluteDate(_ text: String) -> Date? {
// Require an explicit offset. Comparing raw ISO spellings would put
// 10:00+09:00 after 02:00Z even though it happened an hour earlier.
guard text.range(of: #"(?:Z|[+-][0-9]{2}:?[0-9]{2})$"#, options: .regularExpression) != nil else { return nil }
let formatter = ISO8601DateFormatter()
formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
if let date = formatter.date(from: text) { return date }
formatter.formatOptions = [.withInternetDateTime]
return formatter.date(from: text)
}
}
extension SoftwareLibraryTitle {
init(from decoder: Decoder) throws {
let values = try decoder.container(keyedBy: CodingKeys.self)
self.init(id: try values.decode(String.self, forKey: .id), name: try values.decode(String.self, forKey: .name),
identityStatus: try values.decode(String.self, forKey: .identityStatus),
releases: try values.decode([SoftwareLibraryRelease].self, forKey: .releases))
}
}
struct SoftwareLibraryRelease: Identifiable, Codable, Sendable {
let id: String
let titleID: String
let name: String
let category: String
let mediaType: String
let contentRole: String
let sourceURL: URL
let modifiedAt: String?
let modifiedPrecision: String?
let modifiedTimezone: String?
let packageSHA256: String
let byteSize: Int64
let languageStatus: String
let metadata: LibraryJSON
let setup: SoftwareLibrarySetup
let assets: [SoftwareLibraryAsset]
let downloadURLs: [URL]
// The full reviewed project-title intake record lives in metadata.owned_game.
// Catalog and companion decoding validate it before exposing a release.
var ownedGame: SoftwareLibraryOwnedGame? { try? SoftwareLibraryOwnedGame.parse(metadata["owned_game"]) }
var browseCategories: [String] {
ownedGame?.browseCategories ?? metadata["browse_categories"].strings
}
var primaryBrowseCategory: String? {
ownedGame?.primaryBrowseCategory ?? metadata["primary_browse_category"].string
}
var categoryFeatured: Bool {
if let ownedGame { return ownedGame.categoryFeatured }
if case .bool(let value) = metadata["category_featured"] { return value }
return false
}
var gettingStarted: Bool {
if let ownedGame { return ownedGame.gettingStarted }
if case .bool(let value) = metadata["getting_started"] { return value }
return false
}
var primaryManualAsset: SoftwareLibraryAsset? {
guard let ownedGame else { return assets.first(where: { $0.isManual && $0.manualURL != nil }) }
var asset = SoftwareLibraryAsset(id: "owned-manual:" + id, name: "Manual", kind: "manual",
sourceURL: ownedGame.projectURL, sha256: ownedGame.manualPDF.sha256, byteSize: ownedGame.manualPDF.byteSize,
credit: ownedGame.author, matchStatus: "project-owned", matchReason: "Published project manual")
asset.manualURL = ownedGame.manualPDF.url
return asset
}
func validatePresentationMetadata() throws {
if let owned = try SoftwareLibraryOwnedGame.parse(metadata["owned_game"]) {
guard mediaType == "disk", owned.gameID == titleID, owned.releaseID == id,
owned.package.sha256 == packageSHA256, owned.package.byteSize == byteSize,
setup.profile == "disk-basic", setup.ramKiB == owned.ramKiB, setup.processor == owned.processor,
setup.command == "DOS\r", setup.selectedMembers.array.count == 1,
owned.configuration.object.allSatisfy({ setup.configuration[$0.key] == $0.value }),
setup.selectedMembers.array.first?["path"].string == owned.diskPath,
setup.selectedMembers.array.first?["target"].string == "disk0" else {
throw SoftwareLibraryCatalog.Failure.invalid("project-owned metadata does not match this release's package/setup")
}
}
try SoftwareLibraryOwnedGame.validateBrowseMetadata(metadata, optional: true)
if metadata["related_archive"] != .null {
guard metadata["related_archive_contract"].integer == 1, case .array(let references) = metadata["related_archive"], references.count <= 100 else {
throw SoftwareLibraryCatalog.Failure.invalid("unsupported related Archive document contract")
}
let parsed = try references.map(SoftwareLibraryRelatedReference.parse)
guard Set(parsed.map(\.id)).count == parsed.count,
Set(parsed.map { $0.documentID + ":" + String($0.page ?? 0) }).count == parsed.count else {
throw SoftwareLibraryCatalog.Failure.invalid("duplicate related Archive document relationship")
}
}
}
var publisher: String? { metadata["publisher"].string }
var year: Int? { metadata["year"].integer }
var system: String { metadata["system"].string ?? "unknown" }
var videoModes: [String] { metadata["video_modes"].strings }
// These are catalog observations, not the launcher's generous defaults.
var environment: String { setup.configuration["browse_environment"].string ?? "unknown" }
var processorRequirement: String { setup.configuration["processor_requirement"].string ?? "unknown" }
var hardwareSupport: [String: String] {
setup.configuration["hardware_support"].object.compactMapValues(\.string)
}
var semigraphicsModes: [String] { videoModes.filter { $0 == "SG" || $0.hasPrefix("SG-") } }
var videoBadges: [String] {
videoModes.map { $0 + (metadata["video_scope"].string == "intro-only" ? " intro" : "") }
}
var mediaLabel: String {
switch mediaType {
case "cartridge": return "Cartridge"
case "cassette": return "Cassette"
case "disk": return "Disk"
case "hard-disk": return "Hard disk"
case "sdc": return "SDC SD card"
default: return mediaType
}
}
fileprivate var ownedGameVersion: String? {
guard ownedGame != nil, let value = metadata["owned_game"]["game_version"].string,
!value.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty, value.utf8.count <= 160,
!value.unicodeScalars.contains(where: CharacterSet.controlCharacters.contains) else { return nil }
return value
}
var editionLabel: String { mediaLabel + " — " + (ownedGameVersion ?? name) }
var searchText: String {
[name, category, mediaLabel, publisher ?? "", year.map(String.init) ?? "", system,
metadata["catalog_number"].string ?? "", videoModes.joined(separator: " "),
metadata["media_tags"].strings.joined(separator: " "), browseCategories.joined(separator: " "),
ownedGame?.author ?? "", setup.compatibilityNotes.joined(separator: " ")].joined(separator: " ")
}
}
/// Project-owned distribution metadata, never a source of executable host commands.
/// The native catalog stores the complete intake shape under metadata.owned_game;
/// only the fields below are consumed here. Publication remains a maintainer step.
struct SoftwareLibraryOwnedGame: Sendable, Equatable {
struct HostedFile: Codable, Sendable, Equatable {
let url: URL
let sha256: String
let byteSize: Int64
}
struct Source: Sendable, Equatable {
let package: HostedFile
let projectDirectory: String
let configurationFile: String
let entrySource: String
let licenseFiles: [String]
var companionPackages: [HostedFile] = []
var buildConfiguration: String? = nil
}
let gameID: String
let releaseID: String
let author: String
let license: String
let projectURL: URL
let onlineManualURL: URL
let manualPDF: HostedFile
let sourceRepositoryURL: URL
let source: Source
let gettingStarted: Bool
let categoryFeatured: Bool
let browseCategories: [String]
let primaryBrowseCategory: String
let firstPlayColdDOS: Bool
let diskPath: String
let diskSHA256: String
let diskByteSize: Int64
let package: HostedFile
let ramKiB: Int
let processor: String
let configuration: LibraryJSON
static let categoryNames: Set<String> = ["Applications", "Games", "Music", "Educational", "Demos", "Utilities",
"Programming", "Magazines", "Books", "Pictures", "Hardware", "Operating Systems", "Blank Media", "Other"]
static func categoryLabel(_ id: String) -> String { id == "Educational" ? "Education" : id }
private static func invalid(_ detail: String) -> SoftwareLibraryCatalog.Failure { .invalid("project-owned title: " + detail) }
private static func text(_ value: LibraryJSON, _ name: String) throws -> String {
guard let result = value.string, !result.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
result.utf8.count <= 4096,
!result.unicodeScalars.contains(where: CharacterSet.controlCharacters.contains) else { throw invalid("invalid " + name) }
return result
}
private static func flag(_ value: LibraryJSON, _ name: String) throws -> Bool {
guard case .bool(let result) = value else { throw invalid("invalid " + name) }
return result
}
static func validRelativePath(_ value: String) -> Bool {
let parts = value.split(separator: "/", omittingEmptySubsequences: false)
return !value.isEmpty && value.utf8.count <= 1024 && parts.count <= 32 &&
!value.contains("\\") && !value.contains(":") &&
!parts.contains(where: { $0.isEmpty || $0 == "." || $0 == ".." }) &&
value == value.precomposedStringWithCanonicalMapping &&
!value.unicodeScalars.contains(where: CharacterSet.controlCharacters.contains)
}
private static func relative(_ value: LibraryJSON, _ name: String) throws -> String {
let result = try text(value, name)
guard validRelativePath(result) else { throw invalid("unsafe " + name) }
return result
}
private static func web(_ value: LibraryJSON, _ name: String) throws -> URL {
let raw = try text(value, name)
guard !raw.contains("\\"), !raw.unicodeScalars.contains(where: CharacterSet.whitespacesAndNewlines.contains),
let url = URL(string: raw), url.scheme == "https", url.host?.isEmpty == false,
url.user == nil, url.password == nil, url.port == nil || url.port == 443,
!url.pathComponents.contains("."), !url.pathComponents.contains(".."),
!url.path.contains("\\"), !url.path.unicodeScalars.contains(where: CharacterSet.controlCharacters.contains) else {
throw invalid("invalid " + name)
}
return url
}
private static func fingerprint(_ value: LibraryJSON, _ maximum: Int64, _ name: String) throws -> (String, Int64) {
guard let sha = value["sha256"].string, sha.count == 64,
sha.allSatisfy({ "0123456789abcdef".contains($0) }),
let bytes = value["byte_size"].integer, bytes > 0, Int64(bytes) <= maximum else {
throw invalid("invalid " + name + " identity")
}
return (sha, Int64(bytes))
}
private static func hosted(_ value: LibraryJSON, prefix: String, ext: String,
maximum: Int64, name: String) throws -> HostedFile {
let url = try web(value["url"], name)
let (sha, bytes) = try fingerprint(value, maximum, name)
guard url.host == "vccplus.brianholman.com", url.query == nil, url.fragment == nil,
url.path.hasPrefix("/dl/software/CoCoLibrary/" + prefix), url.pathExtension.lowercased() == ext else {
throw invalid("unapproved " + name + " delivery area")
}
return HostedFile(url: url, sha256: sha, byteSize: bytes)
}
static func validateBrowseMetadata(_ value: LibraryJSON, optional: Bool) throws {
let categories = value["browse_categories"]
if optional && categories == .null {
guard value["primary_browse_category"] == .null else { throw invalid("primary category has no memberships") }
} else {
guard case .array(let values) = categories, !values.isEmpty, values.count <= 8,
values.allSatisfy({ $0.string.map(categoryNames.contains) == true }),
Set(values.compactMap(\.string)).count == values.count,
let primary = value["primary_browse_category"].string,
values.contains(.string(primary)) else { throw invalid("invalid browse categories") }
}
for key in ["category_featured", "getting_started"] where !optional || value[key] != .null {
_ = try flag(value[key], key)
}
}
static func parse(_ value: LibraryJSON) throws -> Self? {
guard value != .null else { return nil }
guard case .object = value, value["schema_version"].integer == 1,
value["provenance"]["kind"].string == "project-owned",
value["provenance"]["collection"].string == "vccplus-exclusive" else { throw invalid("unsupported metadata") }
try validateBrowseMetadata(value, optional: false)
let provenance = value["provenance"], links = value["links"], sourceValue = value["source"]
let gameID = try text(value["id"], "game ID"), releaseID = try text(value["release_id"], "release ID")
guard gameID.range(of: "^vccplus\\.[a-z0-9]+(?:-[a-z0-9]+)*$", options: .regularExpression) != nil,
releaseID.utf8.count <= 160 else { throw invalid("invalid stable identity") }
let projectDirectory = try relative(sourceValue["project_directory"], "project directory")
let configurationFile = try relative(sourceValue["configuration_file"], "project configuration")
let entrySource = try relative(sourceValue["entry_source"], "entry source")
guard configurationFile == projectDirectory + "/vccplus-project.json", entrySource.lowercased().hasSuffix(".c"),
case .array(let licenses) = sourceValue["license_files"], !licenses.isEmpty, licenses.count <= 32 else {
throw invalid("explicit project entry/configuration/licenses required")
}
let licenseFiles = try licenses.map { try relative($0, "license path") }
guard Set(licenseFiles).count == licenseFiles.count else { throw invalid("duplicate license path") }
var companionPackages: [HostedFile]
if sourceValue["companion_packages"] == .null { companionPackages = [] }
else {
guard case .array(let packages) = sourceValue["companion_packages"], packages.count <= 8 else {
throw invalid("invalid related source packages")
}
companionPackages = try packages.map {
try hosted($0, prefix: "Sources/Exclusives/", ext: "zip", maximum: 64 * 1024 * 1024, name: "related source")
}
guard Set(companionPackages.map(\.url)).count == companionPackages.count else { throw invalid("duplicate related source package") }
}
// Retained publication receipts use a separate source-offer descriptor.
if value["library_sources"] != .null {
let library = try hosted(value["library_sources"], prefix: "Sources/Exclusives/", ext: "zip",
maximum: 64 * 1024 * 1024, name: "corresponding library source")
if let existing = companionPackages.first(where: { $0.url == library.url }) {
guard existing == library else { throw invalid("conflicting related source identity") }
} else { companionPackages.append(library) }
}
let buildConfiguration = sourceValue["build_configuration"] == .null ? nil
: try text(sourceValue["build_configuration"], "source build configuration")
let online = try web(links["manual_online"], "online manual")
guard online.host == "vccplus.brianholman.com", online.path.hasPrefix("/games/") else { throw invalid("unapproved online manual") }
let disk = value["disk"], setup = value["setup"], config = setup["configuration"]
let path = try relative(disk["path"], "disk member")
let (diskSHA, diskBytes) = try fingerprint(disk, 16 * 1024 * 1024, "disk")
guard path.lowercased().hasSuffix(".dsk"), config["profile"].string == "disk-basic",
let ram = config["ram_kib"].integer, [128, 512, 2048, 8192].contains(ram),
let processor = config["processor"].string, ["6809", "6309"].contains(processor),
setup["selected_members"] == .array([.object(["path": .string(path), "target": .string("disk0")])]),
setup["command"].string == "DOS\r", value["first_play"]["mode"].string == "cold-restart-dos",
setup["validation"]["disk_sha256"].string == diskSHA,
let status = value["publication_status"].string, ["fixture-only", "pending-review", "approved"].contains(status),
let scope = setup["validation"]["scope"].string, ["fixture-only", "runtime-verified"].contains(scope),
status != "approved" || scope == "runtime-verified" else { throw invalid("invalid vetted first-Play recipe") }
return Self(gameID: gameID, releaseID: releaseID,
author: try text(provenance["author"], "author"), license: try text(provenance["license"], "license"),
projectURL: try web(provenance["project_url"], "project link"), onlineManualURL: online,
manualPDF: try hosted(links["manual_pdf"], prefix: "Documents/Manuals/Exclusives/", ext: "pdf", maximum: 512 * 1024 * 1024, name: "manual"),
sourceRepositoryURL: try web(links["source_repository"], "source repository"),
source: Source(package: try hosted(sourceValue["package"], prefix: "Sources/Exclusives/", ext: "zip", maximum: 64 * 1024 * 1024, name: "source"),
projectDirectory: projectDirectory, configurationFile: configurationFile, entrySource: entrySource,
licenseFiles: licenseFiles, companionPackages: companionPackages, buildConfiguration: buildConfiguration),
gettingStarted: try flag(value["getting_started"], "Getting Started"),
categoryFeatured: try flag(value["category_featured"], "curated category"),
browseCategories: value["browse_categories"].strings, primaryBrowseCategory: value["primary_browse_category"].string!,
firstPlayColdDOS: status == "approved" && scope == "runtime-verified",
diskPath: path, diskSHA256: diskSHA, diskByteSize: diskBytes,
package: try hosted(value["disk_package"], prefix: "Exclusives/", ext: "zip", maximum: 1_073_741_824, name: "disk package"),
ramKiB: ram, processor: processor, configuration: config)
}
}
extension SoftwareLibraryRelease {
// Companion snapshots must not silently turn malformed owned metadata back
// into an Archive record just because they bypass the SQLite loader.
init(from decoder: Decoder) throws {
let values = try decoder.container(keyedBy: CodingKeys.self)
self.init(id: try values.decode(String.self, forKey: .id), titleID: try values.decode(String.self, forKey: .titleID),
name: try values.decode(String.self, forKey: .name), category: try values.decode(String.self, forKey: .category),
mediaType: try values.decode(String.self, forKey: .mediaType), contentRole: try values.decode(String.self, forKey: .contentRole),
sourceURL: try values.decode(URL.self, forKey: .sourceURL), modifiedAt: try values.decodeIfPresent(String.self, forKey: .modifiedAt),
modifiedPrecision: try values.decodeIfPresent(String.self, forKey: .modifiedPrecision), modifiedTimezone: try values.decodeIfPresent(String.self, forKey: .modifiedTimezone),
packageSHA256: try values.decode(String.self, forKey: .packageSHA256), byteSize: try values.decode(Int64.self, forKey: .byteSize),
languageStatus: try values.decode(String.self, forKey: .languageStatus), metadata: try values.decode(LibraryJSON.self, forKey: .metadata),
setup: try values.decode(SoftwareLibrarySetup.self, forKey: .setup), assets: try values.decode([SoftwareLibraryAsset].self, forKey: .assets),
downloadURLs: try values.decode([URL].self, forKey: .downloadURLs))
try validatePresentationMetadata()
}
}
struct SoftwareLibrarySetup: Codable, Sendable {
let status: String
let command: String?
let instructions: String
let configuration: LibraryJSON
let selectedMembers: LibraryJSON
let reasons: [String]
let validation: LibraryJSON
var compatibilityNotes: [String] { configuration["compatibility_notes"].strings }
var configurationRequirements: [String] { configuration["configuration_requirements"].strings }
var profile: String? { configuration["profile"].string }
var processor: String? { configuration["processor"].string }
var ramKiB: Int? { configuration["ram_kib"].integer }
var controls: LibraryJSON { configuration["controls"] }
func controlDescription(_ key: String, source: String = "the Archive") -> String {
let value = controls[key]
if let text = value.string { return text }
let prefix = key.capitalized + " joystick: "
switch value["suggested_input"].string {
case "keyboard-joystick": return prefix + "keyboard control suggested by \(source)."
case "mouse-joystick": return prefix + "mouse control suggested by \(source)."
case "gamepad", "joystick": return prefix + "controller input suggested by \(source)."
default: return key.capitalized + " input is noted by \(source); check the available instructions."
}
}
var curationNote: String? { configuration["curation_note"].string }
var validationScope: String? { validation["scope"].string }
var statusLabel: String {
switch status {
case "source-ready": return "Archive-assisted loading"
case "inferred-ready": return "Inferred loading instructions"
case "spot-checked": return "VCC Plus spot-checked"
case "manual-setup": return "Manual setup"
default: return status
}
}
}
struct SoftwareLibraryAsset: Identifiable, Codable, Sendable {
let id: String
let name: String
let kind: String
let sourceURL: URL
let sha256: String?
let byteSize: Int64?
let credit: String
let matchStatus: String
let matchReason: String
var manualURL: URL? = nil
var thumbnailURL: URL? = nil
var thumbnailSHA256: String? = nil
var thumbnailByteSize: Int64? = nil
var isManual: Bool { kind == "manual" }
}
// Preserve optional and future metadata without translating unknown values into
// compatibility claims. Known display fields are exposed above as typed helpers.
indirect enum LibraryJSON: Codable, Sendable, Equatable {
case object([String: LibraryJSON]), array([LibraryJSON]), string(String), number(Double), bool(Bool), null
init(from decoder: Decoder) throws {
let value = try decoder.singleValueContainer()
if value.decodeNil() { self = .null }
else if let v = try? value.decode(Bool.self) { self = .bool(v) }
else if let v = try? value.decode(String.self) { self = .string(v) }
else if let v = try? value.decode(Double.self) { self = .number(v) }
else if let v = try? value.decode([String: LibraryJSON].self) { self = .object(v) }
else { self = .array(try value.decode([LibraryJSON].self)) }
}
func encode(to encoder: Encoder) throws {
var value = encoder.singleValueContainer()
switch self {
case .object(let v): try value.encode(v)
case .array(let v): try value.encode(v)
case .string(let v): try value.encode(v)
case .number(let v): try value.encode(v)
case .bool(let v): try value.encode(v)
case .null: try value.encodeNil()
}
}
subscript(_ key: String) -> Self { if case .object(let v) = self { return v[key] ?? .null }; return .null }
var string: String? { if case .string(let v) = self { return v }; return nil }
var integer: Int? { if case .number(let v) = self, v.isFinite, v >= Double(Int.min), v < Double(Int.max), v.rounded() == v { return Int(v) }; return nil }
var strings: [String] { if case .array(let v) = self { return v.compactMap(\.string) }; return [] }
var object: [String: Self] { if case .object(let v) = self { return v }; return [:] }
var array: [Self] { if case .array(let v) = self { return v }; return [] }
}
final class LibrarySQLite {
private var handle: OpaquePointer?
private let describeError: (String) -> Error
init(url: URL, cancellable: Bool = false,
describeError: @escaping (String) -> Error = { SoftwareLibraryCatalog.Failure.invalid($0) }) throws {
self.describeError = describeError
let result = sqlite3_open_v2(url.path, &handle, SQLITE_OPEN_READONLY | SQLITE_OPEN_NOMUTEX, nil)
guard result == SQLITE_OK else {
let reason = handle.map { String(cString: sqlite3_errmsg($0)) } ?? "cannot open database"
sqlite3_close(handle); handle = nil
throw describeError(reason)
}
if cancellable {
sqlite3_progress_handler(handle, 1024, { _ in Task.isCancelled ? 1 : 0 }, nil)
}
}
deinit { sqlite3_close(handle) }
func execute(_ sql: String) throws { _ = try rows(sql) }
func rows(_ sql: String, _ parameters: [String] = []) throws -> [[String: String]] {
var statement: OpaquePointer?
guard sqlite3_prepare_v2(handle, sql, -1, &statement, nil) == SQLITE_OK else { throw failure() }
defer { sqlite3_finalize(statement) }
for (index, value) in parameters.enumerated() {
let transient = unsafeBitCast(-1, to: sqlite3_destructor_type.self)
guard sqlite3_bind_text(statement, Int32(index + 1), value, -1, transient) == SQLITE_OK else { throw failure() }
}
var result: [[String: String]] = []
while true {
let status = sqlite3_step(statement)
if status == SQLITE_DONE { break }
if status == SQLITE_INTERRUPT { throw CancellationError() }
guard status == SQLITE_ROW else { throw failure() }
var row: [String: String] = [:]
for column in 0..<sqlite3_column_count(statement) where sqlite3_column_type(statement, column) != SQLITE_NULL {
guard let name = sqlite3_column_name(statement, column), let text = sqlite3_column_text(statement, column) else { continue }
row[String(cString: name)] = String(cString: text)
}
result.append(row)
}
return result
}
private func failure() -> Error { describeError(String(cString: sqlite3_errmsg(handle))) }
}
private extension Dictionary where Key == String, Value == String {
func required(_ key: String) throws -> String {
guard let value = self[key] else { throw SoftwareLibraryCatalog.Failure.invalid("missing \(key)") }
return value
}
func json<T: Decodable>(_ key: String) throws -> T {
do { return try JSONDecoder().decode(T.self, from: Data(try required(key).utf8)) }
catch { throw SoftwareLibraryCatalog.Failure.invalid("malformed \(key)") }
}
func webURL(_ key: String) throws -> URL {
guard let text = self[key], let value = URL(string: text),
["http", "https"].contains(value.scheme?.lowercased() ?? ""),
value.host != nil, value.user == nil, value.password == nil else {
throw SoftwareLibraryCatalog.Failure.invalid("invalid \(key)")
}
return value
}
}
/// Reviewed cross-library relationships are public metadata, never transport URLs.
struct SoftwareLibraryRelatedReference: Identifiable, Sendable {
let id: String
let title: String
let documentID: String
let sha256: String
let role: String
let page: Int?
let spoiler: Bool
let order: Int
static let roles = ["Guide", "Tutorial", "Reference", "Hints", "Walkthrough", "Solution", "Map"]
static func parse(_ json: LibraryJSON) throws -> Self {
guard let id = json["id"].string, !id.isEmpty, id.utf8.count <= 240,
let title = json["title"].string, !title.isEmpty, title.utf8.count <= 1000,
let document = json["document_id"].string, document.count == 64, document.allSatisfy(\.isHexDigit),
let sha = json["sha256"].string, sha == document,
let role = json["role"].string, roles.contains(role),
json["page"] == .null || (json["page"].integer ?? 0) > 0 else {
throw SoftwareLibraryCatalog.Failure.invalid("invalid related Archive document metadata")
}
return .init(id: id, title: title, documentID: document, sha256: sha, role: role,
page: json["page"].integer, spoiler: json["spoiler"] == .bool(true), order: json["order"].integer ?? 999)
}
}
extension SoftwareLibraryRelease {
var isDirectSubmission: Bool { metadata["origin"].string == "direct_submission" }
var isArchive: Bool { ownedGame == nil && !isPersonal && !isDirectSubmission }
var relatedArchiveReferences: [SoftwareLibraryRelatedReference] {
guard metadata["related_archive_contract"].integer == 1 else { return [] }
return metadata["related_archive"].array.compactMap { try? SoftwareLibraryRelatedReference.parse($0) }.sorted {
if $0.order != $1.order { return $0.order < $1.order }
let a = SoftwareLibraryRelatedReference.roles.firstIndex(of: $0.role) ?? 99
let b = SoftwareLibraryRelatedReference.roles.firstIndex(of: $1.role) ?? 99
if a != b { return a < b }
return $0.title.localizedStandardCompare($1.title) == .orderedAscending
}
}
}
extension SoftwareLibraryRelease {
var isPersonal: Bool { metadata["personal"] == .bool(true) && titleID.hasPrefix("personal:") }
}