NXST/PLAN.md

# NXST Architectural Refactor Plan

## Current Phase Tracker

| Phase | Title | Status | Effort | Notes |
|-------|-------|--------|--------|-------|
| 0 | Tooling & ground rules | ✅ Done | S (~2h) | `.clang-format`, `.clang-tidy`, `.editorconfig`, `.gitattributes` |
| 1 | Bug fixes & dead code | ✅ Done | S (~3h) | logger rewrite, `mkdir 0777`, RU comment, dead code |
| 2 | File renames + `#pragma once` | ✅ Done | S (~2h) | snake_case filenames, unify guards |
| 3 | Directory restructure | ✅ Done | M (~1d) | `src/` + `include/nxst/` layered tree |
| 4 | Make → CMake migration | ✅ Done | M (~1d) | devkitpro `Switch.cmake` toolchain |
| 5 | TransferService extraction | ✅ Done | L (~2d) | kill globals, sever UI ↔ net coupling |
| 6 | `Result<T>` + RAII | ✅ Done | M (~1d) | tagged union, OS handle wrappers, fix raw memory |
| 7 | Documentation + license | ✅ Done | S (~half-day) | README, ARCHITECTURE, PROTOCOL, CHANGELOG, GPLv3 LICENSE |
| 8 | CI | ✅ Done | S (~2h) | GitHub Actions, `.nro` artifact, format check, layering check |

**Active phase:** — All phases complete.
**Last updated:** 2026-04-27.

Mark a phase `🟡 In progress` when starting and `✅ Done` when verified on hardware. Keep this table the source of truth.

---

## Context

NXST is a Nintendo Switch homebrew save-transfer app (~3.2K LOC across 13 .cpp + 24 .hpp files, plus the vendored Plutonium UI submodule). The current codebase works but reads as a prototype:

- Flat `source/` + mostly flat `include/` with mixed `PascalCase` and `lowercase` filenames.
- Mixed identifier style (`recv_all` next to `isServerTransferDone`).
- 11 headers use `#pragma once`, 9 use legacy `#ifndef X_HPP` guards.
- **Severe layering violation**: UI layouts (`TitlesLayout::runTransfer`, `runReceive`) call into raw socket code and `io::restore` directly.
- Globals: 6 in `server.cpp`, 4 in `client.cpp`, 2 in `io.cpp`, plus `g_currentUId` everywhere.
- **Logger is silently broken** (`include/logger.hpp:54`): `printf(StringUtils::format(...).c_str(), args...)` already substitutes the format, then passes leftover variadic args to a string with no remaining `%` specifiers — every error log loses its arguments.
- **Permission bug** in `source/io.cpp:119`: `mkdir(path.c_str(), 777)` — decimal 777 is octal 1411 (no read for owner). Has been wrong since day one.
- One monster function: `io::restore` is 112 lines mixing mount, create, clear, copy, commit.
- Russian comment in `io.cpp:231` (mixed languages).
- Dead commented-out code in `util.cpp:50-58` and `logger.hpp:51-54`.
- No `.clang-format`, no `.clang-tidy`, no `.editorconfig`, no `.gitattributes`, no CI, no `README.md`, no `ARCHITECTURE.md`, no `LICENSE` file (despite `io.cpp` carrying GPLv3 from Checkpoint).

Goal: transform NXST into a layered, conventionally-named, tooled-up project that builds on Switch via CMake and is readable by a stranger in under ten minutes. Solo developer; bar is "professional indie", not enterprise.

User decisions (already made):
- **Full 8-phase plan**.
- **Migrate Make → CMake** with devkitpro toolchain file.
- **camelCase for functions, PascalCase for classes**, snake_case for files and locals, `kPascalCase` for constants.
- **No tests** (Switch homebrew rarely has them; pure-logic surface is small).

---

## Target Directory Tree

