Imported from travisg/files11 (AGENTS.md). Install upstream with npx skills add travisg/files11. Copyright stays with the author.

AI Agent Context: Files-11 ODS-2 Disk Image Parser

Purpose

This repository contains a Rust-based Files-11 ODS-2 Disk Image Parser. It is designed to read and interpret legacy disk images formatted with the ODS-2 (On-Disk Structure level 2) file system, which was the standard for DEC's OpenVMS and RSX-11M operating systems.

Current Capabilities (What is implemented)

As of the current state, the project is a "read-only" exploratory tool capable of the following:

• Mounting Images: Opens ODS-2 formatted disk image files.
• Volume Bootstrapping: Reads the Home Block (typically at Logical Block Number 1) to understand disk structure and locate the index file.
• Index File Parsing: Reads INDEXF.SYS directly from raw disk sectors to build the master table of files.
• Extent Mapping: Parses file headers and maps Virtual Block Numbers (VBNs) to physical Logical Block Numbers (LBNs) to handle fragmented files.
• Directory Traversal: Opens the Master File Directory (MFD, [000000]000000.DIR) and parses ODS-2 directory records to retrieve file names, version limits, and file IDs.
• Recursive Walking: Capable of recursively walking the entire volume's directory tree.
• Command Line Switches: Uses clap to support -h/--help manuals, -V/--version, -v/--verbose detailed metadata reporting, and -m/--map physical disk layout mapping.
• Disk LBN Mapping: Outputs a sorted physical LBN block layout map showing where files, directories, Home Blocks, and bitmaps are physically placed on disk.
• Version Suffix Formatting: Appends VMS-standard version number suffixes (;version, e.g. ;1) to file and directory paths during listing and mapping.
• Robust I/O Pipe Handling: Employs a shadowed println! macro to gracefully handle standard Unix BrokenPipe signals (e.g. when output is piped to head or less and terminated early).
• Unit Testing: Includes unit tests covering File ID formatting, File Record Attribute swizzling, and FileIdent name whitespace trimming.

Architecture & Code Map

• src/main.rs: Entry point. Mounts an ODS-2 disk image and manages CLI/bootstrap orchestration.
• src/recurse.rs: Traversal helper module. Contains the directory recursion (recurse_directory) and LBN map printing (print_lbn_disk_map) logic.
• src/lib.rs: Library root.
• src/ods2.rs: Contains the core packed structs representing the on-disk binary structures of the ODS-2 format (e.g., HomeBlock, FileId, FileHeader, FileIdent, DirHeader).
• src/file.rs: Implements file and directory parsing logic. Handles parsing file headers, translating VBNs to LBNs, and parsing directory entries.
• src/disk.rs: Low-level disk/file I/O operations.

Known Limitations & Roadmap for Future Agents

When contributing to this repository, be aware of the following missing features:

• No Data Extraction: Code exists to walk directories and map blocks, but there is no logic to extract file payloads and write them to the host OS.
• Read-Only: No write support exists (no modifying files, adding files, or generating images).
• Image Files Only: Does not support reading from raw block devices directly.
• Strictly ODS-2: No support for ODS-1 or ODS-5 variants.

Development Guidelines for Contributed Agents

When adding new code or modifying existing logic, always adhere to the following rules:

1. Write Unit Tests: Always attempt to add unit tests for new logic (such as binary swizzling, parsing, formatting, or helper functions) to prevent regressions.
2. Format Code: Ensure that a formatter (i.e. cargo fmt) is run on the entire codebase before creating commits or submitting code changes.