feat: add attested and downloads fields to File/Package types

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-audio-stack/core",
-  "version": "0.1.54",
+  "version": "0.1.55",
   "description": "Open-source audio plugin management software",
   "type": "module",
   "main": "./build/index.js",

src/classes/Package.ts

@@ -73,11 +73,26 @@ export class Package extends Base {
     return Array.from(this.versions.keys()).sort(semver.rcompare)[0] || '0.0.0';
   }
 
+  // Rollup across every published version's own downloads rollup (itself a sum of that
+  // version's files) - i.e. total downloads for this package, all-time. Pure aggregation over
+  // whatever `downloads` values are already present; does not fetch anything itself.
+  getTotalDownloads(): number {
+    let total = 0;
+    for (const [, pkgVersion] of this.versions) {
+      total += pkgVersion.downloads || 0;
+    }
+    return total;
+  }
+
   toJSON() {
+    const totalDownloads = this.getTotalDownloads();
     return {
       slug: this.slug,
       version: this.version,
       versions: Object.fromEntries(this.versions),
+      // Omit rather than write `downloads: 0` - keeps generated JSON smaller, and "0" wouldn't
+      // distinguish "genuinely zero downloads" from "not fetched yet" anyway.
+      ...(totalDownloads > 0 && { downloads: totalDownloads }),
     };
   }
 }

src/helpers/package.ts

@@ -55,6 +55,13 @@ export function packageVersionLatest(pkg: PackageInterface) {
   return Array.from(Object.keys(pkg.versions)).sort(semver.rcompare)[0] || '0.0.0';
 }
 
+// Sums files[].downloads for a single version - pure aggregation, no network access. Callers
+// that have populated each file's `downloads` from an external source (e.g. the registry's
+// build-time GitHub fetch) use this to set the version-level rollup before export.
+export function packageDownloadsTotal(pkgVersion: PackageVersion): number {
+  return pkgVersion.files.reduce((total, file) => total + (file.downloads || 0), 0);
+}
+
 // This is a first version using zod library for validation.
 // If it works well, consider updating all types to infer from Zod objects.
 // This will remove duplication of code between types and validators.
@@ -67,6 +74,8 @@ export const PackageSystemValidator = z.object({
 
 export const PackageFileValidator = z.object({
   architectures: z.nativeEnum(Architecture).array().min(1).max(Object.keys(Architecture).length),
+  attested: z.boolean().optional(),
+  downloads: z.number().min(0).optional(),
   sha256: z.string().length(64),
   size: z.number().min(8).max(9999999999),
   systems: PackageSystemValidator.array().min(1).max(Object.keys(SystemType).length),

src/types/File.ts

@@ -4,6 +4,15 @@ import { System } from './System.js';
 
 export interface FileInterface {
   architectures: Architecture[];
+  // Whether this exact file (identified by its sha256) has a GitHub Artifact Attestation
+  // linking it back to the CI run/commit that built it. Computed once at import time (the
+  // hash/url/release this is tied to never changes for a published version), not recomputed
+  // on every build - see registry/src/fetch.ts.
+  attested?: boolean;
+  // Cumulative download count for this exact file, sourced from the GitHub Releases API.
+  // Recomputed at registry build time (unlike attested, this changes continuously) - see
+  // registry/src/downloads.ts. Not authored/committed metadata.
+  downloads?: number;
   open?: string;
   sha256: string;
   size: number;

src/types/Package.ts

@@ -8,6 +8,10 @@ export interface PackageInterface {
   slug: string;
   version: string;
   versions: PackageVersions;
+  // Rollup of every version's `downloads` (itself a rollup of that version's files) - i.e.
+  // total downloads across all published versions of this package, all-time. Computed by
+  // Package.getTotalDownloads(), not authored/committed data.
+  downloads?: number;
 }
 
 export interface PackageVersions {
@@ -21,6 +25,9 @@ export interface PackageBase {
   date: string;
   description: string;
   donate?: string;
+  // Rollup of this version's files[].downloads (sum across all files for this release).
+  // Computed at registry build time - see packageDownloadsTotal() and downloads.ts.
+  downloads?: number;
   image: string;
   installed?: boolean;
   license: License;

tests/classes/Package.test.ts

@@ -59,6 +59,14 @@ test('Package latest version', () => {
   expect(pkg.latestVersion()).toEqual('3.2.1');
 });
 
+test('Package total downloads rolls up across versions', () => {
+  const pkg = new Package(PLUGIN_PACKAGE.slug);
+  pkg.addVersion('1.3.0', { ...PLUGIN, downloads: 100 });
+  pkg.addVersion(PLUGIN_PACKAGE.version, { ...PLUGIN, downloads: 250 });
+  expect(pkg.getTotalDownloads()).toEqual(350);
+  expect((pkg.toJSON() as PackageInterface).downloads).toEqual(350);
+});
+
 test('Package get version or latest', () => {
   const PLUGIN_V2: PackageVersion = structuredClone(PLUGIN);
   PLUGIN_V2.name = 'Plugin V2';

tests/helpers/package.test.ts

@@ -1,6 +1,7 @@
 import { expect, test } from 'vitest';
 import {
   packageCompatibleFiles,
+  packageDownloadsTotal,
   packageRecommendations,
   packageVersionLatest,
   PackageVersionValidator,
@@ -15,6 +16,19 @@ test('Package version latest', () => {
   expect(packageVersionLatest(PLUGIN_PACKAGE_MULTIPLE)).toEqual('1.3.2');
 });
 
+test('Package downloads total sums across files', () => {
+  const pluginWithDownloads: PackageVersion = {
+    ...PLUGIN,
+    files: PLUGIN.files.map((file, index) => ({ ...file, downloads: index === 0 ? undefined : (index + 1) * 10 })),
+  };
+  // files[0].downloads left undefined - missing/not-yet-fetched data must count as 0, not NaN.
+  expect(packageDownloadsTotal(pluginWithDownloads)).toEqual(20 + 30 + 40 + 50);
+});
+
+test('Package downloads total is zero when no files have downloads', () => {
+  expect(packageDownloadsTotal(PLUGIN)).toEqual(0);
+});
+
 test('Package recommendations pass', () => {
   expect(packageRecommendations(PLUGIN)).toEqual([
     {