Merge feature/max-inf: complete .inf sidecar support (v0.9.0)

Full access byte, directory .inf, CRC16/CRC32, flat extraction
layout as default, robust parser with warnings, real-world smoke
tests.

Author: acscpt

CHANGELOG.md

@@ -5,6 +5,96 @@ All notable changes to this project will be documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.9.0] - 2026-04-13
+
+### Added
+
+- Directory-level `.inf` sidecars on extract. `extractAll` now writes a
+  `$.inf` alongside the root directory (or per-side `$.inf` for DSD)
+  carrying `TITLE=` and `OPT=` extra-info keys. Formats with
+  subdirectories also get a `.inf` per directory entry.
+
+- `formatDirectoryInf()` helper for emitting directory-level `.inf`
+  lines in stardot spec syntax 1 (zeroed hex fields + extra-info keys).
+
+- `buildImage()` reads `$.inf` as the source of truth for disc title
+  and boot option. Explicit `title`/`boot_option` arguments warn when
+  a `$.inf` is present; pass `force=True` to override.
+
+- CLI `--force` flag on the `build` subcommand to override `$.inf`
+  disc metadata with explicit `--title`/`--boot` values.
+
+- CRC16 and CRC32 checksums emitted in `.inf` sidecars on extract.
+  Validated on build with a warning on mismatch.
+
+- Flat extraction layout. Files are named using the full Acorn path
+  (e.g. `$.BOOT.bas`, `T.DATA.bin`, `$.GAMES.ELITE.bin`). DSD images
+  use `side0/`/`side1/` subdirectories with flat contents per side.
+
+- CLI `--mkdirs` flag on the `extract -a` subcommand to opt into
+  the old hierarchical directory layout.
+
+- CLI `--no-inf` flag on `extract -a` to suppress `.inf` sidecars.
+
+### Deprecated
+
+- `--inf` flag on `extract -a` is now the default and emits a
+  `DeprecationWarning`. It will be removed in a future release.
+
+### Changed (breaking)
+
+- **Default extract behaviour changed.** `extractAll()` now writes a
+  flat directory of files named by their full Acorn path (e.g.
+  `$.BOOT.bas`) and writes `.inf` sidecars by default. Previously
+  it created subdirectories per DFS directory character and required
+  `--inf` to emit sidecars. Use `--mkdirs` (CLI) or
+  `layout="hierarchical"` (library) for the old directory layout;
+  use `--no-inf` (CLI) or `write_inf=False` (library) to suppress
+  sidecars.
+
+- `InfData.access_byte` replaces the old `locked` boolean field. The
+  full 8-bit access byte is preserved through parse, format, and
+  round-trip. `locked` is now a read-only property (bit 3 of
+  `access_byte`).
+
+- `DiscEntry` ABC gains an `accessByte` property (default: 0x08 if
+  locked, 0x00 otherwise). Format engines with richer access bits
+  override it to return the full byte.
+
+- `formatInf()` now percent-encodes spaces in extra-info values so
+  they survive whitespace-delimited tokenization on re-parse.
+  `parseInf()` percent-decodes extra-info values.
+
+- `buildImage()` signature: `title` and `boot_option` are now
+  `Optional` (default `None`), distinguishing "not set" from an
+  explicit empty/OFF value. New `force` parameter.
+
+### Fixed
+
+- `.inf` parser now warns on unrecognised tokens instead of silently
+  discarding remaining fields. Malformed tokens are skipped so that
+  valid fields further along the line are still captured.
+
+- `InfData.crc` property now emits `BeebToolsWarning` on unparseable
+  hex, consistent with `startSector`. Previously returned `None`
+  silently.
+
+- New `InfData.crc32` property with the same warn-on-bad-value
+  pattern. Replaces inline `try/except` in build validation.
+
+- `_decodePercentEscapes` warns on invalid or truncated `%XX`
+  sequences instead of silently treating them as literals.
+
+- Bare `$` in root directory `.inf` (Disc Image Manager format) now
+  correctly parses as `directory="$", name=""` instead of
+  `name="$"`.
+
+- Extra-info values containing spaces were silently truncated on
+  round-trip because `formatInf` emitted them unencoded and the
+  tokenizer split on whitespace.
+
 ## [0.8.0] - 2026-04-12
 
 ### Added

README.md

