cto-legends · module specification · infrastructure · v0.1.1
legends-cloudflare: Preview-First Cloudflare DNS Automation & Readback Verification
Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.
GitHub Repository (https://github.com/avalonreset/legends-cloudflare) · Handoff: cto-legends handoff legends-cloudflare
legends-cloudflare (v0.1.1) is a zero-dependency Python 3.11+ standard-library CLI and source-cited DNS operations vault built over the official Cloudflare API v4 (https://api.cloudflare.com/client/v4). While any LLM can synthesize a raw curl call to Cloudflare's DNS API, production DNS incidents happen when an agent modifies the wrong zone, overwrites an existing proxy (orange-cloud) or TTL setting with a PUT request, deletes an entire round-robin record set instead of a single record ID, or assumes a timed-out write failed and blindly retries.
Architecturally, legends-cloudflare enforces a deterministic preview-then-apply contract for single-record changes across six supported record types (A, AAAA, CNAME, TXT, MX, and NS). Running upsert or delete without --apply executes read-only API queries, validates ASCII/punycode label formatting and IP/hostname syntax, snapshots the existing record's before-state, preserves omitted TTL/proxy/priority settings, and computes a canonical sha256 plan digest. Applying a mutation requires --apply --confirm-zone <zone> --confirm-plan <sha256>, re-verifies remote state immediately before sending a targeted POST, PATCH, or DELETE, and performs an immediate GET readback to confirm that both changed and preserved fields match expectations.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
A raw Frontier LLM operating via ad-hoc shell scripts or an unconstrained MCP server lacks transactional guardrails against DNS misconfiguration. In Cloudflare's API, updating a record without carrying forward existing metadata or distinguishing between multiple records sharing the same (name, type) tuple (such as multiple TXT verification records, MX servers, or round-robin A records) leads to silent service outages for web traffic, email delivery, and domain verification.
- SHA-256 Plan Binding & Pre-Write Drift Detection: make_plan() builds a canonical JSON structure containing schema, zone, zone_id, normalized FQDN name, type, action (create, update, delete, or noop), before snapshot, and payload, hashed with SHA-256. apply_plan() recomputes the plan from live state, verifies --confirm-zone and --confirm-plan, and aborts if the target record changed or a new record appeared since preview.
- Ambiguity Refusal & Exact-ID Deletion: When multiple DNS records share the same name and type (e.g., multiple TXT or A records), upsert refuses to guess and fails with 'Multiple records match; select --record-id explicitly.' Furthermore, delete requires an explicit 32-hex --record-id and verifies that the exact ID belongs to the specified zone, name, and type—never deleting a matching record set.
- PATCH Setting Preservation & Proxy/TTL Invariants: Updating an existing record uses HTTP PATCH rather than replacement, automatically preserving existing TTL, proxied status, and MX priority whenever those flags are omitted. It also enforces Cloudflare's protocol rule before network write: proxied A/AAAA/CNAME records must use automatic TTL (--ttl 1), rejecting invalid combinations offline.
- Immediate Post-Write Readback & Pagination Integrity: After every POST, PATCH, or DELETE, apply_plan() queries the Cloudflare API to verify that every preserved and updated field matches the expected state (or that a deleted record ID is absent). Meanwhile, Client.paged() validates 32-hex resource IDs, detects duplicate IDs across pages during concurrent edits, and fails closed if pagination metadata is incomplete.
CLI Subcommands & Capability Surface
legends-cloudflare doctor [--live] | zones | nameservers --zone ZONE — Offline Readiness & Scoped Zone Discovery: doctor checks local Python 3.11+ readiness offline without credentials, while doctor --live verifies CLOUDFLARE_API_TOKEN reachability and reports accessible_zone_count (explicitly noting dns_read_or_write_access: not_checked). zones and nameservers inspect zone status and assigned Cloudflare nameservers for migration and cutover verification.legends-cloudflare records --zone ZONE [--name NAME] [--type A|AAAA|CNAME|TXT|MX|NS] — Paginated DNS Record Inventory with Duplicate Detection: Retrieves full DNS record snapshots (id, type, name, content, ttl, proxied, priority, comment, tags, settings, modified_on) across all pages (50 records/page up to 1,000 pages). Normalizes @ and relative labels to the zone FQDN and fails explicitly if duplicate record IDs or truncated pagination occur.legends-cloudflare upsert --zone ZONE --name NAME --type TYPE --content VALUE [--record-id ID] [--ttl N] [--proxied|--dns-only] [--priority N] — Preview-First Single-Record DNS Upsert: Performs read-only API queries to construct a reviewed change plan with writes_sent: 0. Validates IPv4/IPv6 addresses via Python's ipaddress module, checks ASCII hostname labels, preserves existing TTL/proxy/priority settings when omitted, detects no-op updates (action: noop), and outputs a SHA-256 confirmation hash.legends-cloudflare upsert ... --apply --confirm-zone ZONE --confirm-plan SHA256_FROM_PREVIEW — Hash-Confirmed Apply with PATCH Preservation & Readback: Executes the reviewed create (POST) or update (PATCH) only when --apply, --confirm-zone, and --confirm-plan match the live rebuilt plan hash. Re-verifies the record snapshot immediately prior to mutation and runs an immediate GET readback to confirm that all modified and preserved attributes match.legends-cloudflare delete --zone ZONE --name NAME --type TYPE --record-id 32_HEX_ID [--apply --confirm-zone ZONE --confirm-plan SHA256] — Guarded Exact-ID Record Deletion: Requires the exact 32-character hexadecimal --record-id alongside matching --zone, --name, and --type to preview a deletion. Upon hash-locked confirmation, sends a single DELETE /zones/{zone_id}/dns_records/{record_id} request and verifies via readback that the record ID is no longer present in the zone.wiki/index.md | knowledge/cloudflare/pack.json (legends.knowledge-pack/v1) — DNS Migration Runbooks & Attachable Empire Knowledge Pack: Includes source-cited runbooks for DNS operations, token scoping, troubleshooting, and full-setup nameserver migrations (DNSSEC DS record handling, authoritative vs. recursive resolution checks, and private change-receipt templates), attachable to a legends-empire vault.
Raw Frontier LLM vs. legends-cloudflare Execution Matrix
- DNS Record Updates (Upsert): Raw LLM (Sends blind PUT/PATCH requests that reset orange-cloud proxy status, overwrite custom TTLs, or fail when multiple TXT/A records share a hostname.) vs. Module (Previews before-state and proposed payload first, preserves omitted TTL/proxy/priority fields via PATCH, and requires --record-id whenever multiple records match.) — Preview JSON returns action, before snapshot, payload, and sha256 with writes_sent: 0.
- Record Deletion Safety: Raw LLM (Filters by name/type and loops over results to delete records, risking accidental deletion of apex MX, SPF/DKIM TXT, or sibling round-robin records.) vs. Module (Mandates an explicit 32-hex --record-id verified against zone, name, and type, plus --apply, --confirm-zone, and --confirm-plan SHA-256 confirmation.) — Post-DELETE API readback confirms the exact record_id is absent and returns verified: true.
- Concurrent Edit & Race Protection: Raw LLM (Applies changes from stale conversation context without checking if another operator or ACME client modified the zone in the meantime.) vs. Module (Rebuilds the plan and re-fetches the target record immediately before mutation, aborting if the live snapshot differs from the previewed before-state.) — CloudflareError raised with zero writes sent if sha256 or pre-write GET snapshot diverges.
- Transport & Error Boundaries: Raw LLM (Uses arbitrary API paths, follows redirects with Bearer headers, or automatically retries timed-out POST requests (creating duplicate DNS records).) vs. Module (Restricts requests to /zones and /dns_records via regex PATH, disables proxies and redirects (NoRedirect), caps responses at 16 MiB, and never auto-retries writes.) — Actionable sanitized stderr JSON without leaking provider response bodies or tokens.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Does legends-cloudflare upsert modify DNS records immediately when invoked?
- No. Running upsert or delete without --apply performs only read-only API queries and returns a JSON preview containing the current before-state snapshot, the proposed payload, the action (create, update, delete, or noop), and a sha256 digest with writes_sent: 0. No mutation is sent unless you repeat the command with --apply, --confirm-zone, and the matching --confirm-plan SHA-256 hash.
- How does legends-cloudflare avoid breaking existing Cloudflare proxy (orange-cloud) or TTL settings?
- When updating an existing A, AAAA, CNAME, TXT, MX, or NS record, omitting --ttl, --proxied/--dns-only, or --priority preserves the record's current values via a targeted HTTP PATCH request. After the write completes, apply_plan() performs an immediate GET readback and verifies that both the updated fields and all preserved fields match the expected state.
- Why does API readback verification not guarantee global DNS propagation or application health?
- API readback confirms only that Cloudflare's authoritative control plane accepted and persisted the exact record state. As documented in wiki/dns-operations.md, full operational verification requires separate checks: querying Cloudflare's authoritative nameservers, waiting for recursive resolver TTL caches to expire, and testing the target web, TLS, or mail service directly.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.