dnsmadeeasy 0.4.0 → 1.0.3

data/docs/plans/01-plan-ruby4-baseline.md

@@ -0,0 +1,38 @@
+# 01 Plan: Ruby 4 Baseline
+
+## Stacked PR Metadata
+
+- Plan identifier: `01`
+- Branch: `stack-01-ruby4-baseline`
+- Base branch: `master`
+- PR title: `01: Establish Ruby 4 baseline for dnsmadeeasy 1.0`
+- PR description must reference: `Plan 01 - Ruby 4 Baseline`
+
+## Scope
+
+- Drop Ruby 2 support.
+- Add Ruby 4 support.
+- Bump `DnsMadeEasy::VERSION` to `1.0.0`.
+- Update gem metadata and CI Ruby version.
+- Add the first dependency baseline needed by later PRs only when it is directly required here.
+- Preserve current library behavior.
+
+## Implementation Notes
+
+- Prefer Ruby 4 only with `spec.required_ruby_version = '~> 4.0'` unless we decide public compatibility requires Ruby 3.2+.
+- Add `tsort` explicitly to quiet the Ruby 4.1 default-gem warning from `sym`.
+- Update GitHub Actions from Ruby 2.7 and old `actions/setup-ruby` usage to current `ruby/setup-ruby`.
+
+## RSpec Requirements
+
+- Update or add specs proving `DnsMadeEasy::VERSION == '1.0.0'`.
+- Keep the Ruby 4 keyword-argument compatibility specs passing.
+- Use modern nested `describe`/`context` blocks with block-local `subject`.
+- Use concise one-liner expectations, including `it { ... }` and `its(:property) { ... }` where readable.
+
+## Acceptance Criteria
+
+- `bundle exec rspec` passes on Ruby 4.
+- CI config targets Ruby 4.
+- The gem metadata no longer claims Ruby 2 support.
+- No live DNS Made Easy calls are made.

data/docs/plans/02-plan-dry-cli-launcher.md

@@ -0,0 +1,44 @@
+# 02 Plan: dry-cli Launcher and Aruba Test Harness
+
+## Stacked PR Metadata
+
+- Plan identifier: `02`
+- Branch: `stack-02-dry-cli-launcher`
+- Base branch: `stack-01-ruby4-baseline`
+- PR title: `02: Introduce dry-cli launcher and Aruba harness`
+- PR description must reference: `Plan 02 - dry-cli Launcher and Aruba Test Harness`
+
+## Scope
+
+- Add `dry-cli`.
+- Include `tty-spinner` as a runtime dependency for later threaded zone export/apply progress reporting.
+- Add a `DnsMadeEasy::CLI::Commands` registry.
+- Add `DnsMadeEasy::CLI::Launcher`.
+- Add `DnsMadeEasy::CLI::Commands::Base`.
+- Add a `version` command.
+- Configure Aruba for in-process CLI tests.
+- Update `exe/dme` to call the launcher.
+- Keep `DnsMadeEasy::Runner` temporarily for migration reference.
+
+## Implementation Notes
+
+- Follow the `../githuh` launcher shape, but keep the implementation smaller.
+- All command output must use injected `stdout` and `stderr`.
+- Do not put business logic in the launcher.
+- Do not make zone commands in this PR.
+
+## RSpec Requirements
+
+- Add launcher specs using direct `StringIO` streams.
+- Add Aruba specs for:
+  - `dme --help`
+  - `dme version`
+- Use `subject(:launcher)` or block-local `subject { output }` per describe block.
+- Use `its(:stdout)` style only where the object exposes a clear property; otherwise use `it { is_expected.to ... }`.
+
+## Acceptance Criteria
+
+- `dme --help` is handled through dry-cli.
+- `dme version` prints `1.0.0`.
+- Aruba runs the CLI in-process.
+- Existing library specs still pass.

data/docs/plans/03-plan-account-command.md

