docs: add AGENTS.md for OpenAI Codex with PortTracker reference and porting workflow
This commit is contained in:
Joseph Doherty
228
AGENTS.md
Normal file
228
AGENTS.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# AGENTS.md
|
||||
|
||||
## Project Summary
|
||||
|
||||
This project ports the NATS messaging server from Go to .NET 10 C#. The Go source (~130K LOC) is the reference at `golang/nats-server/`. Porting progress is tracked in an SQLite database (`porting.db`) managed by the PortTracker CLI tool.
|
||||
|
||||
## Folder Layout
|
||||
|
||||
```
|
||||
natsnet/
|
||||
├── golang/nats-server/ # Go source (read-only reference)
|
||||
├── dotnet/
|
||||
│ ├── src/ZB.MOM.NatsNet.Server/ # Main server library
|
||||
│ ├── src/ZB.MOM.NatsNet.Server.Host/ # Host entry point
|
||||
│ └── tests/
|
||||
│ ├── ZB.MOM.NatsNet.Server.Tests/ # Unit tests
|
||||
│ └── ZB.MOM.NatsNet.Server.IntegrationTests/ # Integration tests
|
||||
├── tools/NatsNet.PortTracker/ # CLI tracking tool
|
||||
├── docs/standards/dotnet-standards.md # .NET coding standards (MUST follow)
|
||||
├── docs/plans/phases/ # Phase instruction guides
|
||||
├── reports/current.md # Latest porting status
|
||||
├── porting.db # SQLite tracking database
|
||||
└── porting-schema.sql # Database schema
|
||||
```
|
||||
|
||||
## Build and Test
|
||||
|
||||
```bash
|
||||
# Build the solution
|
||||
dotnet build dotnet/
|
||||
|
||||
# Run all unit tests
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
|
||||
# Run filtered tests (by namespace/class)
|
||||
dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol" \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
|
||||
# Run integration tests
|
||||
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/
|
||||
|
||||
# Generate porting report
|
||||
./reports/generate-report.sh
|
||||
```
|
||||
|
||||
## .NET Coding Standards
|
||||
|
||||
**MUST follow all rules in `docs/standards/dotnet-standards.md`.**
|
||||
|
||||
Critical rules (non-negotiable):
|
||||
|
||||
- .NET 10, C# latest, nullable enabled
|
||||
- **xUnit 3** + **Shouldly** + **NSubstitute** for testing
|
||||
- **NEVER use FluentAssertions or Moq** — these are forbidden
|
||||
- PascalCase for public members, `_camelCase` for private fields
|
||||
- File-scoped namespaces: `ZB.MOM.NatsNet.Server.[Module]`
|
||||
- Use `CancellationToken` on all async signatures
|
||||
- Use `ReadOnlySpan<byte>` on hot paths
|
||||
- Test naming: `[Method]_[Scenario]_[Expected]`
|
||||
- Test class naming: `[ClassName]Tests`
|
||||
- Structured logging with `ILogger<T>` and `LogContext.PushProperty`
|
||||
|
||||
## PortTracker CLI
|
||||
|
||||
All tracking commands use this base:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- <command> --db porting.db
|
||||
```
|
||||
|
||||
### Querying
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `report summary` | Show overall porting progress |
|
||||
| `dependency ready` | List items ready to port (no unported deps) |
|
||||
| `dependency blocked` | List items blocked by unported deps |
|
||||
| `feature list --status <s>` | List features by status |
|
||||
| `feature list --module <id>` | List features in a module |
|
||||
| `feature show <id>` | Show feature details (Go source path, .NET target) |
|
||||
| `test list --status <s>` | List tests by status |
|
||||
| `test show <id>` | Show test details |
|
||||
| `module list` | List all modules |
|
||||
| `module show <id>` | Show module with its features and tests |
|
||||
|
||||
### Updating Status
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `feature update <id> --status <s>` | Update one feature |
|
||||
| `feature batch-update --ids "1-10" --set-status <s> --execute` | Bulk update features |
|
||||
| `test update <id> --status <s>` | Update one test |
|
||||
| `test batch-update --ids "1-10" --set-status <s> --execute` | Bulk update tests |
|
||||
| `module update <id> --status <s>` | Update module status |
|
||||
|
||||
### Audit Verification
|
||||
|
||||
Status updates are verified against Roslyn audit results. If the audit disagrees with your requested status, add `--override "reason"` to force it.
|
||||
|
||||
```bash
|
||||
feature update 42 --status verified --override "manually verified logic"
|
||||
```
|
||||
|
||||
### Audit Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `audit --type features` | Dry-run audit of features against .NET source |
|
||||
| `audit --type tests` | Dry-run audit of tests against test project |
|
||||
| `audit --type features --execute` | Apply audit classifications to DB |
|
||||
| `audit --type tests --execute` | Apply test audit classifications to DB |
|
||||
|
||||
### Valid Statuses
|
||||
|
||||
```
|
||||
not_started → stub → complete → verified
|
||||
└→ n_a (not applicable)
|
||||
└→ deferred (blocked, needs server infra)
|
||||
```
|
||||
|
||||
### Batch ID Syntax
|
||||
|
||||
`--ids` accepts: ranges `"100-200"`, lists `"1,5,10"`, or mixed `"1-5,10,20-25"`.
|
||||
|
||||
All batch commands default to dry-run. Add `--execute` to apply.
|
||||
|
||||
## Porting Workflow
|
||||
|
||||
### Finding Work
|
||||
|
||||
1. Query for features ready to port:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- dependency ready --db porting.db
|
||||
```
|
||||
|
||||
2. Or find deferred/stub features in a specific module:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature list --module <id> --status deferred --db porting.db
|
||||
```
|
||||
|
||||
3. To find tests that need implementing:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test list --status stub --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test list --status deferred --db porting.db
|
||||
```
|
||||
|
||||
### Implementing a Feature
|
||||
|
||||
1. **Claim it** — mark as stub before starting:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature update <id> --status stub --db porting.db
|
||||
```
|
||||
|
||||
2. **Read the Go source** — use `feature show <id>` to get the Go file path and line numbers, then read the Go implementation.
|
||||
|
||||
3. **Write idiomatic C#** — translate intent, not lines:
|
||||
- Use `async`/`await`, not goroutine translations
|
||||
- Use `Channel<T>` for Go channels
|
||||
- Use `CancellationToken` for `context.Context`
|
||||
- Use `ReadOnlySpan<byte>` on hot paths
|
||||
- Use `Lock` (C# 13) for `sync.Mutex`
|
||||
- Use `ReaderWriterLockSlim` for `sync.RWMutex`
|
||||
|
||||
4. **Ensure it compiles** — run `dotnet build dotnet/`
|
||||
|
||||
5. **Mark complete**:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature update <id> --status complete --db porting.db
|
||||
```
|
||||
|
||||
### Implementing a Unit Test
|
||||
|
||||
1. **Read the Go test** — use `test show <id>` to get Go source location.
|
||||
2. **Read the corresponding .NET feature** to understand the API surface.
|
||||
3. **Write the test** in `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/` using xUnit 3 + Shouldly + NSubstitute.
|
||||
4. **Run it**:
|
||||
|
||||
```bash
|
||||
dotnet test --filter "FullyQualifiedName~TestClassName" \
|
||||
dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
|
||||
```
|
||||
|
||||
5. **Mark verified** (if passing):
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test update <id> --status verified --db porting.db
|
||||
```
|
||||
|
||||
### After Completing Work
|
||||
|
||||
1. Run affected tests to verify nothing broke.
|
||||
2. Update DB status for all items you changed.
|
||||
3. Check what's newly unblocked:
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- dependency ready --db porting.db
|
||||
```
|
||||
|
||||
4. Generate updated report:
|
||||
|
||||
```bash
|
||||
./reports/generate-report.sh
|
||||
```
|
||||
|
||||
## Go to .NET Translation Reference
|
||||
|
||||
| Go Pattern | .NET Equivalent |
|
||||
|------------|-----------------|
|
||||
| `goroutine` | `Task.Run` or `async`/`await` |
|
||||
| `chan T` | `Channel<T>` |
|
||||
| `select` | `Task.WhenAny` |
|
||||
| `sync.Mutex` | `Lock` (C# 13) |
|
||||
| `sync.RWMutex` | `ReaderWriterLockSlim` |
|
||||
| `sync.WaitGroup` | `Task.WhenAll` or `CountdownEvent` |
|
||||
| `atomic.Int64` | `Interlocked` methods on `long` field |
|
||||
| `context.Context` | `CancellationToken` |
|
||||
| `defer` | `try`/`finally` or `using` |
|
||||
| `error` return | Exceptions or Result pattern |
|
||||
| `[]byte` | `byte[]`, `ReadOnlySpan<byte>`, `ReadOnlyMemory<byte>` |
|
||||
| `map[K]V` | `Dictionary<K,V>` or `ConcurrentDictionary<K,V>` |
|
||||
| `interface{}` | `object` or generics |
|
||||
| `time.Duration` | `TimeSpan` |
|
||||
| `weak.Pointer[T]` | `WeakReference<T>` |
|
||||
29
docs/plans/2026-02-27-agents-md-design.md
Normal file
29
docs/plans/2026-02-27-agents-md-design.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# AGENTS.md Design
|
||||
|
||||
## Purpose
|
||||
|
||||
Create an `AGENTS.md` file at the project root for OpenAI Codex agents working on this codebase. The file provides project context, PortTracker CLI reference, porting workflow guidance, and pointers to .NET coding standards.
|
||||
|
||||
## Target
|
||||
|
||||
OpenAI Codex — follows Codex's AGENTS.md discovery conventions (root-level, markdown format, under 32KB).
|
||||
|
||||
## Structure Decision
|
||||
|
||||
**Flat single-file** at project root. The project information is tightly coupled — PortTracker commands are needed regardless of which directory Codex is editing. A single file keeps everything in context for every session.
|
||||
|
||||
## Sections
|
||||
|
||||
1. **Project Summary** — What the project is, where Go source and .NET code live
|
||||
2. **Folder Layout** — Directory tree with annotations
|
||||
3. **Build and Test** — Commands to build, run unit tests, run filtered tests, run integration tests
|
||||
4. **.NET Coding Standards** — Pointer to `docs/standards/dotnet-standards.md` with critical rules inlined (forbidden packages, naming, testing framework)
|
||||
5. **PortTracker CLI** — Full command reference: querying, updating, audit verification, valid statuses, batch syntax
|
||||
6. **Porting Workflow** — Step-by-step: finding work, implementing features, implementing tests, post-completion checklist
|
||||
7. **Go to .NET Translation Reference** — Quick-reference table for common Go-to-.NET pattern translations
|
||||
|
||||
## Size
|
||||
|
||||
~3.5KB — well within Codex's 32KB default limit.
|
||||
|
||||
<!-- Last verified against codebase: 2026-02-27 -->
|
||||
@@ -1,6 +1,6 @@
|
||||
# NATS .NET Porting Status Report
|
||||
|
||||
Generated: 2026-02-27 10:51:26 UTC
|
||||
Generated: 2026-02-27 11:11:12 UTC
|
||||
|
||||
## Modules (12 total)
|
||||
|
||||
@@ -12,10 +12,10 @@ Generated: 2026-02-27 10:51:26 UTC
|
||||
|
||||
| Status | Count |
|
||||
|--------|-------|
|
||||
| deferred | 2501 |
|
||||
| deferred | 2493 |
|
||||
| n_a | 18 |
|
||||
| stub | 168 |
|
||||
| verified | 986 |
|
||||
| verified | 994 |
|
||||
|
||||
## Unit Tests (3257 total)
|
||||
|
||||
@@ -35,4 +35,4 @@ Generated: 2026-02-27 10:51:26 UTC
|
||||
|
||||
## Overall Progress
|
||||
|
||||
**1593/6942 items complete (22.9%)**
|
||||
**1601/6942 items complete (23.1%)**
|
||||
|
||||
38
reports/report_db1de2a.md
Normal file
38
reports/report_db1de2a.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# NATS .NET Porting Status Report
|
||||
|
||||
Generated: 2026-02-27 11:11:12 UTC
|
||||
|
||||
## Modules (12 total)
|
||||
|
||||
| Status | Count |
|
||||
|--------|-------|
|
||||
| verified | 12 |
|
||||
|
||||
## Features (3673 total)
|
||||
|
||||
| Status | Count |
|
||||
|--------|-------|
|
||||
| deferred | 2493 |
|
||||
| n_a | 18 |
|
||||
| stub | 168 |
|
||||
| verified | 994 |
|
||||
|
||||
## Unit Tests (3257 total)
|
||||
|
||||
| Status | Count |
|
||||
|--------|-------|
|
||||
| deferred | 2662 |
|
||||
| n_a | 187 |
|
||||
| stub | 18 |
|
||||
| verified | 390 |
|
||||
|
||||
## Library Mappings (36 total)
|
||||
|
||||
| Status | Count |
|
||||
|--------|-------|
|
||||
| mapped | 36 |
|
||||
|
||||
|
||||
## Overall Progress
|
||||
|
||||
**1601/6942 items complete (23.1%)**
|
||||
Reference in New Issue
Block a user