```
NXST/
├── .clang-format               # LLVM-derived, 4-space, 110 col
├── .clang-tidy                 # bugprone-*, readability-*, modernize-*
├── .editorconfig               # LF, UTF-8, trim WS, final newline
├── .gitattributes              # eol=lf; lib/Plutonium linguist-vendored
├── .github/workflows/build.yml # CI: devkitpro container, cmake, .nro upload
├── docs/
│   ├── ARCHITECTURE.md
│   ├── PROTOCOL.md
│   └── screenshots/
├── cmake/
│   └── modules/                # FindPlutonium.cmake (if needed)
├── include/nxst/
│   ├── app/                    # MainApplication, AppContext
│   ├── domain/                 # Title, Account, TransferState, Result
│   ├── infra/
│   │   ├── fs/                 # filesystem, directory, RAII handles
│   │   ├── net/                # socket, sendAll/recvAll
│   │   └── sys/                # logger, threading, switch services
│   ├── service/                # TransferService
│   └── ui/                     # layouts, widgets, theme
├── src/                        # mirrors include/nxst/
│   ├── app/
│   ├── domain/
│   ├── infra/{fs,net,sys}/
│   ├── service/
│   ├── ui/
│   └── main.cpp
├── tools/format.sh             # one-line clang-format helper
├── lib/Plutonium/              # submodule, untouched
├── deps/asprintf/              # untouched
├── CMakeLists.txt              # top-level
├── README.md
├── ARCHITECTURE.md             # → docs/ARCHITECTURE.md
├── CHANGELOG.md
├── LICENSE                     # GPLv3 (forced by Checkpoint inheritance)
└── icon.png
```

---

## Naming Convention Spec

| Axis | Rule | Examples |
|---|---|---|
| Files | `snake_case.{cpp,hpp}` | `transfer_service.cpp`, `socket.hpp` |
| Classes / structs | `PascalCase` | `TransferService`, `AccountProfile`, `Socket` |
| Functions / methods | `camelCase` | `sendAll()`, `recvAll()`, `replaceUsername()` |
| Locals / params | `snake_case` | `int sock_fd`, `std::string file_name` |
| Members | `snake_case`, no prefix | `bytes_done`, `client_sock` |
| Constants / constexpr | `kPascalCase` | `kTcpPort`, `kBufSize`, `kMulticastGroup` |
| Enums | `enum class Foo { Bar, Baz }` | `enum class TransferKind { Send, Receive }` |
| Macros (avoid) | `NXST_UPPER_SNAKE` | `NXST_UNREACHABLE` |
| Namespaces | lowercase, short | `nxst`, `nxst::net`, `nxst::ui` |

---

## Layering (dependency direction)

```
                ┌────────────────────────┐
                │   Presentation (ui/)   │
                │   layouts, widgets     │
                └───────────┬────────────┘
                            │
                ┌───────────▼────────────┐
                │     Service (svc/)     │
                │   TransferService      │
                └───────────┬────────────┘
                            │
       ┌────────────────────┼────────────────────┐
       │                    │                    │
┌──────▼──────┐    ┌────────▼──────┐    ┌────────▼──────┐
│  Domain     │    │   Infra/net   │    │   Infra/fs    │  Infra/sys
│  Title,     │    │   Socket,     │    │   Directory,  │  Logger,
│  Account,   │    │   sendAll,    │    │   FsHandle,   │  Thread,
│  Result<T>  │    │   recvAll     │    │   FileHandle  │  Account svc
└─────────────┘    └───────────────┘    └───────────────┘
                            │
                  libnx, SDL, Plutonium
```

**Hard rules.** `domain/` depends on nothing in the project. `infra/` depends only on `domain/`. `service/` depends on `domain/` + `infra/`. `ui/` depends only on `service/` + `domain/` — **must not include `<arpa/inet.h>`, `<sys/socket.h>`, `pthread.h`, or call `recv`/`send` directly**. `app/` wires everything.

CI enforcement: a 20-line shell step greps `src/ui/**` for forbidden headers.

---

## Phase 0 — Tooling and ground rules (S, ~2h)

**Goal.** Lay down conventions before touching code.