@@ -0,0 +1,43 @@
+# 03 Plan: Account Command for Existing API Operations
+
+## Stacked PR Metadata
+
+- Plan identifier: `03`
+- Branch: `stack-03-account-command`
+- Base branch: `stack-02-dry-cli-launcher`
+- PR title: `03: Move existing API operations under account command`
+- PR description must reference: `Plan 03 - Account Command for Existing API Operations`
+
+## Scope
+
+- Add `dme account <operation> [args...]`.
+- Move existing CLI behavior from `DnsMadeEasy::Runner` into a dry-cli command.
+- Preserve output formats where practical.
+- Validate operation names using `DnsMadeEasy::Api::Client.public_operations`.
+- Replace runner specs with Aruba command specs.
+
+## Implementation Notes
+
+- Treat `<operation>` as an argument to one `Account` command.
+- Do not generate one dry-cli class per API method unless the single-command design becomes unworkable.
+- For version 1.0, prefer a clear migration hint for old root operations like `dme domains`.
+- Preserve method arity diagnostics where reasonable.
+
+## RSpec Requirements
+
+- Add Aruba specs for:
+  - `dme account operations`
+  - `dme account domains`
+  - `dme account records_for example.com`
+  - invalid account operation
+  - invalid arity where current behavior provides a useful message
+- Mock `DnsMadeEasy.client`; do not hit the network.
+- Use nested `describe '#call'`, `context 'with valid operation'`, and `context 'with invalid operation'`.
+- Use `subject { output }` for CLI output examples and `its(:exit_status)` if command objects expose it.
+
+## Acceptance Criteria
+
+- Existing API operations are reachable through `dme account`.
+- Old `Runner` can be deleted or made a thin deprecated wrapper.
+- `bundle exec rspec` passes.
+- No live DNS Made Easy calls are made.

data/docs/plans/04-plan-zone-record-model.md

@@ -0,0 +1,48 @@
+# 04 Plan: Typed Zone Record Model
+
+## Stacked PR Metadata
+
+- Plan identifier: `04`
+- Branch: `stack-04-zone-record-model`
+- Base branch: `stack-03-account-command`
+- PR title: `04: Add typed zone record domain model`
+- PR description must reference: `Plan 04 - Typed Zone Record Model`
+
+## Scope
+
+- Add `dry-types`.
+- Add `dry-struct`.
+- Define internal provider-neutral zone record objects.
+- Define record-set and sorting behavior.
+- Keep provider IDs out of serializable zone records.
+
+## Implementation Notes
+
+- Create `DnsMadeEasy::Types`.
+- Support initial record types:
+  - `A`
+  - `AAAA`
+  - `CNAME`
+  - `MX`
+  - `NS`
+  - `PTR`
+  - `SPF`
+  - `SRV`
+  - `TXT`
+- Represent DNS Made Easy metadata separately from record equality.
+- Build deterministic sort keys now because serializer and diff will depend on them.
+
+## RSpec Requirements
+
+- Add specs for valid construction.
+- Add specs for invalid record type, TTL, and required attributes.
+- Add specs for deterministic sorting.
+- Add specs proving provider metadata is separate from record equality.
+- Use `subject(:record) { described_class.new(...) }`.
+- Use `its(:owner) { ... }`, `its(:type) { ... }`, and `it { is_expected.to ... }` one-liners where useful.
+
+## Acceptance Criteria
+
+- Zone records are immutable typed value objects.
+- Invalid input fails before parser/diff/apply logic can use it.
+- `bundle exec rspec` passes.

data/docs/plans/05-plan-zone-parser.md

@@ -0,0 +1,41 @@
+# 05 Plan: Zone File Parser and Validation Command
+
+## Stacked PR Metadata
+
+- Plan identifier: `05`
+- Branch: `stack-05-zone-parser`
+- Base branch: `stack-04-zone-record-model`
+- PR title: `05: Parse and validate standard zone files`
+- PR description must reference: `Plan 05 - Zone File Parser and Validation Command`
+
+## Scope
+
+- Add `dns-zonefile`.
+- Add `dry-monads` and use `Dry::Monads::Result` for parser and validation service results.
+- Add parser adapter at the boundary.
+- Add `dme zone validate FILE`.
+- Convert parser output immediately into internal zone records.
+
+## Implementation Notes
+
+- `aeden/dns-zonefile` is sufficient for v1 parsing of downloaded or standard RFC-style zone files.
+- Parser and validation workflows should return `Success(value)` / `Failure(errors)` rather than raising for expected user-input errors.
+- Do not leak `DNS::Zonefile::*` classes beyond the adapter.
+- Unsupported syntax should produce actionable validation errors.
+- `HTTPRED` is not represented in standard zone files and does not need parser support in v1.
+
+## RSpec Requirements
+
+- Add parser unit specs with fixture zone files.
+- Add Aruba specs for:
+  - valid zone file
+  - invalid zone file
+  - unsupported record type
+- Use `subject(:result) { described_class.new(...).call }` for service specs.
+- Use `its(:records) { ... }`, `its(:errors) { ... }`, and one-liner `it { is_expected.to be_success }` style where available.
+
+## Acceptance Criteria
+
+- `dme zone validate FILE` succeeds for standard fixture zone files.
+- Parser adapter returns internal records only.
+- `bundle exec rspec` passes.

