Pandora

A lightning-fast package manager for AtlasLinux

High-level design

On-disk layout and activation model

• Root paths
  • Store root: $HOME/pandora/store — immutable package contents, one directory per package version named as name@version.
  • Active virtual tree: $HOME/pandora/vir — canonical tree containing bin, lib, etcetera for the active profile.
  • Profiles: $HOME/pandora/profiles/ — symlink forest entries that point into store entries.
  • Manifests: $HOME/pandora/manifests — package metadata and lockfiles.
  • Temp and caches: $HOME/pandora/tmp and $HOME/pandora/cache.
• User-visible paths
  • $HOME/bin, $HOME/lib, $HOME/etcetera — each is a symlink into $HOME/pandora/vir/bin etcetera so user workflows remain natural.
• Package directory naming
  • store///files...
  • store///manifest.acl (canonical metadata)
• Symlink forest rules
  • Each profile directory contains symlinks that mirror filesystem layout (bin, lib, etcetera) but point to specific versioned files in store. Switching a package version updates the profile symlinks only.
• Co-installability
  • All versions of a package are retained in store. The active profile decides which version’s files are reachable through $HOME/bin etcetera.

---

Package metadata, format and reproducibility

• .pkg contents
  • Deterministic archive produced by your custom packer. Must contain:
    • manifest.acl with required fields: name, version, architecture, authors, license, dependencies (exact versions), install hooks, build metadata, SHA256 of archive.
    • file tree under ./files matching final filesystem layout.
    • optional build provenance metadata generated by MPT.
• Manifest semantics
  • Dependencies are exact version pins only. No ranges. Dependencies list is authoritative for resolution.
• Reproducible builds
  • MPT integrates to emit deterministic artifacts and build metadata. Pandora will verify artifact SHA256 against manifest and can additionally verify build provenance metadata if present.
• Signature model
  • Package-level SHA256 required. Optional additional detached signatures supported by the signing tool you made. Pandora verifies SHA256 by default; signature verification is configurable per registry.

---

Registry protocol and discovery

• Registry model
  • Registries are HTTP(s) endpoints serving ACL indices and .pkg blobs. Client reads registry ACL index to discover packages and versions.
• Registry configuration
  • $HOME/pandora/registries.acl lists registries with priorities and per-registry flags (require-signatures, allow-publish, cache-policy).
• Fetch behavior
  • On install request, Pandora queries registries in priority order for the requested package@version; downloads .pkg; verifies SHA256; stores under store//.
• Sync and pruning
  • Support on-demand fetch only. Local cache stores downloaded blobs. Pruning policy: user-configurable TTL and explicit prune command to remove unreferenced versions.
• Search and index
  • Registry index supports package metadata and simple search by name and tags. Client-side search queries index endpoints.

---

CLI surface and UX

• Command style
  • Git-like subcommands, human output only, colorized progress bars. No JSON output.
• Primary commands
  • pandora install @ — fetch, verify, unpack to store; prompts to link into active profile unless --no-activate.
  • pandora activate @ — switch symlinks in current profile to point to that version.
  • pandora remove @ — unlink from profile and optionally delete from store with confirm.
  • pandora list [--installed|--store|--remote] — human-readable lists.
  • pandora search — registry search across configured registries.
  • pandora build — run MPT build in sandbox and produce .pkg.
  • pandora publish --registry — upload package to registry if registry permits.
  • pandora profile create|switch|delete — manage profiles.
  • pandora info @ — show manifest, provenance, dependencies.
  • pandora graph @ — show human-friendly dependency graph and suggested fixes for missing deps.
  • pandora verify @ — verify SHA256 and optional signature.
  • pandora prune — remove unreferenced cached blobs.
  • pandora metrics — displays public metrics aggregated from registries and local install stats.
• Interactive prompts
  • Minimal, clear yes/no prompts for actions like activation on install or deletion of versions. A global --yes flag for scripting.
• Error reporting
  • Solver explanation prints minimal graph with colored highlights and an exact action suggestion such as "activate X@v or install Y@v".

---

Dependency solver, profiles and lockfiles

• Solver rules
  • Deterministic, greedy solver for exact pins. If dependencies are not satisfied, Pandora reports missing packages with exact commands to install them.
• Lockfiles
  • Pandora writes a manifest lockfile per profile at $HOME/pandora/manifests/.lock listing resolved package@version entries and checksums to guarantee reproducible profile rebuilds.
• Shadowing and file conflicts
  • On activation, if multiple active packages would create the same relative path in vir, Pandora reports a conflict and refuses activation until user chooses an override strategy: prefer new, prefer existing, or create namespaced install (e.g., bin/pkgname-version/).
• Optional overrides
  • Users can create path-level overrides in profile metadata to control resolution behavior.

---

Security, build sandboxing and policies

• Privilege model
  • All operations run with user privileges within $HOME. No system-wide changes. Root only if run as root.
• Verification
  • SHA256 verification is mandatory on download. Signature verification is configurable per-registry and can be enabled by default for the default registry.
• Sandboxing
  • Builds and install hook execution run inside unprivileged user namespaces using Linux namespaces and seccomp where available to limit effects to $HOME. MPT integration uses the same sandbox to produce deterministic outputs.
• Trust and registries
  • Registries are configured by users; Pandora does not enforce a single trust root. Users may opt to require registry-level metadata signed by a known key.

---

Built-in build pipeline with MPT

• Build flow
  • pandora build invokes MPT inside an isolated build sandbox, produces deterministic package artifacts and writes build metadata and SBOM.
• Outputs
  • .pkg archive, manifest.acl with build provenance, and SBOM in standard format stored alongside package in store and optionally published.
• Caches
  • Build cache is per-user under $HOME/pandora/cache; optional export/import for CI to share caches.

---

Metrics, deprecation and FOSS model

• Metrics
  • Pandora collects only local install/publish events for display and optional user opt-in reporting to registries. Registries publish aggregate public metrics (installs, downloads, publishes) that Pandora can fetch for display.
• Deprecation
  • Packages may be marked deprecated in registry indices. Pandora will print warnings on install/activate but will not block or remove packages.
• Licenses
  • License is stored in manifest and displayed but not enforced.

---

MVP roadmap and milestones

1. Core fetch and verify
   • Implement registry ACL index parsing, secure download, SHA256 verification, unpack to store.
2. Per-user store and activation
   • Implement store layout, symlink forest, profile create/switch, user-visible $HOME/bin linking.
3. CLI surface
   • Implement install, activate, remove, list, search, info, verify, basic error messages, colored progress.
4. Basic build integration
   • Integrate MPT to produce .pkg and manifest; sandboxed build invocation.
5. Lockfiles and graph
   • Implement profile lockfiles and human-readable dependency graph with suggested fixes.
6. Extras
   • Prune, publish, advanced conflict strategies, optional signature verification, metrics display.

• Priority for first deliverable
  • Steps 1–3 completed to get a working experience of download → verify → install → activate.

---

Developer notes and implementation suggestions

• Use atomic rename operations when linking into vir to avoid transient inconsistent states.
• Keep manifests immutable once the .pkg is published; support publish with content-addressed SHA256 storage to avoid duplication.
• Keep the ACL parser as a central library used by both client and registry tooling.
• Expose a machine-readable log for CI (plain text machine-friendly lines) even if no JSON output is supported.
• Add comprehensive tests for reproducibility and SHA256 verification.