From eea175499d3286e6dbd556eddba106ae40d0161a Mon Sep 17 00:00:00 2001 From: Kevin Bataille Date: Tue, 21 Jul 2026 16:55:33 +0200 Subject: [PATCH] Scaffold WhiteMagic solution and add AGENTS.md Create the WhiteMagic net8.0-windows class library and the WhiteMagicTest xUnit project, grouped in WhiteMagic.slnx (SDK 10 default format). Library enables nullable, unsafe blocks, x86/x64 platforms, warnings-as-errors. Empty solution builds clean (0 errors, 0 warnings). Add AGENTS.md (ASD-STE100) defining the build/test commands, the test-first rule, and the one-feature-one-branch workflow with review before merge to master. Mark project-setup tasks 1.1-1.3, 1.5 done; 1.4 (Native P/Invoke surface) is the first feature branch. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 96 +++++++++++++++++++ WhiteMagic.slnx | 4 + WhiteMagic/WhiteMagic.csproj | 12 +++ WhiteMagicTest/WhiteMagicTest.csproj | 25 +++++ .../changes/whitemagic-foundation/design.md | 2 +- .../changes/whitemagic-foundation/tasks.md | 10 +- 6 files changed, 143 insertions(+), 6 deletions(-) create mode 100644 AGENTS.md create mode 100644 WhiteMagic.slnx create mode 100644 WhiteMagic/WhiteMagic.csproj create mode 100644 WhiteMagicTest/WhiteMagicTest.csproj diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8185aa0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,96 @@ +# AGENTS.md + +This file gives rules to an AI agent that works in this repository. +The text uses ASD-STE100 Simplified Technical English. +Write short sentences. Use the active voice. Give one instruction in each sentence. + +## 1. Purpose + +WhiteMagic is a .NET 8 library for Windows. +The library reads and writes the memory of another process. +The library also injects code, hooks functions, and calls remote functions. +The target process is a game client (WoW 3.3.5a). + +## 2. Repository layout + +- `WhiteMagic/` — the library. Write the product code here. +- `WhiteMagicTest/` — the xUnit test project. Write the tests here. +- `openspec/` — the design documents. Read these before you write code. +- `docs/` — the reference study `memory-library-comparison.md`. +- `reference/` — four older libraries. Git ignores this folder. Read these for study only. Do not build these projects. Do not reference these assemblies. + +## 3. Build and test + +Run each command from the repository root. + +- Build the solution: `dotnet build WhiteMagic.slnx` +- Run the tests: `dotnet test WhiteMagicTest/WhiteMagicTest.csproj` + +The build must show zero errors and zero warnings. +`TreatWarningsAsErrors` is on. A warning stops the build. + +## 4. Code rules + +- Target framework: `net8.0-windows`. +- Enable nullable reference types. Do not disable nullable. +- Enable unsafe blocks only where a pointer dereference needs them. +- Keep the library bitness-agnostic. Support x86 and x64. +- Use `LibraryImport` for a new P/Invoke declaration. Do not use `DllImport` for new code. +- Match the style of the code near your change. + +## 5. Test-first rule + +Write the test before you write the product code. + +Do these steps in order: + +1. Write a test that fails. +2. Write the smallest code that makes the test pass. +3. Clean the code. Keep the test green. + +Test all pure logic. Pure logic includes the assembler bytes, the marshal cache, the pattern matcher, the stub builder, and the pump queue. +A test that needs a live process is an integration test. Gate an integration test on an available target. + +## 6. Design source + +The plan lives in `openspec/changes/whitemagic-foundation/`. + +- Read `proposal.md` for the goal. +- Read `design.md` for the decisions. +- Read `tasks.md` for the ordered task list. +- Read the file in `specs/` that matches your feature. Each requirement uses SHALL. Each scenario uses WHEN and THEN. + +Make the code agree with the specification. +If you must change the plan, update the specification first. +Validate the change: `openspec validate whitemagic-foundation --strict`. + +## 7. Branch and review workflow + +The team builds one feature at a time. + +Obey these rules: + +1. Make one branch for one feature. Name the branch `feature/`. +2. Start the branch from `master`. +3. Write the tests and the code on the branch. +4. Keep the build green on the branch. +5. Request a review before a merge. +6. Do not merge your own feature without a review. +7. Merge to `master` only after the review passes. +8. Delete the feature branch after the merge. + +`master` must always build. `master` must always pass the tests. + +## 8. Commit rules + +- Write a clear commit message. Use the present tense. +- Describe what the commit changes. Describe why the commit changes it. +- Make a small commit for one logical change. +- Do not commit build output. Git ignores `bin/` and `obj/`. + +## 9. Scope limits + +- Do not add WoW offsets to the library. The consumer holds the offsets. +- Do not add bot logic to the library. +- Do not add anti-cheat evasion. +- Add the optional Iced backend only behind the `IAssembler` seam. Keep the default backend free of a third-party dependency. diff --git a/WhiteMagic.slnx b/WhiteMagic.slnx new file mode 100644 index 0000000..10b1b20 --- /dev/null +++ b/WhiteMagic.slnx @@ -0,0 +1,4 @@ + + + + diff --git a/WhiteMagic/WhiteMagic.csproj b/WhiteMagic/WhiteMagic.csproj new file mode 100644 index 0000000..2b1816a --- /dev/null +++ b/WhiteMagic/WhiteMagic.csproj @@ -0,0 +1,12 @@ + + + + net8.0-windows + enable + enable + true + x86;x64;AnyCPU + true + + + diff --git a/WhiteMagicTest/WhiteMagicTest.csproj b/WhiteMagicTest/WhiteMagicTest.csproj new file mode 100644 index 0000000..437979c --- /dev/null +++ b/WhiteMagicTest/WhiteMagicTest.csproj @@ -0,0 +1,25 @@ + + + + net8.0-windows + enable + enable + false + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/openspec/changes/whitemagic-foundation/design.md b/openspec/changes/whitemagic-foundation/design.md index d3bb558..199ee1c 100644 --- a/openspec/changes/whitemagic-foundation/design.md +++ b/openspec/changes/whitemagic-foundation/design.md @@ -93,7 +93,7 @@ A `static class MarshalCache` computes and caches `Marshal.SizeOf`, `TypeCode ### D7: New projects, additive, test-first -`WhiteMagic/` (library, `net8.0-windows`, `AllowUnsafeBlocks`) and `WhiteMagicTest/` (xUnit). No solution file exists in the repo root today; task 1.3 creates a fresh `WhiteMagic.sln` (or builds the csproj directly). BlackMagic lives in a nested subdir with its own git and is not part of this build. Pure-logic components (assembler encodings, marshal cache, pattern matcher, stub builders, pump queue) get tests before implementation, mirroring the existing `inject-and-assemble` change's TDD discipline. Live-process behavior (RPM/WPM, injection, detours) is validated in integration tests gated on an available target. +`WhiteMagic/` (library, `net8.0-windows`, `AllowUnsafeBlocks`) and `WhiteMagicTest/` (xUnit). Task 1.3 creates `WhiteMagic.slnx` (SDK 10's default solution format). The reference libraries live under `reference/` (git-ignored) and are not part of this build. Pure-logic components (assembler encodings, marshal cache, pattern matcher, stub builders, pump queue) get tests before implementation, mirroring the existing `inject-and-assemble` change's TDD discipline. Live-process behavior (RPM/WPM, injection, detours) is validated in integration tests gated on an available target. ## Risks / Trade-offs diff --git a/openspec/changes/whitemagic-foundation/tasks.md b/openspec/changes/whitemagic-foundation/tasks.md index dd9857c..10b5fb5 100644 --- a/openspec/changes/whitemagic-foundation/tasks.md +++ b/openspec/changes/whitemagic-foundation/tasks.md @@ -1,10 +1,10 @@ ## 1. Project Setup -- [ ] 1.1 Create `WhiteMagic/WhiteMagic.csproj` targeting `net8.0-windows`, `AllowUnsafeBlocks=true`, nullable enabled -- [ ] 1.2 Create `WhiteMagicTest/WhiteMagicTest.csproj` (xUnit, `net8.0-windows`) referencing `WhiteMagic` -- [ ] 1.3 No solution file exists in the repo root. Create one (`dotnet new sln -n WhiteMagic`) and add both projects, OR skip the solution and build csproj directly (decide before 1.5). Do NOT reference `BlackMagic.slnx` — it does not exist. +- [x] 1.1 Create `WhiteMagic/WhiteMagic.csproj` targeting `net8.0-windows`, `AllowUnsafeBlocks=true`, nullable enabled, `TreatWarningsAsErrors`, `Platforms=x86;x64;AnyCPU` +- [x] 1.2 Create `WhiteMagicTest/WhiteMagicTest.csproj` (xUnit, `net8.0-windows`) referencing `WhiteMagic` +- [x] 1.3 Create `WhiteMagic.slnx` (SDK 10 default solution format) and add both projects. (Built on SDK 10; `net8.0-windows` targeting pack auto-restored.) - [ ] 1.4 Add `WhiteMagic/Native/` P/Invoke surface (`LibraryImport`): OpenProcess, Read/WriteProcessMemory, VirtualAllocEx/FreeEx/ProtectEx, CreateRemoteThread, Wow64Get/SetThreadContext, Get/SetThreadContext, LoadLibrary, GetProcAddress; add `SafeMemoryHandle` -- [ ] 1.5 Verify empty projects build: `dotnet build WhiteMagic.sln` (or `dotnet build WhiteMagic/WhiteMagic.csproj` if no solution) — zero errors +- [x] 1.5 Verify empty projects build: `dotnet build WhiteMagic.slnx` — zero errors, zero warnings ## 2. Core Memory Access (spec: memory-access) @@ -81,6 +81,6 @@ ## 9. Verification - [ ] 9.1 Run full test suite: `dotnet test WhiteMagicTest/WhiteMagicTest.csproj` — all pass -- [ ] 9.2 Run full build (`dotnet build WhiteMagic.sln` or the WhiteMagic csproj, per 1.3) — zero errors, zero new warnings in `WhiteMagic` +- [ ] 9.2 Run full build (`dotnet build WhiteMagic.slnx`) — zero errors, zero new warnings in `WhiteMagic` - [ ] 9.3 Confirm existing BlackMagic/its tests are unchanged and still green - [ ] 9.4 Update `docs/memory-library-comparison.md` "WhiteMagic — synthesis" section with any deviations discovered during implementation