**Files created.**
- `.clang-format`: BasedOnStyle LLVM, IndentWidth 4, ColumnLimit 110, PointerAlignment Left, IncludeBlocks Regroup with three categories (system, third-party, project).
- `.clang-tidy`: enable `bugprone-*`, `readability-*` (minus `magic-numbers`), `modernize-*` (minus `use-trailing-return-type`, `use-nodiscard`), `cppcoreguidelines-pro-type-cstyle-cast`. Disable `fuchsia-*`, `google-*`, `llvm-header-guard`.
- `.editorconfig`: LF, UTF-8, 4-space, trim trailing whitespace, final newline. Tab indent for `Makefile` (only while it still exists).
- `.gitattributes`: `* text=auto eol=lf`, `lib/Plutonium/** linguist-vendored=true`, `deps/** linguist-vendored=true`. Stops GitHub mis-classifying the repo language.
- `tools/format.sh`: `clang-format -i` over `src/` + `include/`.

**Risk.** None — no compiled changes.

**Buildable?** Unaffected.

---

## Phase 1 — Bug fixes and dead code (S, ~3h)

**Goal.** Fix concrete bugs before any structural change can mask them.

**Tasks.**
1. Replace broken `Logger` (`include/logger.hpp`) with free-function API in `include/nxst/infra/sys/log.hpp`:
   ```cpp
   namespace nxst::log {
       enum class Level { Debug, Info, Warn, Error };
       void write(Level, const char* fmt, ...) __attribute__((format(printf, 2, 3)));
       void debug(const char* fmt, ...) __attribute__((format(printf, 1, 2)));
       void info (const char* fmt, ...) __attribute__((format(printf, 1, 2)));
       void warn (const char* fmt, ...) __attribute__((format(printf, 1, 2)));
       void error(const char* fmt, ...) __attribute__((format(printf, 1, 2)));
   }
   ```
   Implementation: `vsnprintf` into stack buffer, prefix with `[YYYY-MM-DD HH:MM:SS][LEVEL]`, append to `/switch/NXST/log.log` and stderr. TU-local `std::mutex`. No singleton class. Drop the GPLv3 Checkpoint header (the new file is original).
   - `format(printf, ...)` attribute gives compile-time format-string checking — that is the actual reason this rewrite matters.
   - Leave thin shim `LOG_INFO(...)`/`LOG_ERROR(...)` macros so existing call sites keep compiling during phase migration.
2. Fix `source/io.cpp:119` — `mkdir(path.c_str(), 777)` → `mkdir(path.c_str(), 0777)`.
3. Translate Russian comment at `source/io.cpp:231` to English.
4. Delete dead commented-out code in `source/util.cpp:50-58` and old `include/logger.hpp:51-54` block.

**Risk.** Logger API change ripples to <30 call sites. Macros bridge the gap.

**Buildable?** Yes after each file.

---

## Phase 2 — File renames + `#pragma once` (S, ~2h)

**Goal.** Land the filename convention before the directory move so git history sees rename + move as separate commits.

**Tasks.**
- Rename to `snake_case` via `git mv` (use two-step on case-insensitive macOS): `Main.cpp`→`main.cpp`, `MainApplication.{cpp,hpp}`→`main_application.{cpp,hpp}`, `TitlesLayout.{cpp,hpp}`→`titles_layout.{cpp,hpp}`, `UsersLayout.{cpp,hpp}`→`users_layout.{cpp,hpp}`, plus matching headers under `include/`.
- Convert all `#ifndef X_HPP / #define X_HPP / #endif` guards to `#pragma once`. Affected: `logger.hpp`, `account.hpp`, and the 7 other headers using legacy guards.
- Update affected `#include` lines.
- `Makefile` `SOURCES` globs `*.cpp`, so no Makefile change needed for renames.

**Risk.** macOS case-insensitive FS hides case-only renames — use `git mv Foo.cpp tmp.cpp && git mv tmp.cpp foo.cpp`.

**Buildable?** Yes after each pair.

