// 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) } 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 = ["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.. 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(_ 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 } }