/aminet-mirror

name: aminet-mirror
description: "Selective Aminet package mirroring: single-package fetch, integrity verification, mirror state tracking, bulk download, and sync detection. Use when downloading, verifying, or managing mirrored packages."
metadata:
  extensions:
    gsd-skill-creator:
      triggers:
        intents:
          - "aminet.*fetch"
          - "aminet.*download"
          - "mirror.*state"
          - "integrity.*verif"
        files:
          - "src/aminet/package-fetcher.ts"
          - "src/aminet/mirror-state.ts"
          - "src/aminet/integrity.ts"
          - "src/aminet/bulk-downloader.ts"
          - "src/aminet/sync-detector.ts"
        contexts:
          - "aminet mirroring"
          - "package download"
        threshold: 0.7
      token_budget: "1.0%"
      version: 1
      enabled: true
      plan_origin: "242-aminet-integration"
      phase_origin: "242"

Aminet Mirror

Purpose

Manages selective mirroring of Aminet packages to the local filesystem. Handles single-package fetching with ordered mirror fallback, SHA-256 integrity verification, persistent mirror state tracking with 7-state status enum, concurrent bulk downloads with rate limiting, and sync detection comparing local state against the INDEX.

Capabilities

• Single-package fetch with ordered mirror fallback
• Directory hierarchy preservation matching Aminet structure
• Non-fatal .readme download (best-effort alongside archive)
• User-Agent header on all HTTP requests
• SHA-256 integrity verification via node:crypto
• Size verification with +/-1 KB tolerance for Aminet metadata rounding
• Combined integrity result (hash + size) in single check
• 7-state PackageStatus enum tracking full lifecycle
• Atomic write-then-rename for mirror state persistence
• Immutable updateEntry pattern for safe concurrent access
• Bulk download with async semaphore concurrency control
• Global rate limiting gate between requests
• Resume from interruption (skips already-mirrored packages)
• Serialized state writes via Promise chain mutex
• Sync detection comparing mirror state vs INDEX by sizeKb
• O(1) Map lookup for efficient change detection
• Only change-eligible statuses compared (mirrored+)

Key Modules

| Module | Purpose | |--------|---------| | `src/aminet/package-fetcher.ts` | Single-package fetch with ordered mirror fallback and .readme | | `src/aminet/mirror-state.ts` | 7-state status enum, atomic persistence, immutable updateEntry | | `src/aminet/integrity.ts` | SHA-256 hash and size verification with combined IntegrityResult | | `src/aminet/bulk-downloader.ts` | Concurrent downloads with semaphore, rate limiting, resume support | | `src/aminet/sync-detector.ts` | Detects INDEX changes against local mirror state via Map lookup |

Usage Examples

**Fetch a single package:**

import { fetchPackage } from './package-fetcher.js';

const result = await fetchPackage({
  entry: indexEntry,
  mirrors: ['https://aminet.net', 'https://de.aminet.net'],
  outputDir: './mirror',
});
// Downloads archive + .readme, preserves directory structure

**Verify integrity:**

import { verifyIntegrity } from './integrity.js';

const result = await verifyIntegrity(filePath, { expectedSha256: hash, expectedSizeKb: 42 });
// result.valid, result.hashMatch, result.sizeMatch

**Bulk download with concurrency:**

import { bulkDownload } from './bulk-downloader.js';

await bulkDownload({
  entries: selectedPackages,
  mirrors,
  outputDir: './mirror',
  concurrency: 4,
  rateLimit: 500, // ms between requests
  onProgress: (completed, total) => console.log(`${completed}/${total}`),
});

**Detect sync changes:**

import { detectChanges } from './sync-detector.js';

const changes = detectChanges(mirrorState, currentIndex);
// changes: { added: [], updated: [], removed: [] }

Dependencies

• Node.js `node:crypto` for SHA-256 hashing
• Node.js `node:fs` for mirror state persistence and file I/O
• HTTP client for mirror downloads
• Aminet mirror network (ordered fallback list)

Token Budget Rationale

1.0% budget reflects the 5 modules covering fetch, state, integrity, bulk download, and sync detection. The concurrency control, rate limiting, and atomic state persistence patterns require moderate context for safe operation.