@@ -164,7 +164,7 @@ beebtools extract mydisc.dsd T.MYPROG --pretty
 beebtools extract mydisc.dsd -a --pretty -d output/
 
 # Extract everything with .inf sidecars preserving file metadata
-beebtools extract mydisc.dsd -a --inf -d output/
+beebtools extract mydisc.dsd -a -d output/
 
 # Preserve teletext control codes in BASIC strings (lossless UTF-8)
 beebtools extract mydisc.dsd T.LOTTERY -o lottery.bas -t utf8

docs/README.md

@@ -23,5 +23,6 @@ For a quick overview and installation instructions, see the
 
 ## Guides
 
+- [The .inf sidecar format](https://github.com/acscpt/beebtools/blob/main/docs/inf-format.md) - syntax, keys, extraction layouts, CRC validation
 - [Pretty-printer](https://github.com/acscpt/beebtools/blob/main/docs/pretty-printer.md) - operator spacing, anti-listing traps
 - [Library usage](https://github.com/acscpt/beebtools/blob/main/docs/library.md) - using beebtools as a Python library

docs/commands/build.md

@@ -1,7 +1,7 @@
 # build - Build a disc image from files
 
 ```bash
-beebtools build <dir> <output> [-t 40|80] [--title TITLE] [--boot OFF|LOAD|RUN|EXEC] [--strict]
+beebtools build <dir> <output> [-t 40|80] [--title TITLE] [--boot OFF|LOAD|RUN|EXEC] [--force] [--strict]
 ```
 
 Assembles a disc image from a directory of files with `.inf` sidecars. The
@@ -10,70 +10,81 @@ or `.adl`).
 
 ## Source directory layout
 
-The source directory should have the same hierarchical layout produced by
-`extract -a --inf`:
+The source directory should have the layout produced by `extract -a`. The
+builder supports both flat (default) and hierarchical layouts.
 
-- **DFS**: one subdirectory per directory character (`$/`, `T/`), with each
-  data file accompanied by a `.inf` sidecar. For DSD images, `side0/` and
-  `side1/` subdirectories are expected.
+### Flat layout (default from `extract -a`)
 
-- **ADFS**: a `$` directory at the top level containing the file hierarchy,
-  with subdirectories matching the ADFS tree structure. Subdirectories are
-  created on the image automatically.
+All files sit in one directory, named by their full Acorn path with dots
+as separators. Each data file has a companion `.inf` sidecar. A `$.inf`
+carries the disc title and boot option.
 
-### DFS example layout
+**DFS example:**
 
 ```
 working/
-  $/
-    BOOT
-    BOOT.inf          # $.BOOT  FF1900 FF8023 000100
-    MENU
-    MENU.inf          # $.MENU  FF0E00 FF802B 000400
-  T/
-    MYPROG
-    MYPROG.inf        # T.MYPROG FF0E00 FF802B 000800
+  $.inf                   # $ 00000000 00000000 00000000 00 TITLE=MY%20DISC OPT=3
+  $.BOOT.bin
+  $.BOOT.bin.inf          # $.BOOT  FF1900 FF8023 000100 00
+  $.MENU.bas
+  $.MENU.bas.inf          # $.MENU  FF0E00 FF802B 000400 00
+  T.MYPROG.bas
+  T.MYPROG.bas.inf        # T.MYPROG FF0E00 FF802B 000800 00
+```
+
+**ADFS example:**
+
+```
+working/
+  $.inf
+  $.GAMES.inf             # directory metadata
+  $.GAMES.ELITE.bin
+  $.GAMES.ELITE.bin.inf   # $.GAMES.ELITE  FFFF0E00 FFFF802B 004000 00
+  $.DATA.inf              # directory metadata
+  $.DATA.SCORES.bin
+  $.DATA.SCORES.bin.inf   # $.DATA.SCORES  FF0000 FF0000 001000 00
 ```
 
-Each `.inf` file uses the standard DFS format: `DIR.NAME  LOAD EXEC SIZE [L]`.
-The directory character in the `.inf` content matches the subdirectory the file
-sits in.
+For DSD images, the builder expects `side0/` and `side1/` subdirectories,
+each with its own flat layout and `$.inf`.
 
-### ADFS example layout
+### Hierarchical layout (from `extract -a --mkdirs`)
+
+One subdirectory per DFS directory character or ADFS path. This is the
+layout produced when `--mkdirs` is passed to `extract`.
+
+**DFS example:**
 
 ```
 working/
+  $.inf
   $/
-    BOOT
-    BOOT.inf          # $.BOOT  FF1900 FF8023 000100
-    GAMES/
-      ELITE
-      ELITE.inf       # $.GAMES.ELITE  FFFF0E00 FFFF802B 004000
-      DATA/
-        SCORES
-        SCORES.inf    # $.GAMES.DATA.SCORES  FF0000 FF0000 001000
+    BOOT.bin
+    BOOT.bin.inf          # $.BOOT  FF1900 FF8023 000100 00
+  T/
+    MYPROG.bas
+    MYPROG.bas.inf        # T.MYPROG FF0E00 FF802B 000800 00
 ```
 
-For ADFS, the directory tree on the filesystem mirrors the ADFS directory
-hierarchy. Each `.inf` sidecar must contain the **full ADFS path** of the file
-(e.g. `$.GAMES.ELITE`, not just `$.ELITE`), because `build` reads the path
-from the `.inf` content when adding the file to the image.
+The builder auto-detects which layout is present by looking for `.inf`
+sidecars in the source tree. Both layouts round-trip correctly.
 
-Subdirectories do not need their own `.inf` files - `build` creates them
-automatically as it walks the filesystem tree.
+### $.inf as source of truth
 
-## Round-trip workflow
+When a `$.inf` exists in the source directory, the builder uses its
+`TITLE=` and `OPT=` values for the disc title and boot option. Explicit
+`--title`/`--boot` flags emit a warning when they conflict with `$.inf`;
+pass `--force` to override.
 
-The easiest way to get a valid source directory is to extract from an existing
-image:
+## Round-trip workflow
 
 ```bash
 # DFS round-trip
-beebtools extract original.ssd -a --inf -d working/
+beebtools extract original.ssd -a -d working/
 beebtools build working/ modified.ssd --title "MODIFIED"
 
 # ADFS round-trip
-beebtools extract original.adf -a --inf -d working/
+beebtools extract original.adf -a -d working/
 beebtools build working/ modified.adf --title "MODIFIED"
 ```
 
@@ -95,14 +106,12 @@ beebtools add mydisc.adf game.bin --name $.GAMES.ELITE --load 0E00 --exec 802B
 
 **Option 2: `build`** (better for many files)
 
-Create the directory tree manually with `.inf` sidecars, then build in one
-step. You must write the `.inf` files yourself with the correct paths and
-addresses:
+Create a directory with `.inf` sidecars, then build in one step. You must
+write the `.inf` files yourself with the correct paths and addresses:
 
 ```bash
-mkdir -p working/\$/GAMES
-echo '$.LOADER  001900 001900 000400' > working/\$/LOADER.inf
-echo '$.GAMES.ELITE  FFFF0E00 FFFF802B 004000' > working/\$/GAMES/ELITE.inf
+echo '$.LOADER  001900 001900 000400 00' > working/$.LOADER.bin.inf
+echo '$.GAMES.ELITE  FFFF0E00 FFFF802B 004000 00' > working/$.GAMES.ELITE.bin.inf
 # ... copy the actual data files alongside each .inf ...
 beebtools build working/ mydisc.adf --title "MY DISC"
 ```
@@ -114,7 +123,7 @@ the builder places the file at that exact sector instead of allocating a fresh
 range. This enables byte-exact round-trips on discs whose catalogue entries
 share sectors (notably Level 9 copy-protected games).
 
-`extract -a --inf` writes `X_START_SECTOR` on every sidecar automatically, so
+`extract -a` writes `X_START_SECTOR` on every sidecar automatically, so
 the default extract-and-rebuild cycle preserves original sector positions without
 any extra flags.
 
@@ -131,6 +140,9 @@ for the full story.
 
 - `--boot` - boot option: OFF, LOAD, RUN, or EXEC (numbers 0-3 also accepted)
 
+- `--force` - override `$.inf` disc metadata with explicit `--title`/`--boot`
+  values
+
 - `--strict` - enforce DFS spec-compliance on filenames. Rejects non-printable
   bytes, `.`, `#`, `*`, `:`, `"`, and space. Use when authoring new discs where
   spec conformance matters. Default behaviour accepts any 7-bit byte, matching