Scaffold wg-wrap project structure and toolchain

1 files changed, 70 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8bb175a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,70 @@
+# wg-wrap Agent Guidelines
+
+This document defines the architectural conventions, project layout, and system assumptions for the development of `wg-wrap`.
+
+## Project Goals
+`wg-wrap` is a transparent userspace VPN wrapper that allows native Linux processes to communicate over WireGuard without requiring host-level root privileges. It utilizes User and Network namespaces to isolate traffic and a userspace WireGuard implementation to handle encryption.
+
+## Project Layout
+The project follows a modern Go project structure to ensure scalability and a clear separation between public APIs and internal implementation details.
+
+```text
+.
+├── cmd/
+│   └── wg-wrap/           # CLI Entry point. Handles flag parsing and subcommand routing.
+├── internal/
+│   ├── config/            # Application-wide configuration types.
+│   ├── namespace/         # Linux namespace management (unshare, setns, pinning).
+│   └── wireguard/         # Userspace WireGuard controller and TUN device binding.
+├── pkg/
+│   └── wgconf/            # WireGuard .conf parsing logic. Reusable library.
+├── tests/
+│   └── e2e/               # End-to-End "Data Plane" tests using Virtual Peers.
+├── go.mod                 # Module definition.
+└── README.md              # Project overview and design specification.
+```
+
+## Development Conventions
+
+### 1. Quality Assurance Pipeline
+No piece of code is considered "done" until it has passed the full verification pipeline. Every implementation cycle must conclude with the following checks:
+
+1. **Formatting**: `go fmt ./...`
+2. **Static Analysis**: `go vet ./...`
+3. **Linting**: `golangci-lint run`
+4. **Verification**: `go test` (relevant packages)
+
+If any of these tools report an error or warning, the code must be corrected before the task is marked as complete.
+
+### 2. Testing Strategy
+We employ a three-tier testing approach to balance speed and reliability:
+
+| Tier | Location | Type | Scope | Requirement |
+| :--- | :--- | :--- | :--- | :--- |
+| **Unit** | Package dirs | `go test` | Pure logic (e.g., parsing, validation) | None |
+| **Integration** | `internal/**/*_test.go` | `go test -tags=integration` | Syscalls, Namespace creation, Routing | Linux |
+| **E2E** | `tests/e2e/` | `go test ./tests/e2e/...` | Full data path (Connect $\rightarrow$ Curl $\rightarrow$ Peer) | Linux + TUN access |
+
+### 2. Platform Constraints
+- **Target OS**: Linux only.
+- **Build Tags**: Use `//go:build linux` or `//go:build linux,integration` for any code interacting with `golang.org/x/sys/unix` or network namespaces.
+- **MTU**: Always default the TUN device MTU to `1420` to account for WireGuard overhead.
+
+### 3. Namespace Lifecycle
+- **Creation**: `CLONE_NEWUSER` $\rightarrow$ `CLONE_NEWNET`.
+- **Persistence**: Namespaces are pinned by bind-mounting the namespace file to `/run/user/$UID/wg-wrap/profiles/<name>`.
+- **Cleanup**: The tool must monitor the wrapped process and ensure the namespace is unpinned/torn down via `wg-wrap profile stop` or upon process termination.
+
+## System Assumptions
+The project assumes the target environment is a modern Linux system configured for rootless container operations (e.g., Podman is installed and functional):
+- **User Namespaces**: `kernel.unprivileged_userns_clone=1` is assumed.
+- **UID Mapping**: SubUIDs/SubGIDs are configured.
+- **TUN Access**: The user has permission to access `/dev/net/tun`.
+- **Tooling**: The `ip` command (iproute2) is available in the environment.
+
+## Roadmap Priority
+1. **Configuration**: Implement robust `.conf` parsing in `pkg/wgconf`.
+2. **Bootstrapping**: Implement the `unshare` and user-mapping flow in `internal/namespace`.
+3. **Data Path**: Integrate `wireguard-go` with the TUN device in `internal/wireguard`.
+4. **Routing**: Automate the isolated routing table setup.
+5. **Lifecycle**: Implement namespace pinning and cleanup.