# CLAUDE.md

## Language: Moxie

This project uses Moxie — a compiled systems language for domain-isolated programs. Moxie descends from TinyGo but is its own language with `.mx` source files, `moxie.mod` modules, and a restricted execution model.

**Read [../moxie/REFERENCE.md](../moxie/REFERENCE.md) before writing any code.**

## Hard Rules

These are compile errors. Violating them wastes a build cycle.

### Type System
- `string` and `[]byte` are the **same type**. Identical 3-word layout (ptr, len, cap). Mutually assignable. Use `string` in signatures for readability.
- `int` and `uint` are always **32-bit**. `len()` and `cap()` return `int32`.
- `range` over text yields **bytes**, not runes.

### Forbidden Constructs
| Construct | Compile Error | Use Instead |
|-----------|---------------|-------------|
| `go f()` | No goroutines | Channels + `select` for dispatch, `spawn` for isolation |
| `make(T, ...)` | Removed | Literal syntax: `[]T{:n}`, `chan T{}`, `map[K]V{}` |
| `new(T)` | Removed | `&T{}` or `var x T; p := &x` |
| `"a" + "b"` | No `+` on text | `"a" \| "b"` (pipe operator) |
| `fallthrough` | Removed | `case A, B:` comma-separated |
| `complex64/128` | Removed | Not supported |
| `uintptr` | Removed | Explicit pointers. Allowed with `import "unsafe"` |
| `import "strings"` | Removed | `import "bytes"` (they're the same type) |

### Literal Syntax
| Moxie | Description |
|-------|-------------|
| `[]T{:n}` | Slice with length n |
| `[]T{:n:c}` | Slice with length n, capacity c |
| `chan T{}` | Unbuffered channel |
| `chan T{n}` | Buffered channel with capacity n |
| `map[K]V{}` | Empty map |

`make()` is a compile error in user code. Use literal syntax only.

## Build

```sh
make build
# or directly:
MOXIEROOT=../moxie ../moxie/moxie build -o gitweb .
```

## Architecture

gitweb is a single-file Moxie application (`main.mx`) that serves a git hosting frontend. It implements HTTP handling directly (raw TCP + manual HTTP parsing) because `net/http` is broken in Moxie's runtime. Deployed via Docker to git.smesh.lol.

Key details:
- Single `.mx` source file
- Uses `unsafe` and `syscall` for raw clone/execve (git-http-backend CGI)
- Markdown rendering built-in (GFM tables, code fences, relative links)
- `string=[]byte` aliasing means `bytes.Buffer.String()` returns an alias — copy if reusing the buffer

## Known Moxie Bugs (work around, don't fix here)

- `net/http` broken — bypass entirely, use raw TCP + manual HTTP parsing
- `SetReadDeadline` causes instant timeout — never use net.Conn deadlines
- `Sprintf` can corrupt earlier results (string=[]byte means shared backing) — always copy

Fix upstream in ../moxie first, then rebuild gitweb.

## Dependencies

ALLOWED:
- Moxie standard library
- Packages already in go.mod

FORBIDDEN without approval:
- Any new dependency not already in go.mod
- Any npm/node ecosystem tool

## Change Discipline

- Small commits, one feature at a time
- Verify compile AND run before moving on
- Re-read modified files after changes to catch drift
- When fixing a bug, understand the root cause before writing code
- Do not refactor adjacent code while fixing a bug
- Do not create test files unless explicitly asked
- Do not introduce abstractions "for future flexibility"
- Do not modify build configuration without approval

## Code Style

- Direct, minimal, no abstraction for abstraction's sake
- If a function does one thing and is called once, inline it
- Concise variable names
- Comments only where the why isn't obvious from the what
- No boilerplate, scaffolding, or template code "you might need later"
- Prefer explicit over clever
- Prefer flat over nested

## What NOT To Do

- Never add dependencies without explicit approval
- Never refactor working code that wasn't asked about
- Never introduce abstractions for future flexibility
- Never use frameworks when stdlib suffices
- Never explain code you're about to write — just write it
- Never summarize changes after making them unless asked
- Never create files that weren't requested
- Never modify build/dependency manifests without approval
- Never assume the tech stack — read the project first
- Never optimize before it works
- Never use `go` keyword (it's a compile error)
- Never use `+` for text concatenation (use `|`)
- Never use `make()` (use literal syntax)
- Never use `new(T)` (use `&T{}`)