data/docs/plans/06-plan-zone-formatter.md

@@ -0,0 +1,43 @@
+# 06 Plan: Canonical Zone Serializer and Formatter
+
+## Stacked PR Metadata
+
+- Plan identifier: `06`
+- Branch: `stack-06-zone-formatter`
+- Base branch: `stack-05-zone-parser`
+- PR title: `06: Add canonical zone serializer and formatter`
+- PR description must reference: `Plan 06 - Canonical Zone Serializer and Formatter`
+
+## Scope
+
+- Add canonical serializer.
+- Add `dme zone fmt FILE`.
+- Optionally add `dme zone format FILE` as an alias.
+- Normalize whitespace and ordering.
+
+## Normalized Output Rules
+
+- one zone per file
+- explicit owner on every record
+- `$ORIGIN`
+- `$TTL`
+- `@` for zone apex
+- deterministic ordering
+- normalized, aligned whitespace
+- provider-managed SOA omitted
+- apex NS records omitted by default
+- delegated NS records preserved
+
+## RSpec Requirements
+
+- Add golden-file specs for formatter output.
+- Add idempotency spec: parse, serialize, parse, serialize produces byte-identical output.
+- Add specs for apex NS omission and delegated NS preservation.
+- Use `subject(:serialized_zone) { described_class.new(...).to_s }`.
+- Use one-liners for exact matches and property checks where readable.
+
+## Acceptance Criteria
+
+- `dme zone fmt FILE` emits canonical zone text.
+- Already formatted files remain byte-identical.
+- `bundle exec rspec` passes.

data/docs/plans/07-plan-zone-export.md

@@ -0,0 +1,58 @@
+# 07 Plan: Remote Adapter and Zone Export
+
+## Stacked PR Metadata
+
+- Plan identifier: `07`
+- Branch: `stack-07-zone-export`
+- Base branch: `stack-06-zone-formatter`
+- PR title: `07: Export DNS Made Easy records as canonical zone files`
+- PR description must reference: `Plan 07 - Remote Adapter and Zone Export`
+
+## Scope
+
+- Add remote record adapter.
+- Add `dme zone export DOMAIN`.
+- Convert DNS Made Easy API responses to internal zone records.
+- Serialize remote records through the canonical serializer.
+
+## Implementation Notes
+
+- Use the existing API client as the provider boundary.
+- Keep provider IDs separate from exported records.
+- Omit `HTTPRED` from exports.
+- Emit warnings listing omitted `HTTPRED` records.
+- Write zone text to stdout by default.
+- Write warnings to stderr so stdout remains pipe-safe.
+- When export requires multiple independent provider calls, split work into bounded worker-thread chunks.
+- Use one `TTY::Spinner` per active worker/chunk for interactive progress.
+- Use `TTY::Spinner::Multi` for concurrent thread progress:
+  https://github.com/piotrmurach/tty-spinner#5-ttyspinnermulti-api
+- Collect worker results and render final zone output deterministically after all workers finish.
+- Inject a fake/no-op spinner in specs so output remains stable.
+
+## Live Integration Note
+
+Opt-in live specs may use:
+
+- Domain: `isdue.today`
+- DNS Made Easy domain ID: `8218117`
+
+Live specs must be gated by `DNSMADEEASY_LIVE_TESTS=1` or equivalent and must only touch test-owned records.
+
+## RSpec Requirements
+
+- Add unit specs for remote adapter conversion.
+- Add Aruba specs for export using a mocked client.
+- Add specs proving `HTTPRED` is omitted and warning text is emitted.
+- Add specs for chunked parallel execution with deterministic result ordering.
+- Add specs for failed worker chunks and aggregated error reporting.
+- Add optional live integration specs marked/skipped unless explicitly enabled.
+- Use `subject(:records)`, `subject(:output)`, and `its(:warnings)` where the object model supports it.
+
+## Acceptance Criteria
+
+- `dme zone export example.com` produces deterministic zone output with mocked data.
+- Provider metadata is not serialized.
+- Independent provider reads can run concurrently with bounded worker threads.
+- Progress is displayed with `TTY::Spinner` during interactive export work.
+- `bundle exec rspec` passes without live credentials.