---

## Phase 3 — Directory restructure (M, ~1 day)

**Goal.** Move flat `source/` and `include/` into the layered tree. **No code changes**, just relocation + include-path updates.

**Tasks.**
1. Create the `src/{app,domain,infra/{net,fs,sys},service,ui}` and `include/nxst/{...}` skeleton.
2. Move files:
   - `protocol.hpp`, `transfer_state.hpp`, `account.hpp` (the `AccountUid` struct + ordering only), `title.hpp/cpp`, `common.hpp/cpp`, `util.hpp/cpp` → `domain/`.
   - `client.{hpp,cpp}` → `infra/net/transfer_sender.{hpp,cpp}`, `server.{hpp,cpp}` → `infra/net/transfer_receiver.{hpp,cpp}`. Renaming is intentional: `CLAUDE.md` already documents that "server = receiver, client = sender" is inverted from typical usage; renaming kills the confusion permanently.
   - `net/socket.hpp` → `infra/net/socket.hpp`.
   - `io.hpp/cpp`, `directory.hpp/cpp`, `filesystem.hpp/cpp` → `infra/fs/`.
   - new `log.hpp/cpp`, switch-service init pieces from `account.cpp` → `infra/sys/`.
   - `main_application.{hpp,cpp}`, `main.{hpp,cpp}` → `app/`.
   - `titles_layout.*`, `users_layout.*`, `transfer_overlay.hpp`, `theme.hpp`, `ui/*.hpp`, `header_bar.hpp` → `ui/`.
3. Update `Makefile` (still in use — CMake migration is Phase 4):
   ```make
   SOURCES  := src src/app src/domain src/infra/net src/infra/fs src/infra/sys src/service src/ui lib/Plutonium/source
   INCLUDES := include lib/Plutonium/include
   ```
   Remove the now-defunct `include/net` from `INCLUDES`.
4. Update **every** `#include` to `#include <nxst/...>` form: `#include <nxst/domain/protocol.hpp>`, `#include <nxst/infra/net/socket.hpp>`. The single root `include/` keeps the prefix mandatory and grepable.

**Risk.** Big disruptive phase. Do on a feature branch, build after every directory's worth of moves. `service/` directory stays empty for now — scaffolding only.

**Buildable?** Yes if you move-and-rebuild incrementally.

---

## Phase 4 — Migrate Make → CMake (M, ~1 day)

**Goal.** Replace `Makefile` with `CMakeLists.txt` using devkitpro's bundled `Switch.cmake` toolchain file. Project compiles via `cmake -B build -DCMAKE_TOOLCHAIN_FILE=$DEVKITPRO/cmake/Switch.cmake && cmake --build build`.

**Tasks.**
1. Create top-level `CMakeLists.txt`:
   - `cmake_minimum_required(VERSION 3.20)`, `project(NXST CXX)`.
   - C++17, `-fno-rtti -fno-exceptions` (matches current `CXXFLAGS`).
   - ARM flags `-march=armv8-a+crc+crypto -mtune=cortex-a57 -mtp=soft -fPIE` mirror current `ARCH`.
   - `find_package(PkgConfig REQUIRED)` + `pkg_check_modules(SWITCH_LIBS REQUIRED SDL2_ttf SDL2_gfx SDL2_image SDL2_mixer freetype2 harfbuzz minizip libpng libjpeg libwebp glesv2 egl glapi zlib)` against `aarch64-none-elf-pkg-config` (already wired up per memory ID 101).
   - Manual link: `pu` (Plutonium), `drm_nouveau`, plus the trailing `-lharfbuzz -lfreetype -lz` static-link-order workaround (memory IDs 97, 98, 100 — required after recent libnx update).
   - Add Plutonium as `add_subdirectory(lib/Plutonium)` if its CMake exists, else as an INTERFACE library wrapping its prebuilt `.a`. Inspection during this phase decides.
   - Use devkitpro's `nx_create_nro` / `nx_generate_nacp` helpers from the toolchain file to emit `NXST.nro` with icon + NACP metadata (`APP_TITLE=NXST`, `APP_AUTHOR=DragonSpirit`, `APP_VERSION=04.26.2026`).
