# devns

**Domain lokal `https://<nama>.test` tanpa port untuk macOS.**

```bash
devns add webui 8080
# ✓ https://webui.test → 127.0.0.1:8080 (caddy admin load HTTP 200)
```

Satu CLI yang menyiapkan semuanya: **dnsmasq** (wildcard `*.test` → 127.0.0.1), **Caddy** (satu-satunya pemegang port 80/443, HTTPS otomatis via internal CA), dan opsional **bridge DoH lokal** agar browser dengan *Secure DNS* tetap bisa membuka domain `.test`.

## Kenapa dibutuhkan?

| Tanpa devns | Dengan devns |
|---|---|
| `http://localhost:7337` | `https://pueue.test` |
| Port bentrok antar project | Nama unik per project, tanpa port di URL |
| HTTP polos | HTTPS trusted (cookie `Secure`, service worker, clipboard API jalan) |
| Secure DNS browser mematikan domain lokal | Bridge DoH: `.test` lokal, sisanya tetap terenkripsi ke cloud |

## Install

Butuh: macOS + [uv](https://docs.astral.sh/uv/) + Homebrew.

```bash
git clone https://github.com/apiep/devns && cd devns
uv tool install --editable .
devns init          # sekali saja — minta sudo interaktif 2-3x
devns doh install   # opsional: bridge DoH utk browser secure-DNS
```

`devns init` menyiapkan:

1. `brew install dnsmasq caddy` bila belum ada
2. `/etc/resolver/test` → macOS me-routing TLD `.test` ke 127.0.0.1
3. Blok `address=/.test/127.0.0.1` di `dnsmasq.conf` + service root di :53
4. Caddyfile utama (`import ~/.config/devns/sites/*.caddy`) + service root 80/443
5. CA internal Caddy ke system trust store (`sudo caddy trust`)
6. Bridge DoH (`dnsproxy` dari AdGuard — binary auto-download sesuai OS/arch)

Sehari-hari **tanpa sudo sama sekali**: `add/rm/ls/open/doctor/doh/log`.

## Pakai

```bash
devns add pueue 7337          # daftarkan domain + reload Caddy + cek port
devns add api 3000 --open     # sekalian buka browser
devns ls                      # ● https://pueue.test → 127.0.0.1:7337
devns open pueue              # buka di browser default
devns rm pueue                # hapus (konfirmasi; -y skip)
devns doctor                  # kesehatan: resolver/DNS/Caddy/HTTPS/DoH

devns doh install             # bridge DoH (LaunchAgent user-level)
devns doh status
devns doh log -f              # ikuti log dnsproxy live
```

### Browser dengan Secure DNS

Setelah `devns doh install`, setel Secure DNS ke **Custom**: `https://dns.test:8443/dns-query`.
Query `.test` dijawab lokal, semua query lain diteruskan terenkripsi ke upstream DoH pilihanmu (default OpenDNS).

## Arsitektur

```
Browser ──DoH──> dns.test:8443 (dnsproxy, launchd io.devns.doh)
                   ├─ [/test/] ──> dnsmasq :53 ──> 127.0.0.1
                   └─ lainnya  ──> https://doh.opendns.com/dns-query

Browser ──HTTPS──> Caddy :443 ──reverse_proxy──> 127.0.0.1:<port-app>
        ──HTTP───> Caddy :80  ──308──> HTTPS
                     cert: Caddy Local Authority (tls internal), per-hostname on-demand
```

- **Registry**: `~/.config/devns/registry.yaml` = satu-satunya sumber kebenaran
- **Site files**: `~/.config/devns/sites/<nama>.caddy` (artefak generate; template pakai `flush_interval -1` agar SSE tidak ter-buffer)
- **Reload harian**: admin endpoint Caddy `localhost:2019` dengan header `Content-Type: text/caddyfile`

## MCP server

devns menyertakan server MCP stdio tanpa dependency tambahan:

```bash
hermes mcp add devns --command devns-mcp    # Hermes Agent
# atau konfigurasi MCP client lain (Claude Desktop dsb) dengan command "devns-mcp"
```

Tools: `list_domains`, `add_domain`, `remove_domain`, `check_health`, `doh_status`.

## Skill untuk AI agent

Repo ini menyertakan skill portabel di [`skills/devns/SKILL.md`](skills/devns/SKILL.md) (format agentskills.io / Claude skills). Salin atau symlink ke direktori skills agent-mu.

## Catatan desain (pelajaran nyata)

- **Wildcard `*.test` ditolak verifier modern** — Chrome & curl menolak cert wildcard yang menempel langsung ke TLD walau SAN valid secara RFC. Karena itu cert dibuat **per-hostname on-demand** oleh CA internal Caddy.
- **Port 5353 sudah dipakai mDNSResponder (Bonjour)** → bridge DoH memakai 5335.
- `/etc/resolver/test` membuat resolve *menggantung* (bukan gagal cepat) saat dnsmasq mati — itu tanda resolver aktif, bukan bug.

## License

MIT