project initialization

Author: ethical-buddy

CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to VX6
+
+VX6 is being developed as a networking project with a narrow initial scope and a long technical runway. Contributions should improve correctness, clarity, and operational confidence.
+
+## Project Priorities
+
+- Keep IPv6 behavior explicit.
+- Prefer simple designs over speculative abstraction.
+- Build stable transport primitives before layering discovery or routing features.
+- Document behavioral changes in the same change set as the code.
+
+## Development Baseline
+
+- Go 1.22 or newer
+- Linux-first workflow
+- An environment where IPv6 can be tested directly
+
+## Repository Conventions
+
+- `cmd/` contains executable entrypoints.
+- `internal/` contains implementation packages.
+- `docs/` contains architecture, roadmap, and protocol notes.
+
+## Pull Requests
+
+Keep pull requests focused. A good change set should:
+
+- solve one clearly defined problem
+- include tests when behavior can be exercised automatically
+- update documentation when commands, structure, or semantics change
+- explain operational impact in plain language
+
+## Coding Standards
+
+- Run `gofmt` on all Go changes.
+- Keep exported APIs minimal.
+- Return contextual errors.
+- Do not silently fall back from IPv6 to IPv4.
+- Avoid introducing dependencies without a clear payoff.
+
+## Design Changes
+
+Open an issue or short design note before changing:
+
+- wire formats
+- identity semantics
+- routing behavior
+- discovery models
+- configuration layout
+
+## Security
+
+Do not commit private keys, captured traffic, credentials, or lab secrets. If a change affects trust boundaries or transport guarantees, document the assumptions directly in the pull request.

README.md

@@ -0,0 +1,62 @@
+# VX6
+
+VX6 is an IPv6-first transport and service fabric for direct, host-to-host connectivity without central tunnel infrastructure.
+
+This repository currently ships the first executable building block: a small Go CLI that opens a `tcp6` connection and streams a file to a remote IPv6 listener. The long-term project direction is larger than that, but the codebase starts with a narrow, working transport primitive.
+
+## Current Scope
+
+- IPv6-only file transfer over `tcp6`
+- Simple CLI with no external dependencies
+- Linux-first development baseline
+- Clean repository structure for future networking components
+
+## Repository Layout
+
+```text
+VX6/
+├── cmd/vx6/              # CLI entrypoint
+├── docs/                 # Architecture and roadmap documents
+├── internal/             # Non-exported application packages
+├── .gitignore
+├── CONTRIBUTING.md
+├── go.mod
+└── README.md
+```
+
+## Quick Start
+
+Build the binary:
+
+```bash
+go build ./cmd/vx6
+```
+
+Start a receiver on another machine with an IPv6 listener on port `4242`:
+
+```bash
+nc -6 -l 4242 > received.bin
+```
+
+Send a file:
+
+```bash
+./vx6 send --file ./example.bin --addr [2001:db8::10]:4242
+```
+
+The current sender writes raw file bytes to the socket. The receiving side can be any IPv6-capable TCP listener that reads from standard input.
+
+## Design Principles
+
+- IPv6 is a first-class constraint, not an optional fallback.
+- The codebase should stay small, inspectable, and easy to reason about.
+- Initial transport primitives should be reliable before higher-level discovery and routing layers are added.
+- Documentation should describe the system plainly and precisely.
+
+## Status
+
+VX6 is at an early bootstrap stage. The present milestone establishes repository conventions and a working IPv6 transfer command that the larger system can build on.
+
+## Contributing
+
+Contribution guidelines are in [CONTRIBUTING.md](./CONTRIBUTING.md).

cmd/vx6/main.go

@@ -0,0 +1,16 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"github.com/vx6/vx6/internal/cli"
+)
+
+func main() {
+	if err := cli.Run(context.Background(), os.Args[1:]); err != nil {
+		fmt.Fprintln(os.Stderr, "vx6:", err)
+		os.Exit(1)
+	}
+}

docs/architecture.md

@@ -0,0 +1,30 @@
+# VX6 Architecture
+
+## Current Baseline
+
+The repository starts with a single transport primitive:
+
+1. Open a `tcp6` connection to a remote IPv6 endpoint.
+2. Stream file bytes over that connection.
+3. Close cleanly after transfer completion or surface the error.
+
+This is intentionally narrow. VX6 should earn complexity rather than declare it.
+
+## Near-Term Direction
+
+The transport primitive in this repository is expected to evolve into a larger IPv6-first system with the following layers:
+
+- endpoint handling
+- node identity
+- service publication
+- discovery
+- forwarding and routing
+
+Each layer should remain independently testable. Direct connectivity is the default path; any relay or proxy behavior should be an explicit extension, not an implicit fallback.
+
+## Implementation Rules
+
+- Keep IPv6-only behavior explicit in code and documentation.
+- Prefer streaming interfaces over whole-file buffering.
+- Keep package boundaries small and responsibility-driven.
+- Add protocol surface gradually and document it as it appears.

docs/roadmap.md