2. Create `cmake/modules/` if any custom Find module proves necessary (likely not).
3. Add convenience targets: `cmake --build build --target send` to invoke `nxlink NXST.nro`.
4. Delete old `Makefile` only after CMake build produces a working `.nro` matching the Make output.
5. Update `.gitignore`: replace `build/` Make artifacts with CMake's `build/` directory rules and `CMakeCache.txt`, `CMakeFiles/`, `compile_commands.json`.

**Risk.** Highest in the plan. Mitigation:
- Keep `Makefile` alongside CMake during the phase. Verify `.nro` from both is identical (or at minimum boots and runs on hardware).
- If the devkitpro `Switch.cmake` toolchain proves brittle for Plutonium's transitive headers, fall back to keeping Make and document why CMake was deferred.
- The pkg-config tweaks captured in memory IDs 96–101 are non-obvious — re-apply them in the CMake config explicitly, not via `pkg_check_modules` defaults.

**Buildable?** Yes — both build systems coexist until CMake is verified.

---

## Phase 5 — TransferService extraction, kill globals (L, ~2 days)

**Goal.** Sever the UI → net coupling. Single biggest "this looks like real software" change.

**Tasks.**
1. Create `src/service/transfer_service.{hpp,cpp}`. Class owns:
   - one `TransferState` per direction (sender, receiver),
   - all listen / accept / broadcast threads (currently 6 globals in `server.cpp`, 4 in `client.cpp`),
   - public API: `start(TransferKind, AccountUid, std::vector<TitleId>)`, `cancel()`, `progress()`, `statusText()`, `isDone()`, `failureReason()`, `setOnComplete(std::function<void(TransferResult)>)`.
2. Move file globals (`g_server_state`, `g_client_state`, all socket/pthread atomics) into `TransferService` private members. pthread C trampolines: `static void* threadEntry(void* self)` immediately calls `*static_cast<TransferService*>(self)`.
3. Refactor `titles_layout.cpp` `runTransfer`/`runReceive` to call `app_ctx.transfer.start(...)` / `cancel()` instead of free `transfer_files()` / `start_listening()`. Inject via `AppContext&` (already partially present per `include/ui/UiContext.hpp`).
4. Move `g_currentUId` out of global scope into `AppContext::current_user`. Pass `AppContext&` down to layouts at construction. There is exactly one `AppContext` and its lifetime equals the app — safe and cheap.
5. UI's `runReceive` currently calls `io::restore` directly after server work completes. Move into the service's completion callback so UI never touches FS directly.

**Strategy.** Keep old `transfer_files()` / `start_listening()` free functions as thin wrappers around `TransferService` for the duration of the phase. Convert UI call sites one at a time. Delete wrappers only after both sites are on the service.

**Buildable?** Yes via the wrappers.

---

## Phase 6 — `Result<T>` and RAII (M, ~1 day)

**Goal.** Replace bool/out-param/silent-failure patterns with `Result<T>`; wrap raw OS handles in RAII.

**Tasks.**
1. `include/nxst/domain/result.hpp` — minimal `Result<T, E=std::string>` with tagged union (no `std::variant` because `-fno-exceptions` rules out monostate-on-throw):
   ```cpp
   template <class T, class E = std::string>
   class Result {
       bool ok_;
       union { T val_; E err_; };
   public:
       static Result success(T v);
       static Result failure(E e);
       bool isOk() const noexcept;
       const T& value() const;     // UB if !isOk
       const E& error() const;     // UB if isOk
       template <class F> auto map(F&&) const;
   };
   ```
   Resist importing `tl::expected`. 60 lines of in-house code beats a vendored dep at this scale.
