Home Explore Help
Sign In
paul
/
mama-dns-tool
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Branch: main
Branches Tags
mama-dns-tool
/
AGENTS.md

AGENTS.md 5.4 KB
Permalink History Raw

AGENTS.md

CLI for Schlundtech DNS. Go, cobra. Read README.md first — it is the source of truth for what the tool does.

Rules

  • Docs and code must never contradict. Every command in README.md must exist, with the flags and output described. If you change the CLI, update README.md in the same change. Verify with go run . <command> --help.
  • Go only. No other language, no script substitutes.
  • gopls is the diagnostic source of truth. Do not guess at type errors. Run gopls check <file> (or gopls definition / gopls references when you need to navigate). Fix what gopls reports; do not suppress.
  • cobra for the CLI. One command per file under cmd/. Every command needs Short, Long, and a complete Example in its help text. No hand-rolled flag parsing.
  • Errors go to stderr, data goes to stdout. Anything pipeable must not be polluted by log output.
  • Never log or echo credentials.

Layout

main.go                entrypoint
cmd/                   root.go, credentials.go, output.go, one file per command
internal/api/          the gateway client: XML types, tasks, record logic

internal/api is the only place that speaks HTTP to the gateway. Commands must not build requests themselves. This is a personal tool — do not add packages beyond this; shared helpers belong in cmd/.

Workflow

go build              # writes ./schlundtech-dns — run that, not `go build ./...`
go test ./...
gopls check ./...        # must be clean before you stop

go build ./... deliberately writes nothing: with more than one package it only compiles as a check. Use bare go build, or go run . <command> to skip the build step entirely.

Credentials

Read from .env in the working directory, falling back to the process environment. godotenv parses the file, but the precedence is ours: a real environment variable always wins, so a one-off override never needs a file edit. Never commit .env; .env.example is the committed template. Never log or echo a credential, and keep a test that proves the password cannot reach an error message. Writes to DNS are public and propagate immediately — every mutating command needs a --dry-run flag.

Generated files

.opencode/skill/, .opencode/agent/, .opencode/command/ are generated from the maister submodule. Never edit them; run node tools/build-maister-opencode.mjs and node tools/verify-maister-opencode.mjs after git -C maister pull.

References

  • The gateway is AutoDNS. gateway.schlundtech.de is Schlundtech's hostname for InterNetX's AutoDNS platform — same host as gateway.autodns.com (the IP reverse-resolves to it). Use gateway.schlundtech.de as the default endpoint.
  • XML is the transport. Schlundtech's own web portal is also built on the AutoDNS JSON API (cloud.schlundtech.com/services/backend/zone/... returns the documented stid/status/object/data envelope with the same task codes: S0205 zone inquire, S0210 axfr, S0225 zone list). Do not mistake that for a public API: it authenticates by portal session cookie only — no BasicAuth — so it is the frontend's private backend, versioned with Schlundtech's release cycle, and unusable without driving a browser login plus 2FA. api.autodns.com/v1 is the documented JSON API but rejects a Schlundtech login with EF1322002 "Application could not be found.": the BasicAuth username must be a registered application on InterNetX's side (x-autodns-agent: PHOENIX does not change this). Build against the XML gateway, which takes the credentials a Schlundtech customer actually has.
  • Context ID is 10. Verified against the real account: zone responses carry "owner":{"context":10,"user":"<id>"}. Context 1 is the demo system, 4 the PersonalAutoDNS live system — so a demo run needs SCHLUNDTECH_CONTEXT=1, not 10.
  • 2FA is a <token> in the auth block, XML only. The Authentication page lists exactly two options for XML: credentials (user/context/password) and 2FA. The token is a six-digit TOTP per RFC 6238, not an opaque string, and it expires roughly every 30 seconds. The JSON API has no token at all — it uses BasicAuth plus an X-Domainrobot-Context header, which is a second reason not to build on it here.
  • The XML gateway answers HTTP 200 even on failure. Verified: a request with bad credentials returns HTTP 200 and this body: response/result/msg/{code:EF00202, text:"User does not exist or password incorrect.", object:{type:user, value:<user>}}, with the sibling status/{code:E00000, type:error} staying generic. Never branch on the HTTP status code — parse the body, treat result/msg/code as the real error and result/status/type as the success flag. Non-2xx from this host is an nginx 404 (wrong path), never an application error. Whether the 3 req/s limit comes back as an HTTP 429 or as an in-body error is still unverified.
  • Zone read = task 0205. Record replace = task 0202001 (rr_rem + rr_add in one transaction, system_ns required). Zone's own NS is the first NS in nameServers (a.k.a. virtualNameServer).
  • Record shape is {name, type, value} plus ttl, where the apex is the empty name. nameServers is the NS set. Task 0210 returns a plain zone file.
  • Working implementations: https://github.com/jurica/ddns-schlundtech (Go), https://github.com/couchtyp/certbot-dns-schlundtech, https://github.com/wosc/schlund-ddns