dns
dns CLI for managing DNS records
Star 0
Fork 0
Watch

docs: mark every writing command as writing; skill show/install + generated reference #13

Merged emma.ordner.fyi
targeting main from feature/skill-and-write-marking
Merged opened by and assigned to emma.ordner.fyi
targeting main from feature/skill-and-write-marking

Companion to the atcli change (PR #1 over there): every writing command is now marked as writing in every document an agent might read, and the agent skill ships as a first-class artifact.

What #

  • Every runnable command (22) declares writes: 'network' | 'local' | false on its spec: network for anything that changes DNS at a provider (set, add, remove, zone create/delete/import/copy), local for this-machine-only writes (login, logout, shell, skill install), false for reads (query, list, zone list/export, providers, accounts, config, version).
  • New generated skills/dns/reference.md (built by tools/reference.ts from the command tree — never hand-written): marker line under each writing command's summary, a "Which commands write" section up top, and an exhaustiveness check — the generator refuses to run while any runnable command lacks the declaration, so a future command cannot silently skip classification. A currency test keeps the generated file honest (npm run reference -- --check).
  • skills/dns/SKILL.md gains the Which commands write tables (record mutations flagged with the take-a-domain-offline warning woven into the existing rules).
  • dns skill becomes skill show / skill install (the atcli shape); bare dns skill prints guide + generated reference, --brief for the guide only.
  • packages/dns/README.md gains a What writes section.

Judgment calls (flagged for review) #

  • zone export = false despite -o file: the action reads a zone; the file is redirect-like. Said explicitly in the skill ("with -o it writes a local file, and nothing at any provider").
  • zone copy/import are network unconditionally — without --prune they still set every RRset.
  • shell = local wholesale (bare form only prints), mirroring atcli's completion.
  • Breaking spell: dns skill --install → dns skill install; bare dns skill output is now the full document. Both atcli-mirroring, both README-documented.

Tests #

  • npm run typecheck: pass.
  • npm test: 250 pass, 0 fail, 12 skipped (all pre-existing BIND-absent skips; +1 is the new currency test).
  • npm run reference -- --check: pass.
Commits 1
docs: mark every writing command as writing in README, skill and reference