| --- |
| tags: |
| - preservation |
| - rust |
| - bevy |
| --- |
| |
| # Nanobrush |
|
|
| Microbrush preservation and a planned native Rust/Bevy/Solari reconstruction for macOS and Linux. The application rewrite has not started. See [the work list](docs/TODO.md), [goals](docs/GOALS.md), and [initial findings](docs/FINDINGS.md). |
|
|
| ## Development setup |
|
|
| ```sh |
| GIT_LFS_SKIP_SMUDGE=1 git clone --origin hf git@hf.co:nmarshall/nanobrush |
| cd nanobrush |
| nix develop |
| assets-fetch |
| unpack-references |
| ``` |
|
|
| `nix develop` installs repository-local code/LFS/Xet filters and hooks. For automatic environment loading, review `.envrc` and run `direnv allow`. The flake uses pinned `my-nix` inputs; `.envrc` also supports watched local `~/src/scripts/my-nix` and `~/src/me/tools` overrides. No original executable or startup script is run by setup/extraction. |
|
|
| ## Storage |
|
|
| This is one Git repository and one history. Source, tests, scripts, authored docs, and small manifests are ordinary Git text. Every file under `assets/`, or under any directory named `references/`, uses LFS pointers in Git and Xet for payload transfer. This includes small original TXT/CFG/IXPL/shader files. Never disable the filters to add a payload. |
|
|
| ```text |
| assets/references/ |
| archives/ # unchanged original ZIPs |
| provenance/collection/ # supplied README, report, manifest, checksums |
| provenance/historical/ # supplied pages and archive indexes |
| extracted/<build>/ # unmodified extracted member bytes |
| inventories/<build>.json # hashes and original ZIP metadata |
| SHA256SUMS # relocated archive paths, verified from repo root |
| ``` |
|
|
| The original license texts remain preserved. Preservation does not grant a new license to the original content; see the recorded terms in the findings. |
|
|
| ## Commands |
|
|
| Run these inside the dev shell (or use `python3 scripts/<name>.py` for Python tools): |
|
|
| ```sh |
| check-environment |
| check-storage |
| test-setup |
| assets-check |
| verify-references --check-extracted |
| unpack-references --dry-run |
| unpack-references --build 2016-03-10-c |
| index-references |
| shasum -a 256 -c assets/references/SHA256SUMS |
| ``` |
|
|
| `unpack-references` defaults to all five builds. It verifies archive hashes/CRCs before extracting, rejects unsafe members, writes atomically, checks existing outputs, and refuses to overwrite changed files. Interrupted locks require inspection before removal. Empty original directories are restored by unpacking because Git does not track empty directories. |
|
|
| Commit code and pointer files together with ordinary `git add` / `git commit` / `git push hf main`. The pre-commit hook checks staged storage and filter configuration; pre-push checks new history, then invokes the LFS/Xet upload. `assets-fetch` hydrates files for the checked-out revision; `assets-check` verifies every payload against its staged pointer identity. No separate dataset, branch, or asset lockfile is required: the Git revision pins the pointers. |
|
|
| See [setup validation](docs/SETUP.md) for the implementation, checks, and remaining platform coverage. |
|
|
| ## Source research |
|
|
| `map-references` verifies the recovered inputs and regenerates the Xet-backed static source map plus the Core/tool Markdown indexes. `check-reference-map` checks that they are reproducible and current. No original compiler or executable runs. Start with [formats](docs/FORMATS.md), [host APIs](docs/HOST_APIS.md), [plugins](docs/PLUGINS.md), [dependencies](docs/DEPENDENCIES.md), and the [coverage ledger](docs/parity.md). The separate [converter investigation](docs/CONVERTER.md) now runs unchanged converters under Mono; native editor behavior remains unverified. |
|
|
| `analyze-converter decompile|probes|check` reproduces the managed converter evidence and 101 controlled probes. `inspect-mb3dat <file>` safely inspects either recovered DAT version. These research tools, including pinned Mono/ILSpy, are in the Nix shell; captures/decompilations remain Xet assets. See [E02](docs/experiments/converter-2026-10-21.md) and the [binary contract](docs/MB3_DAT.md). |
|
|
| ## Rust DAT codec |
|
|
| `crates/mb3-dat` provides dependency-free bounded readers/writers for both recovered DAT versions. Run `cargo test --workspace --locked --offline` inside `nix develop` after hydrating and verifying the converter fixtures (`analyze-converter check`). All 58 captured DAT outputs are tested for exact byte round trips. See [API, compatibility and limits](docs/RUST_DAT.md). |
|
|
| The asset-free Nix check `nix build .#checks.aarch64-darwin.rust --no-link` runs formatting, Clippy, unit tests and doctests; full converter integration tests require Xet assets. |
|
|
| ## Native TXT/DAT CLI |
|
|
| `nix run .#nanobrush -- inspect FILE` prints a JSON summary; `validate FILE` checks structure. Convert with `convert INPUT OUTPUT --to txt`, `--to dat-201501280`, or `--to dat-201512200`. Inside the dev shell, use `cargo run -p nanobrush-cli -- ...`. Existing outputs require `--force`; source aliases and output symlinks are refused. |
|
|
| [TXT compatibility](docs/RUST_TXT.md) documents strict UTF-8 input, BOM output, finite numbers and computed-data consistency. [CLI usage and publication](docs/CLI.md) covers limits, exit codes and atomic saves. Full Cargo tests require hydrated converter fixtures; Nix checks and the native package build exclude assets. |
|
|
