Write operations

[chmmou]

Umbrella tracker for the v0.2.0 write phase. The original scope has been split into per-resource vertical-slice issues so each can land as its own PR; this issue stays open until all children are closed and serves as the single board entry for the write phase.

Status (2026-05-30)

• Progress: the cross-cutting prerequisite is fully in place — feat(cli): destructive-write confirmation infrastructure (--yes / interactive prompt) #109 (confirmation gate), plus feat(cli): structured write-action audit log #131 (structured write-audit log) and feat(cli): --dry-run for write commands #132 (--dry-run), all closed and now wired by every landed write slice. Slices done: feat(mail): mailforward write endpoints — add / update / delete #115 (mailforward), feat(mail): mailinglist write endpoints — add / update / delete #117 (mailinglist), feat(cronjob): write endpoints — add / update / delete #118 (cronjob), feat(ftpuser): write endpoints — add / update / delete #119 (ftpuser), feat(sambauser): write endpoints — add / update / delete #120 (sambauser), feat(ddnsuser): write endpoints — add / update / delete #121 (ddnsuser), feat(database): write endpoints — add / update / delete #122 (database), feat(mail): mailaccount write endpoints — add / update / delete #114 (mailaccount), feat(mail): mailstandardfilter write endpoints — add / delete #116 (mailstandardfilter), feat(directoryprotection): write endpoints — add / update / delete #123 (directoryprotection) — 10 of 16 resource slices. Each lands through the shared internal/kaswrite post-call seam.
• Fixture coverage is already complete for every action listed below (commit 1ef564e, PR test: restructure KAS API fixtures into per-package folders #22). Each action has matching _request.xml, _response_success.xml, and _response_failed_<reason>.xml files in its per-package folder under testdata/.
• Open question for the FTP slice: add_ftpusers plural-vs-add_ftpuser singular. Resolved in feat(ftpuser): write endpoints — add / update / delete #119: the live KAS action is add_ftpuser (singular). add_ftpusers is only the internal PHP function name in the docs; the doc example URL, both request fixtures and the success-response request echo all use the singular form, so no fixture change was needed.

Cross-cutting prerequisite

Every destructive command must require an explicit confirmation (or --yes). The shared confirmation helper + flag lands first:

• feat(cli): destructive-write confirmation infrastructure (--yes / interactive prompt) #109 — feat(cli): destructive-write confirmation infrastructure (--yes / interactive prompt)

Per-resource vertical slices

Each item is one PR, follows kasapi-cli-vertical-slice, and depends on #109.

• feat(account): write endpoints — add / update / delete + settings #110 — feat(account): write endpoints — add / update / delete + settings (add_account, update_account, delete_account, update_accountsettings, update_superusersettings)
• feat(domain): write endpoints — add / update / delete / move #111 — feat(domain): write endpoints — add / update / delete / move (add_domain, update_domain, delete_domain, move_domain)
• feat(subdomain): write endpoints — add / update / delete / move #112 — feat(subdomain): write endpoints — add / update / delete / move (add_subdomain, update_subdomain, delete_subdomain, move_subdomain)
• feat(dns): write endpoints — add / update / delete / reset settings #113 — feat(dns): write endpoints — add / update / delete / reset settings (add_dns_settings, update_dns_settings, delete_dns_settings, reset_dns_settings)
• feat(mail): mailaccount write endpoints — add / update / delete #114 — feat(mail): mailaccount write endpoints — add / update / delete (add_mailaccount, update_mailaccount, delete_mailaccount — add splits the address into local_part/domain_part and generates the mail_login; password key splits mail_password→mail_new_password; delete uses the louder "permanently delete" verb)
• feat(mail): mailforward write endpoints — add / update / delete #115 — feat(mail): mailforward write endpoints — add / update / delete (add_mailforward, update_mailforward, delete_mailforward)
• feat(mail): mailstandardfilter write endpoints — add / delete #116 — feat(mail): mailstandardfilter write endpoints — add / delete (add_mailstandardfilter, delete_mailstandardfilter — no update_mailstandardfilter, so add is wholesale-replace and both add and delete are gated; delete takes only mail_login and removes the whole chain; known PHP sizeof() quirk on delete documented with verification via mail accounts get <login> → mail_spamfilter)
• feat(mail): mailinglist write endpoints — add / update / delete #117 — feat(mail): mailinglist write endpoints — add / update / delete (add_mailinglist, update_mailinglist, delete_mailinglist)
• feat(cronjob): write endpoints — add / update / delete #118 — feat(cronjob): write endpoints — add / update / delete (add_cronjob, update_cronjob, delete_cronjob)
• feat(ftpuser): write endpoints — add / update / delete #119 — feat(ftpuser): write endpoints — add / update / delete (add_ftpuser — singular, resolved; update_ftpuser, delete_ftpuser)
• feat(sambauser): write endpoints — add / update / delete #120 — feat(sambauser): write endpoints — add / update / delete (add_sambauser — docs wrongly say samba_new_password, real create key is samba_password, fixture corrected; update_sambauser, delete_sambauser)
• feat(ddnsuser): write endpoints — add / update / delete #121 — feat(ddnsuser): write endpoints — add / update / delete (add_ddnsuser, update_ddnsuser, delete_ddnsuser — no _new_password split: both actions use dyndns_password; update_ddnsuser accepts undocumented-but-verified dyndns_target_ipv4 / dyndns_target_ipv6, fixture is the authoritative contract)
• feat(database): write endpoints — add / update / delete #122 — feat(database): write endpoints — add / update / delete (add_database, update_database, delete_database — database_allowed_hosts is optional, empty = any-host wildcard)
• feat(directoryprotection): write endpoints — add / update / delete #123 — feat(directoryprotection): write endpoints — add / update / delete (add_directoryprotection, update_directoryprotection, delete_directoryprotection)
• feat(softwareinstall): add_softwareinstall #124 — feat(softwareinstall): add_softwareinstall (add_softwareinstall — no update/delete in the API)
• feat(filesystem): symlink / chown / ssl write helpers #125 — feat(filesystem): symlink / chown / ssl write helpers (add_symlink, update_chown, update_ssl)

Reference

• Per-action contract: https://kasapi.kasserver.com/dokumentation/phpdoc/ (files/<kas_action>-inc.html).
• Response-shape source of truth: testdata/<module>/*.xml.