2. RAII wrappers in `include/nxst/infra/`:
   - `FdHandle` — owns `int fd`, closes on dtor, move-only.
   - `FsFileSystemHandle` — owns `FsFileSystem`, calls `fsFsClose`. Plugs the "save"-mount leak from memory ID 59.
   - `AccountProfileHandle` — owns `AccountProfile`, calls `accountProfileClose`. Plugs the bug from memory ID 64.
   - `FileHandle` — owns `FILE*`, `fclose` on dtor.
3. Replace `io.cpp:57` `new u8[BUFFER_SIZE] / delete[]` and `io.cpp:234` `malloc/free` with `std::vector<u8>` (already the pattern in `client.cpp`/`server.cpp`).
4. Split `io::restore` (the 112-line monster, `io.cpp:221-332`) into `restoreSaveForTitle`, `extractAndCommit`, `clearStaleSaveFiles`. Each returns `Result<void>`.
5. Convert `recvAll` / `sendAll` / socket setup paths in `infra/net` to return `Result<void>` so error paths compose under `-fno-exceptions`.

**Strategy.** Adopt incrementally — start at IO boundaries, leave `bool` returns untouched in modules not yet refactored.

**Buildable?** Yes per file.

---

## Phase 7 — Documentation + license (S, ~half day)

**Goal.** A stranger can build, run, and understand this in under 15 minutes.

**Files created.**
- `README.md`: what NXST does, screenshot, install (drop `.nro` into `/switch/`), build (devkitpro + `cmake --build`), credit Plutonium and Checkpoint, link to `docs/`.
- `docs/ARCHITECTURE.md`: layering diagram from this plan, threading model (one accept thread, one broadcast thread, one transfer thread per direction; cancellation via `shutdown(2)` + atomic flag), pointers to key files.
- `docs/PROTOCOL.md`: promote the 9-line wire-format comment from `protocol.hpp` into a real spec — byte-level diagrams, multicast discovery on `239.0.0.1:8081`, TCP transfer on `:8080`, EOF sentinel = `filename_len == 0`, `kBufSize=65536`, `kMaxFilename=4096`.
- `CHANGELOG.md`: Keep-a-Changelog format. Version `0.x` until protocol stabilizes.
- `LICENSE`: GPLv3 — forced by `io.cpp` carrying Checkpoint's GPLv3 header. Document credit + license inheritance in README.

**Risk.** None.

**Buildable?** Unaffected.

---

## Phase 8 — CI (S, ~2h)

**Goal.** Every push verifies `.nro` builds. One green badge tells visitors the repo is alive.

**Tasks.**
- `.github/workflows/build.yml`:
  ```yaml
  on: [push, pull_request]
  jobs:
    nro:
      runs-on: ubuntu-latest
      container: devkitpro/devkita64:latest
      steps:
        - uses: actions/checkout@v4
          with: { submodules: recursive }
        - run: |
            cmake -B build \
              -DCMAKE_TOOLCHAIN_FILE=$DEVKITPRO/cmake/Switch.cmake \
              -DCMAKE_BUILD_TYPE=Release
            cmake --build build -j$(nproc)
        - uses: actions/upload-artifact@v4
          with:
            name: NXST-${{ github.sha }}
            path: build/NXST.nro
    format:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - run: |
            sudo apt-get install -y clang-format
            find src include -name '*.cpp' -o -name '*.hpp' \
              | xargs clang-format --dry-run --Werror
    layering:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - run: |
            ! grep -rE '^#include\s*[<"](arpa/|sys/socket|pthread\.h)' src/ui/
  ```
- Optional release job on tag `v*`: same CMake build, attach `.nro` to GitHub Release.

**Risk.** First run typically fails on submodule init or container path — iterate on a branch.

**Buildable?** Pass or fix.

---

## Critical files to modify

