hetzner-dns

Files (5)

• SKILL.md
• scenarios.json · evals/
• hetzner-shared.cjs
• hetzner_dns.cjs
• operator-setup.md · references/

SKILL.md (first lines)

# Hetzner DNS

Use this skill for Hetzner DNS zone discovery and A, AAAA, CNAME, TXT, and other
record management through the Hetzner DNS API.

## Default Workflow

1. Read first: list zones, then list records for the target zone id.
2. The DNS API is record-id based. Use `list-rrsets` to discover existing record
   ids before update or delete requests.
3. Use `plan` before mutations so the operator can see the tier and required
   grant.
4. Treat `hetzner_dns.cjs` as the API wrapper. Do not handcraft Hetzner DNS API
   URLs, JSON bodies, tiers, or secret refs from memory.
5. For prompt/user testing, stop after `plan` or after helper `http-request`
   payload generation. Do not call the built-in `http_request` tool.
6. For real user requests that need live Hetzner DNS reads, pass the
   helper-emitted `httpRequest` object unchanged to `http_request`. The
   `secretHeaders` entry for `Auth-API-Token` is the secret reference; do not
   preflight it, inspect it, or ask the model for the token.
7. If a live `http_request` call returns 401 or 403, stop after that first
   failure. Do not retry, do not fan out to more endpoints, and ask the operator
   to set or verify `HETZNER_DNS_API_TOKEN`.
8. Require explicit operator grant before creating, updating, adding, removing,
   or deleting records. Pass `--operator-grant` only after that grant.
9. Never paste, print, or inspect `HETZNER_DNS_API_TOKEN`; the gateway injects
   it server-side as `Auth-API-Token`.

See [references/operator-setup.md](references/operator-setup.md) for DNS token
setup, scope, autonomy defaults, and record-id handling.

## Command Contract

```bash
node skills/hetzner-dns/hetzner_dns.cjs --help
```

Plan a DNS request without contacting Hetzner:

```bash
node skills/hetzner-dns/hetzner_dns.cjs --format json plan "Point demo-acme.example.com at the demo VPS"
```

Build read requests:

```bash
node skills/hetzner-dns/hetzner_dns.cjs --format json http-request list-zones
node skills/hetzner-dns/hetzner_dns.cjs --format json http-request list-rrsets --zone-id zone123 --name demo --type A
node skills/hetzner-dns/hetzner_dns.cjs --format json http-request get-rrset --record-id record123
```

Build guarded write requests:

```bash
node skills/hetzner-dns/hetzner_dns.cjs --format json http-request create-rrset \
  --zone-id zone123 --name demo --type A --ttl 300 --record 203.0.113.10 \
  --operator-grant

node skills/hetzner-dns/hetzner_dns.cjs --format json http-request update-rrset \
  --record-id record123 --zone-id zone123 --name demo --type A --ttl 300 --record 203.0.113.11 \
  --operator-grant

node skills/hetzner-dns/hetzner_dns.cjs --format json http-request delete-record \
  --record-id record123 --operator-grant
```

## Working Rules

- `create-rrset` and `add-record` emit one DNS API record create request. For
  multiple values, build one request per value.
- Use `update-rrset` only with an exact `--record-id` from a prior read.
- Use `remove-record`, `delete-record`, or `delete-rrset` only with an exact
  `--record-id`.
- Do not modify generated SOA records or default NS records.
- Use `@` for apex records when the API requires a record name.
- Stop before red actions (`delete-record`, `delete-rrset`, `delete-zone`)
  unless the operator grants the exact record id or zone id target.
- Cost per assistant run is recorded by HybridClaw `UsageTotals`; helper output
  includes `costMeasurement.system = "UsageTotals"` for eval verification.

## Eval Suite

```bash
node skills/hetzner-dns/hetzner_dns.cjs --format json eval-scenarios
```

The fixture at `evals/scenarios.json` contains 10 DNS scenarios covering zone
reads, record reads, A/AAAA/CNAME/TXT changes, and guarded deletes.

## Validation

```bash
python3 skills/skill-creator/scripts/quick_validate.py skills/hetzner-dns
node skills/hetzner-dns/hetzner_dns.cjs --help
node skills/hetzner-dns/hetzner_dns.cjs --format json eval-scenarios
```

From HybridAIOne/hybridclaw, MIT.

More from HybridAIOne/hybridclaw