data/docs/plans/08-plan-zone-diff.md

@@ -0,0 +1,42 @@
+# 08 Plan: Zone Diff Engine and Plan Command
+
+## Stacked PR Metadata
+
+- Plan identifier: `08`
+- Branch: `stack-08-zone-diff-plan`
+- Base branch: `stack-07-zone-export`
+- PR title: `08: Add zone diff engine and plan command`
+- PR description must reference: `Plan 08 - Zone Diff Engine and Plan Command`
+
+## Scope
+
+- Add diff engine.
+- Add execution plan objects.
+- Add text and JSON plan renderers.
+- Add `dme zone plan FILE`.
+
+## Implementation Notes
+
+- Default behavior:
+  - create missing records
+  - update modified records only when unambiguous
+  - never delete records
+- Multiple records with the same owner/type must be modeled as record sets.
+- Prefer conservative create/delete reporting over unsafe update matching.
+- Ambiguous changes should be reported as requiring manual intervention.
+
+## RSpec Requirements
+
+- Add unit specs for create, update, no-op, skipped delete, and ambiguous cases.
+- Add golden-file specs for text plan output.
+- Add JSON output specs.
+- Add Aruba specs for `dme zone plan FILE` with mocked remote state.
+- Use `subject(:plan) { described_class.new(...).call }`.
+- Use `its(:creates)`, `its(:updates)`, `its(:skipped_deletes)`, and one-liner expectations.
+
+## Acceptance Criteria
+
+- Plan output is deterministic.
+- Deletes are skipped by default.
+- Ambiguous changes are not applied silently.
+- `bundle exec rspec` passes.

data/docs/plans/09-plan-zone-apply.md

@@ -0,0 +1,69 @@
+# 09 Plan: Safe Zone Apply Command
+
+## Stacked PR Metadata
+
+- Plan identifier: `09`
+- Branch: `stack-09-zone-apply`
+- Base branch: `stack-08-zone-diff-plan`
+- PR title: `09: Apply zone plans safely`
+- PR description must reference: `Plan 09 - Safe Zone Apply Command`
+
+## Scope
+
+- Add `dme zone apply FILE`.
+- Reuse the same planner used by `zone plan`.
+- Execute creates and updates through the existing API client.
+- Keep deletes opt-in.
+- Split independent API operations into bounded worker-thread chunks.
+- Use one `TTY::Spinner` per active worker/chunk for interactive progress.
+- Use `TTY::Spinner::Multi` for concurrent thread progress:
+  https://github.com/piotrmurach/tty-spinner#5-ttyspinnermulti-api
+- Keep final execution summaries deterministic even when worker completion order varies.
+
+## Safety Rules
+
+- Never delete by default.
+- Never delete SOA records.
+- Never delete apex NS records in v1.
+- Require confirmation unless `--yes` is provided.
+- Fail before applying if parsing or validation fails.
+- Report partial failures clearly.
+- Parallelize only actions proven independent by the plan.
+- Aggregate worker errors by action/chunk.
+
+## Options (flags)
+
+-a | --add-only     Ensures that only new records are being added, especially if the zone file does not contain all existing records
+-d | --delete-only  Applies only the deletion part of the plan
+-m | --merge        Default mode - compare existing DNS Zone with the provided, and merge the differences, turning them into add/update or delete actions.
+
+## Live Integration Note
+
+Opt-in live specs may use:
+
+- Domain: `isdue.today`
+- DNS Made Easy domain ID: `8218117`
+
+Live specs must only mutate predictable test records such as `_dnsmadeeasy-test.isdue.today` and must clean them up.
+
+## RSpec Requirements
+
+- Add unit specs for executor behavior.
+- Add Aruba specs for confirmation flow.
+- Add specs for `--yes`.
+- Add specs for delete refusal without `--delete`.
+- Add specs for threaded chunk execution.
+- Add specs using fake/no-op spinner objects.
+- Add specs proving final summaries are deterministic.
+- Add optional gated live integration specs for create/update/delete of test-owned records.
+- Use `subject(:result) { described_class.new(...).call }`.
+- Use `its(:applied_actions)`, `its(:failed_actions)`, and concise one-liners where useful.
+
+## Acceptance Criteria
+
+- Apply executes the current plan.
+- Apply refuses destructive operations unless explicitly allowed.
+- Independent actions can run concurrently with bounded worker threads.
+- Progress is displayed with `TTY::Spinner` during interactive apply work.
+- Default test suite never touches live DNS.
+- `bundle exec rspec` passes.

