PackGuard

Safety-first manifest sync toolkit for Minecraft modpack maintainers.

v0.1.0-alpha.0 is an alpha. PackGuard is not production-ready yet.

Quickstart

Run the full local alpha gate:

pnpm install
pnpm run release:check

Run the local fake end-to-end tester kit:

pnpm run example:e2e:run

Run the built CLI:

pnpm run cli:build
node packages/cli/dist/index.js --help
node packages/cli/dist/index.js manifest validate examples/read-only-basic/manifest.json
node packages/cli/dist/index.js plan --manifest examples/read-only-basic/manifest.json --target examples/read-only-basic/target

What PackGuard Is

PackGuard is intended to turn an untrusted modpack manifest into a validated, auditable, reversible filesystem sync transaction.

It is being built for Minecraft modpack maintainers who want a deterministic CLI workflow for validating releases, inspecting planned changes, applying updates with backups, and rolling back a bad transaction.

The current repository is a pnpm workspace:

packages/core      Shared safety engine and sync model
packages/cli       Canonical maintainer interface for v0.1
packages/desktop   Preserved legacy Electron prototype

What PackGuard Is Not

PackGuard is not:

• a Minecraft launcher
• a Minecraft account manager
• a mod hosting platform
• a modpack registry
• a CurseForge or Modrinth replacement
• a malware scanner
• a license bypass tool
• an automatic latest-version updater
• a cloud distribution service
• a SaaS product

PackGuard does not make mods safe. Hash verification proves file integrity relative to a manifest; it does not prove that a mod is safe, legal, or trustworthy.

Current Alpha Capabilities

The CLI/core workflow for v0.1.0-alpha.0 supports:

• manifest v1 validation and source policy checks
• target path safety APIs for traversal, absolute path, Windows drive path, UNC path, and duplicate normalized target rejection
• read-only scanning for mods/**/*.jar
• dry-run planning before target mutation
• guarded apply with --yes
• verified cache use, size checks where metadata is present, and SHA-512 verification
• backup-before-replace for wrong-hash files
• transaction journals for apply
• guarded rollback with --yes
• rollback safety backups and rollback journals
• read-only status, doctor, transaction, rollback, and backup inspection
• human-readable output, --json output for supported commands, and stable documented exit codes
• a local fake E2E tester kit using tiny .jar text fixtures and no network

The preserved desktop app remains a legacy/experimental prototype. It is not the source of truth for the sync model.

Safety Model

PackGuard is built around one principle:

Synchronizing a modpack is a filesystem mutation. Filesystem mutations must be validated, auditable, and reversible.

The implemented alpha safety model includes:

• manifests are validated before use
• default source policy allows https:// and rejects http://, file://, and unsupported protocols
• unsafe local or insecure sources require explicit flags
• manifest target paths are target-relative and pass through core path validation
• dry-run commands do not mutate the target
• apply and rollback require explicit --yes
• downloaded or cached files are verified against manifest SHA-512 hashes before apply
• replacements are backed up before mutation
• apply and rollback write local journals under .packguard
• rollback protects current state with rollback safety backups where needed
• extra files are skipped by default, not deleted

PackGuard verifies file integrity against manifest hashes and records local sync activity. It does not certify mod safety, legality, provenance, or trustworthiness.

CLI Quickstart

From the repository root:

pnpm install
pnpm run cli:build

Useful commands:

node packages/cli/dist/index.js --help
node packages/cli/dist/index.js --version
node packages/cli/dist/index.js manifest validate <manifest>
node packages/cli/dist/index.js scan --target <folder>
node packages/cli/dist/index.js plan --manifest <file> --target <folder>
node packages/cli/dist/index.js apply --manifest <file> --target <folder>
node packages/cli/dist/index.js apply --manifest <file> --target <folder> --yes
node packages/cli/dist/index.js transactions list --target <folder>
node packages/cli/dist/index.js transactions show --target <folder> --transaction <id>
node packages/cli/dist/index.js status --target <folder>
node packages/cli/dist/index.js doctor --target <folder>
node packages/cli/dist/index.js rollbacks list --target <folder>
node packages/cli/dist/index.js rollbacks show --target <folder> --rollback <id>
node packages/cli/dist/index.js backups list --target <folder>
node packages/cli/dist/index.js rollback --target <folder> --transaction <id>
node packages/cli/dist/index.js rollback --target <folder> --transaction <id> --yes

apply and rollback are dry-run by default. They mutate only when --yes is provided.

See docs/CLI.md for command details, JSON output, exit codes, and intentionally unimplemented scope.

E2E Tester Kit

The fake E2E tester kit exercises the implemented CLI/core flow without real mods or network access:

pnpm run example:e2e:run

It resets examples/e2e-apply-rollback, updates local fixture hashes and file:// sources, runs validate, scan, plan, dry-run apply, guarded apply, transaction/status/doctor/backup inspection, dry-run rollback, guarded rollback, and final-state checks.

All .jar files in the tester kit are tiny text fixtures. They are not real Minecraft mods and are not intended for Minecraft.

See docs/TESTER_KIT.md.

Release Check

Run the combined local alpha gate:

pnpm run release:check

It runs:

pnpm run typecheck
pnpm run test
pnpm run cli:build
pnpm run cli:smoke
pnpm run example:e2e:run
pnpm run check:docs
pnpm run check:no-real-mods
pnpm run cli:pack

cli:pack creates a local package tarball under packages/cli for inspection. The tarball is ignored by .gitignore and must not be committed.

See docs/RELEASE_CHECKLIST.md.

Known Limitations

• v0.1.0-alpha.0 is not production-ready.
• Desktop reattachment to the core engine is not implemented.
• The preserved desktop app is still a legacy/experimental prototype.
• Backup-id rollback is not implemented.
• Cache maintenance commands are not implemented.
• Extra files are skipped by default; disabling or moving extras is not implemented.
• Apply support is intentionally limited to Minecraft mods/*.jar.
• Config, resource pack, shader pack, and arbitrary file sync are not implemented.
• Symlink hardening remains an area for future work and should not be overclaimed.
• The CLI currently supports local manifest files, not a full remote release workflow.
• Repository metadata is intentionally not set in package manifests until the maintainer chooses the final public repository URL.

Development

Install dependencies:

pnpm install

Run common checks:

pnpm run typecheck
pnpm run test
pnpm run cli:build
pnpm run cli:smoke
pnpm run example:e2e:run
pnpm run check:no-real-mods

Start the preserved desktop prototype:

pnpm run desktop:dev

Generated artifacts, package tarballs, real mod .jar files, personal pack data, .env files, local databases, and machine-specific paths must not be committed.

See CONTRIBUTING.md.

Legal Note

PackGuard does not provide, host, mirror, or redistribute Minecraft mods.

Pack maintainers are responsible for ensuring they have the right to distribute every file referenced by their manifests. Manifest license metadata can document maintainer intent, but it does not grant redistribution rights.

Important Docs

• Architecture
• Roadmap
• Security Policy
• Contributing
• CLI
• Tester Kit
• Release Checklist
• GitHub Readiness
• Issue Starter List
• Docs Index
• Manifest v1
• Target Jail
• Plan Model
• Verified Cache
• Apply Model
• Rollback Model
• Doctor Model
• Transaction Journal
• v0.1.0-alpha.0 Release Notes Draft