Skip to content

AGENTS.md

Latest commit

 

History

History
74 lines (54 loc) · 4.06 KB

AGENTS.md

File metadata and controls

74 lines (54 loc) · 4.06 KB
Raw

Reliquary Agent Context

This file serves as the single point of truth for AI agents working on the Reliquary project.

Project

  • Goal: Physical media preservation — track collections, manage capture/extraction, record provenance.
  • Repository: TwoWells/Reliquary on GitHub.
  • License: AGPL-3.0-or-later with commercial license option.

Rust workspace. The library crate produces data. CLI/TUI/web crates own presentation and interaction.

Coding Standards

  • Edition: Rust 2024.
  • Safety: unsafe code is strictly forbidden (forbid(unsafe_code)).
  • Error Handling: Use anyhow for application logic and thiserror for library errors.
  • Strict Denials: Do NOT use unwrap(), panic!(), todo!(), unimplemented!(), dbg!(), println!(), or eprintln!(). Use proper error handling and the tracing crate for logging. expect() is denied in production code but allowed in #[cfg(test)] modules — prefer expect("reason") over anyhow workarounds in tests.
  • Assertions: All assert!(), assert_eq!(), and assert_ne!() calls must include a message explaining what failed.
  • Imports: No wildcard imports (use crate::*).
  • Formatting: Code must be formatted with rustfmt.
  • Linting: Must pass cargo clippy with pedantic, nursery, and cargo groups enabled. Every #[allow(...)] must include a reason string.

Commit Convention

  • Format: Conventional Commits (enforced by commit-msg hook).
  • Pattern: type(scope): description or type: description
  • Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
  • Breaking changes: append ! before colon, e.g. feat(api)!: remove legacy endpoint
  • Examples:
    • feat(aacs): add AACS decryption module
    • fix(cli): correct VUK hex parsing
    • test(clpi): add multi-program parser test
    • chore: bump version to 0.2.0

Quality Standards

  • License Compliance: All new dependencies MUST have permissive licenses (MIT, Apache-2.0, etc.) as specified in @./deny.toml. Reliquary is dual-licensed under AGPL-3.0-or-later and a commercial license.
  • Copyright Headers: Every .rs file must start with the SPDX header (enforced by pre-commit hook): 
    // SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright (C) 2026 Two Wells <contact@twowells.dev>
  • Documentation: All public APIs must have documentation comments.
  • Testing: All new features must include tests.

Sensitive Data

This is a public repository. Two classes of data must never appear in it — not in code, comments, tests, or commit messages:

  • AACS VUKs and disc IDs. These are decryption keys/identifiers. Never hardcode a real VUK (32 hex chars, optionally 0x-prefixed) or disc ID; pass keys at runtime (--vuk) or via a gitignored file. A pre-commit hook blocks VUK-shaped values — for synthetic test vectors use the all-zero placeholder or mark the line vuk-allow.
  • Real disc / movie titles. They reveal a private physical collection. Use generic descriptors instead — e.g. "a WB Blu-ray title", "a DVD title", "WB animated series". Name test fixtures and comments by what they exercise (codec, structure), not by the source disc.

Setup

  • First time: make setup — configures git hooks and checks for required cargo tools.
  • Required tools: cargo-deny, cargo-machete, cargo-nextest, cargo-semver-checks, cargo-mutants.
  • Install tools: cargo binstall cargo-deny cargo-machete cargo-nextest cargo-semver-checks cargo-mutants

Development Commands

  • Check (full): make check — format, lint, deny, machete, and test in one pass.
  • Test (all): make test
  • Test (filtered): make test T=<filter>
  • Test (repeat): make test T=<filter> N=<count>

Release Workflow

  • Patch Release: make release-patch
  • Minor Release: make release-minor
  • Major Release: make release-major
  • Custom Version: make release V=x.y.z

Release runs: check → semver-checks → mutation tests (library crate) → commit → tag.