data/docs/plans/10-plan-docs-cleanup.md

@@ -0,0 +1,55 @@
+# 10 Plan: Documentation, Migration Notes, and Cleanup
+
+## Stacked PR Metadata
+
+- Plan identifier: `10`
+- Branch: `stack-10-docs-cleanup`
+- Base branch: `stack-09-zone-apply`
+- PR title: `10: Document dnsmadeeasy 1.0 CLI and zone workflow`
+- PR description must reference: `Plan 10 - Documentation, Migration Notes, and Cleanup`
+
+## Scope
+
+- Update README examples for the new command tree.
+- Document Ruby 4 and version 1.0 breaking changes.
+- Document the zone-file workflow.
+- Remove deprecated runner leftovers if still present.
+- Ensure command examples are represented by smoke specs where practical.
+
+## Documentation Requirements
+
+Include examples for:
+
+```text
+dme account domains
+dme account records_for example.com
+dme zone export example.com > example.com.zone
+dme zone validate example.com.zone
+dme zone fmt example.com.zone
+dme zone plan example.com.zone
+dme zone apply example.com.zone --yes
+```
+
+Document that `HTTPRED` is omitted from standard zone exports in v1, with warnings.
+
+Document the live integration test domain:
+
+- Domain: `isdue.today`
+- DNS Made Easy domain ID: `8218117`
+
+## RSpec Requirements
+
+- Add or update CLI smoke specs for README command examples where practical.
+- Add specs for migration messages if old commands are intentionally unsupported.
+- Keep specs in the modern style:
+  - nested `describe`/`context`
+  - block-local `subject`
+  - concise `it { ... }`
+  - `its(:property) { ... }` where it improves readability
+
+## Acceptance Criteria
+
+- README accurately reflects the 1.0 CLI.
+- Old docs for root-level operations are removed or marked as legacy.
+- All specs pass.
+- The stacked PR series is ready to merge from `01` through `10`.

data/docs/plans/11-plan-zone-cli-arguments.md