- `Makefile` — Phase 3 SOURCES/INCLUDES update; deleted in Phase 4 after CMake parity.
- `include/logger.hpp` — Phase 1 replace with `nxst::log` free-function API.
- `source/io.cpp` — Phase 1 mkdir + comment fix; Phase 6 split `restore()` + RAII; Phase 5 stop being called from UI.
- `source/server.cpp` — Phase 3 rename to `transfer_receiver.cpp`; Phase 5 globals migrate into `TransferService`.
- `source/client.cpp` — Phase 3 rename to `transfer_sender.cpp`; Phase 5 globals migrate into `TransferService`.
- `source/TitlesLayout.cpp` — Phase 2 rename; Phase 5 sever direct calls into network and `io::restore`.
- `source/Main.cpp` — Phase 2 rename; Phase 5 construct `AppContext` with `TransferService`.
- `source/util.cpp` — Phase 1 delete dead block.

New files (not yet present):
- `.clang-format`, `.clang-tidy`, `.editorconfig`, `.gitattributes` — Phase 0.
- `CMakeLists.txt` — Phase 4.
- `include/nxst/domain/result.hpp` — Phase 6.
- `include/nxst/service/transfer_service.hpp` + `src/service/transfer_service.cpp` — Phase 5.
- `README.md`, `docs/ARCHITECTURE.md`, `docs/PROTOCOL.md`, `CHANGELOG.md`, `LICENSE` — Phase 7.
- `.github/workflows/build.yml` — Phase 8.

---

## What is deliberately NOT in this plan

1. **C++20.** Devkitpro's `gnu++17` is fine; nothing in the codebase wants concepts/ranges/coroutines, and coroutines under `-fno-exceptions` are a maze. Stay on `gnu++17`.
2. **Abstracting Plutonium.** It is *the* UI framework; you will not port it. UI calls Plutonium directly.
3. **`tl::expected` / `std::expected`.** 60-line in-house `Result<T>` is enough.
4. **DI containers, factories, abstract logger interfaces.** Solo developer, one service, one logger sink. Add complexity only when a second sink actually appears.
5. **Integration tests against the network.** No bug class is meaningfully prevented; cost is high; value comes from running on real hardware.
6. **Migrating from pthread to `std::thread`.** Libnx's pthread is the supported path. A single `Thread` RAII wrapper inside `infra/sys/` is the most you should add.
7. **PImpl broadly.** At 2.3 KLOC compile time is sub-second; PImpl just adds indirection.
8. **Re-vendoring or modifying Plutonium.** Submodule, untouched. `linguist-vendored` keeps it out of GitHub language stats.
9. **UPPER_SNAKE constants.** Visually clash with macros; `kPascalCase` is the modern norm.

---

## Recommended phasing for a solo developer

- **Weekend 1:** Phase 0 + 1 + 2. Tooled, bugs fixed, files renamed, builds. Already feels different.
- **Weekend 2:** Phase 3. Big move, one sitting on a branch.
- **Weekend 3:** Phase 4 (CMake). Build system swap. Highest individual phase risk — schedule when fresh.
- **Weekend 4 (longest):** Phase 5 (TransferService). UI no longer touches sockets. The win.
- **Weekend 5:** Phase 6. `Result<T>`, RAII, `restore()` split.
- **Evening:** Phase 7. README + ARCHITECTURE + LICENSE.
- **Evening:** Phase 8. CI.

Stopping after Weekend 4 still leaves the project visibly more serious than it started. Each weekend produces a defensible "ship it" state.

---

## Verification (end-to-end test plan)

After each phase:
1. `cmake --build build` (Phase 4+) or `make` produces `NXST.nro` with no warnings.
2. Copy `NXST.nro` to Switch SD card `/switch/NXST/`, launch via hbmenu, verify the title list and user list render (regression tests for memory IDs 73, 78).
3. Run a save transfer between two Switches: select a title on the sender, "Receive" on the receiver, verify the file lands and `io::restore` replaces it on the receiver. Verify cancel works mid-transfer (regression for memory IDs 60, 103, 104).
4. Verify the log file at `/switch/NXST/log.log` contains formatted entries with timestamps and levels (regression for the broken-Logger bug).
5. Phase 8 only: confirm a green CI run on a PR; download the `NXST.nro` artifact; install it on Switch; run the same flow.