@@ -0,0 +1,33 @@
+# VX6 Roadmap
+
+## Phase 0
+
+- establish repository structure
+- provide a working Go CLI
+- implement IPv6 file streaming over `tcp6`
+- define documentation and contribution standards
+
+## Phase 1
+
+- add receiver-side protocol support in Go
+- define transfer metadata framing
+- add checksums and transfer diagnostics
+- add tests for IPv6 parsing and stream handling
+
+## Phase 2
+
+- introduce node identity
+- persist local configuration
+- formalize peer connection handling
+
+## Phase 3
+
+- add service advertisement primitives
+- define discovery records
+- document bootstrap and lookup strategy
+
+## Phase 4
+
+- evaluate forwarding, proxying, and policy controls
+- add observability for routing and transfer paths
+- prepare for multi-node integration testing

docs/vision.md

@@ -0,0 +1,12 @@
+# VX6 Vision
+
+VX6 is intended to grow from a transport tool into a broader IPv6-native connectivity layer for direct service exposure and peer-to-peer operation.
+
+The project direction is guided by a few constraints:
+
+- direct IPv6 paths should be preferred over managed tunnel infrastructure
+- endpoint identity should eventually be separable from a changing address
+- service publication and discovery should be designed as composable layers
+- operational simplicity matters as much as protocol ambition
+
+The current repository does not claim that full system yet. It establishes the code, structure, and standards needed to build toward it without overstating present capabilities.

go.mod

@@ -0,0 +1,3 @@
+module github.com/vx6/vx6
+
+go 1.22.0

internal/cli/app.go

@@ -0,0 +1,64 @@
+package cli
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/vx6/vx6/internal/transfer"
+)
+
+func Run(ctx context.Context, args []string) error {
+	if len(args) == 0 {
+		printUsage(os.Stderr)
+		return errors.New("missing command")
+	}
+
+	switch args[0] {
+	case "send":
+		return runSend(ctx, args[1:])
+	case "-h", "--help", "help":
+		printUsage(os.Stdout)
+		return nil
+	default:
+		printUsage(os.Stderr)
+		return fmt.Errorf("unknown command %q", args[0])
+	}
+}
+
+func runSend(ctx context.Context, args []string) error {
+	fs := flag.NewFlagSet("send", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+
+	filePath := fs.String("file", "", "path to the file to send")
+	address := fs.String("addr", "", "remote IPv6 address in [addr]:port form")
+
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+
+	if *filePath == "" {
+		return errors.New("send requires --file")
+	}
+	if *address == "" {
+		return errors.New("send requires --addr")
+	}
+
+	result, err := transfer.SendFile(ctx, *filePath, *address)
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintf(os.Stdout, "sent %d bytes to %s\n", result.BytesSent, result.RemoteAddr)
+	return nil
+}
+
+func printUsage(w io.Writer) {
+	fmt.Fprintln(w, "VX6")
+	fmt.Fprintln(w)
+	fmt.Fprintln(w, "Usage:")
+	fmt.Fprintln(w, "  vx6 send --file <path> --addr [ipv6]:port")
+}

internal/transfer/send.go

@@ -0,0 +1,56 @@
+package transfer
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os"
+)
+
+type SendResult struct {
+	BytesSent  int64
+	RemoteAddr string
+}
+
+func SendFile(ctx context.Context, filePath, address string) (SendResult, error) {
+	if err := validateIPv6Address(address); err != nil {
+		return SendResult{}, err
+	}
+
+	file, err := os.Open(filePath)
+	if err != nil {
+		return SendResult{}, fmt.Errorf("open file: %w", err)
+	}
+	defer file.Close()
+
+	var dialer net.Dialer
+	conn, err := dialer.DialContext(ctx, "tcp6", address)
+	if err != nil {
+		return SendResult{}, fmt.Errorf("dial tcp6 %s: %w", address, err)
+	}
+	defer conn.Close()
+
+	written, err := file.WriteTo(conn)
+	if err != nil {
+		return SendResult{}, fmt.Errorf("stream file to %s: %w", address, err)
+	}
+
+	return SendResult{
+		BytesSent:  written,
+		RemoteAddr: conn.RemoteAddr().String(),
+	}, nil
+}
+
+func validateIPv6Address(address string) error {
+	host, _, err := net.SplitHostPort(address)
+	if err != nil {
+		return fmt.Errorf("invalid address %q: %w", address, err)
+	}
+
+	ip := net.ParseIP(host)
+	if ip == nil || ip.To4() != nil {
+		return fmt.Errorf("address %q is not an IPv6 endpoint", address)
+	}
+
+	return nil
+}

internal/transfer/send_test.go

@@ -0,0 +1,43 @@
+package transfer
+
+import "testing"
+
+func TestValidateIPv6Address(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		address string
+		wantErr bool
+	}{
+		{
+			name:    "valid ipv6",
+			address: "[2001:db8::1]:4242",
+		},
+		{
+			name:    "ipv4 rejected",
+			address: "127.0.0.1:4242",
+			wantErr: true,
+		},
+		{
+			name:    "missing brackets rejected",
+			address: "2001:db8::1:4242",
+			wantErr: true,
+		},
+	}
+
+	for _, tc := range tests {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := validateIPv6Address(tc.address)
+			if tc.wantErr && err == nil {
+				t.Fatal("expected error, got nil")
+			}
+			if !tc.wantErr && err != nil {
+				t.Fatalf("expected nil error, got %v", err)
+			}
+		})
+	}
+}