@@ -0,0 +1,114 @@
+# 11 Plan: Consistent Zone CLI Arguments (and the Trailing-Dot 404)
+
+## Stacked PR Metadata
+
+- Plan identifier: `11`
+- Branch: `11-zone-cli-arguments`
+- Base branch: `master`
+- PR title: `11: Make domain a positional argument across zone commands`
+- PR description must reference: `Plan 11 - Consistent Zone CLI Arguments`
+
+## The Bug That Started This
+
+Found live, while writing the kig.re blog post announcing 1.0.1:
+
+```bash
+$ dmez zone export kig.re --output=kig.re.zone   # works
+$ dmez zone plan kig.re.zone                     # 404 "Not Found"
+$ dmez zone plan kig.re.zone --domain=kig.re     # works
+```
+
+`Plan#call` and `Apply#build_plan_context` fall back to the parsed zone's
+origin when `--domain` is absent:
+
+```ruby
+plan_domain = domain || desired_result.value!.origin
+```
+
+The parser returns the origin exactly as written in the file: `kig.re.`,
+with the RFC-mandated trailing dot. That FQDN goes straight into
+`records_for("kig.re.")`, the API has no such domain, 404.
+
+## The Design Decision
+
+The deeper problem is inconsistency, not the dot. Today:
+
+- `dmez zone export DOMAIN` — domain is a positional argument
+- `dmez zone plan FILE --domain=NAME` — domain is an option
+- `dmez zone apply FILE --domain=NAME` — domain is an option
+
+Decision (Konstantin): **domain is consistently an argument, never an
+option.** Zone files are provided by flags unless one is required for the
+command; a required file becomes a required argument following the domain.
+
+Applied to the command tree:
+
+| Command | New shape | Change |
+| ------- | --------- | ------ |
+| `zone export` | `dmez zone export DOMAIN [--output=FILE]` | none (already correct; output is optional, stays a flag, defaults to stdout) |
+| `zone plan` | `dmez zone plan DOMAIN FILE` | file was the only argument; domain was a flag |
+| `zone apply` | `dmez zone apply DOMAIN FILE [modes]` | same |
+| `zone validate` | `dmez zone validate FILE` | none (no provider involved, no domain to speak of) |
+| `zone fmt` | `dmez zone fmt FILE` | none |
+
+With `domain` required, origin inference is deleted rather than fixed. The
+bug becomes structurally impossible: there is nothing left to infer.
+
+## $ORIGIN Becomes a Cross-Check
+
+Deleting the inference does not mean ignoring `$ORIGIN`. Plan and apply now
+verify that the zone file agrees with the domain argument, before any API
+call is made:
+
+- Normalize both sides: strip one trailing dot, compare case-insensitively.
+  (`kig.re` == `kig.re.` == `KIG.RE.`)
+- If the file has an `$ORIGIN` and it disagrees with the domain argument,
+  fail fast with both values shown. Diffing `foo.com` against
+  `bar.com.zone` should be an error, not a surprise apply.
+- A zone file without `$ORIGIN` skips the check.
+
+This converts yesterday's bug into a safety feature.
+
+## Swapped-Argument Detection
+
+`dmez zone plan valid.zone example.com` is the muscle-memory mistake the
+new argument order invites. Two cheap guards:
+
+- When the zone file path does not exist, say so plainly
+  (`Zone file not found: example.com`) instead of an unhandled `Errno::ENOENT`.
+- When, additionally, the *domain* argument names an existing file, append:
+  `It looks like the arguments are swapped. Usage: dmez zone plan DOMAIN FILE`.
+
+## Out of Scope
+
+- `dme account` argument shapes.
+- `validate`/`fmt` error-handling polish beyond what exists.
+- Version bump: this is a breaking CLI change one day after 1.0.1 shipped
+  (16 downloads). Recommend releasing as **1.1.0** with the README calling
+  out the new shapes; the maintainer bumps the version at release time.
+
+## RSpec Requirements
+
+Update `spec/lib/dns_made_easy/cli/zone_aruba_spec.rb`:
+
+- Rewrite every `zone plan` / `zone apply` invocation to
+  `dme zone plan example.com valid.zone ...` (domain first, file second).
+- Add: plan with origin `example.com.` (trailing dot in file) and domain
+  argument `example.com` succeeds — the normalization test.
+- Add: plan with a mismatched origin fails, names both values, makes no
+  API call.
+- Add: plan with swapped arguments fails with the swap hint.
+- Add: plan with a missing zone file fails with `Zone file not found`.
+- Keep specs in the modern style: nested `describe`/`context`, block-local
+  `subject`, concise `it { ... }`, `its(:property) { ... }` where it reads
+  better.
+
+## Acceptance Criteria
+
+- `dmez zone plan kig.re kig.re.zone` round-trips against production with
+  `No changes.` (verified live, read-only).
+- The 1.0.1 failure mode (`zone plan FILE` → 404) can no longer be
+  expressed: the CLI rejects the invocation with a usage error.
+- Mismatched `$ORIGIN` vs domain argument fails before any API request.
+- README zone examples reflect the new shapes.
+- Full spec suite passes; rubocop clean.