diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5598428 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,97 @@ +# Contributing to kasapi-cli + +Thanks for your interest in contributing. This document collects the conventions a contributor needs to know on top of the in-tree references. + +## Before you start + +- This project is **not affiliated with All-Inkl.com**. The KAS-API surface is reverse-engineered from the public documentation at and from real responses captured in `testdata/`. +- The roadmap in [README.md](README.md#roadmap) shows which endpoints are already wired up. If you want to claim an unchecked item, please open an issue first so work is not duplicated. +- Bug reports and PRs that touch the KAS-API contract should reference the relevant doc page and, where possible, attach a redacted response fixture. + +## Authoritative references + +Read these before designing changes — do not duplicate their content into new docs: + +- [`AGENTS.md`](AGENTS.md) — top-level operating rules: always run `gofmt`/`goimports`, `go vet`, `golangci-lint`, `go test`; clean-architecture layering; no business logic depending on transport. +- [`docs/go/ARCHITECTURE.md`](docs/go/ARCHITECTURE.md) — `cmd/kasapi-cli` wires; domain/use cases in `internal//`; SOAP/HTTP/CLI are outer-layer adapters. +- [`docs/go/STYLE_GUIDE.md`](docs/go/STYLE_GUIDE.md) — Go style. +- [`docs/go/PATTERNS.md`](docs/go/PATTERNS.md) — recurring patterns (e.g. the per-package `Caller` interface, fixture-backed decoders, `cli.Tabular`). +- [`docs/go/LINTING.md`](docs/go/LINTING.md) — the CI gate set. + +## Development setup + +Prerequisites: + +- Go (latest stable; the version pinned in `go.mod`). +- [`golangci-lint`](https://golangci-lint.run/) matching the version used in CI. +- A working GnuPG key — commits to `main` must be signed (the branch is protected with `required_signatures`). + +Standard loop: + +```sh +go fmt ./... +go vet ./... +golangci-lint run ./... +go test ./... +go test -race ./... # for packages with concurrency +go build ./cmd/kasapi-cli +``` + +## Vertical-slice pattern + +Each KAS endpoint is added as a single vertical slice; do not split it across modules. A new endpoint typically needs: + +1. **Type & decoder** in `internal//.go` — typed Go value + `Decode` mapping the SOAP `ns2:Map` / `Array` payload, plus a per-package `Caller` interface so tests do not need network setup. +2. **Client method** on the package's `*Client` (e.g. `(c *Client) Get(ctx, name)`). +3. **Test** in `internal//_test.go` — fixture-backed mapping tests + a `fakeCaller` for the client method (assert the action name and any params). +4. **Fixture** in `testdata//_response_success.xml` (and `_request.xml` if useful). The fixtures are real captured responses with secrets redacted — they are the source of truth for response shape. +5. **CLI subcommand** in `internal/cli/.go`, registered in `cmd/kasapi-cli/main.go`. +6. **CHANGELOG entry** under `## [Unreleased] / ### Added` (or `### Fixed`, etc.). One paragraph, ending with `Closes #` if applicable. +7. **Roadmap update** in [README.md](README.md#roadmap) — flip the corresponding `- [ ]` to `- [x]`. + +When the response shape differs between list and singular views (e.g. `get_domains` with vs. without `domain_name`), prefer one struct with `omitempty` on the view-specific fields rather than two structs. + +## Language + +- Commits, CHANGELOG entries, code comments, doc.go strings, and PR text are in **English**. +- Where a file already uses ASCII fallbacks (`ae/oe/ue/ss`), keep that style consistent in the same file; otherwise use real umlauts. + +## Commit conventions + +- **[Conventional Commits](https://www.conventionalcommits.org/):** `feat:` for new features, `fix:` for bug or schema corrections, `docs:` for documentation- or CHANGELOG-only changes, `chore:` for build/tooling/repo hygiene, `test:` for test-only changes, `refactor:` for structural changes without behavior change. +- **Signed commits.** Do not skip hooks (no `--no-verify`, no `--no-gpg-sign`). On a hook failure, fix the underlying cause and create a **new** commit — do not `--amend`. +- **No `Co-Authored-By` trailer.** Maintainers do not use the Claude Code default trailer; please omit it as well. +- **Selective `git add`.** Stage only files that belong to the current slice; never `git add -A` or `git add .`. Excluded by default: `.claude/`, local settings, unrelated fixtures, IDE/OS noise, secrets, captured KAS responses that have not been redacted. + +## Branches and pull requests + +```sh +git checkout -b feature/ # new functionality +git checkout -b fix/ # bug or schema correction +git checkout -b docs/ # docs only +git checkout -b chore/ # tooling / repo hygiene +``` + +PR body: keep it short. Summary block describing *what*, not *how*. No "Test plan" section, no generated-by footer. If an issue is open, reference it with `Closes #` so the project item flips to "Done" automatically on merge. + +CI must be green before merge. The CI workflow runs `go fmt` (check-only), `go vet`, `golangci-lint`, and `go test` (with `-race` where applicable). + +`main` is protected with `required_signatures` + `enforce_admins` + `linear_history`. The GitHub UI / `gh pr merge` strips signatures and is therefore **not** used for this repo. Merging is done by the maintainer via a locally-rebased, signed fast-forward push to `main`. As a contributor you do not need to do this — you only need to keep your branch rebased on `main` and your commits signed. + +## Code review + +Findings are classified: + +- **Blocker** — outright wrong: bug, undefined behavior, KAS-API schema mismatch, security issue, broken invariant. Must be fixed before merge. +- **Should** — consistency / readability / small footguns. Fix quickly if cheap; otherwise capture as a follow-up issue. +- **Nice-to-have** — cosmetic, style, or speculative. Recorded as a grouped follow-up issue but not a merge blocker. + +Corrections from review land on a dedicated `fix/` branch via a separate PR; the loop ends only when no Blocker or Should-finding remains. + +## Reporting security issues + +Please do **not** open a public issue for security vulnerabilities. Contact the maintainer privately (see the commit author email or the `LICENSE` copyright holder) with a description, reproduction steps, and an assessment of impact. + +## License + +By contributing, you agree that your contributions will be licensed under the project's [BSD 3-Clause License](LICENSE). diff --git a/README.md b/README.md index 39a7830..0d3fb64 100644 --- a/README.md +++ b/README.md @@ -22,33 +22,14 @@ ## Status -Early development. No functional Go code yet — the repository currently holds documentation, agent guidance, and recorded KAS-API response fixtures used to drive offline parser tests. See the project board for the active roadmap. +Early development. The transport, authentication, configuration, and several read modules are wired up; many write paths and the remaining read endpoints are still pending — see [ROADMAP.md](ROADMAP.md) for the current state. The repository also ships recorded KAS-API response fixtures under `testdata/` that drive offline parser tests. -## What it does (planned) +## What it does -`kasapi-cli` is a command-line client for the All-Inkl KAS-API. It wraps the SOAP/`ns2:Map` wire format the API uses, handles the `KasAuth` credential-token flow (plain or session, optional 2FA), enforces the `KasFloodDelay` between calls, and exposes read and write operations for the resources documented at : - -- accounts, account settings, account resources -- server information, space, space usage, traffic -- top-level domains, domains, subdomains, DNS settings -- mail accounts, mail forwards, mail standard filters, mailing lists -- databases, FTP users, Samba users, DDNS users -- cronjobs, directory protection, software install entries -- sessions (`add_session`, `delete_session`) - -## Endpoints - -- API: -- Auth: - -## Configuration (planned) - -`kasapi-cli` reads credentials from a config file or from environment variables (`KAS_LOGIN`, `KAS_AUTHDATA`, `KAS_AUTHTYPE`). Profiles let you switch between accounts. Secrets never appear in `--help` or in default log output. +`kasapi-cli` is a command-line client for the All-Inkl KAS-API. It wraps the SOAP/`ns2:Map` wire format the API uses, handles the `KasAuth` credential-token flow (plain or session, optional 2FA), enforces the `KasFloodDelay` between calls, and exposes read and write operations for the resources documented at . ## Building -Once the Go module is bootstrapped: - ```sh go build ./cmd/kasapi-cli go test ./... @@ -56,8 +37,8 @@ go test ./... ## Repository layout -- `cmd/kasapi-cli/` — CLI entry point (planned). -- `internal/` — domain types, transport, mappers (planned). +- `cmd/kasapi-cli/` — CLI entry point. +- `internal/` — domain types, transport, mappers, CLI wiring; one package per KAS resource (see `internal/account/`, `internal/domain/`, `internal/dns/`, …) plus shared infrastructure (`internal/soap`, `internal/api`, `internal/auth`, `internal/transport`, `internal/session`, `internal/config`, `internal/cli`). - `testdata/` — recorded KAS-API SOAP responses; the source of truth for response shape, used by offline parser tests. - `docs/go/` — Go style, architecture, patterns, and linting reference for this repo. - `.claude/skills/kasapi-cli-git-workflow/` — git/PR/merge mechanics enforced for this project. @@ -66,7 +47,11 @@ go test ./... ## Contributing -Read `AGENTS.md` and `docs/go/ARCHITECTURE.md` before opening a PR. The git workflow (branch naming, commit style, PR shape, CI gate, signed FF-merge) is captured in `.claude/skills/kasapi-cli-git-workflow/SKILL.md`; the review-loop conventions (finding classification, re-review cycle) live next to it in `.claude/skills/kasapi-cli-code-review/SKILL.md`. +See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, coding conventions, the vertical-slice pattern used per KAS endpoint, the commit/PR workflow, and the code-review loop. + +## Roadmap + +The current state of the KAS-API surface — implemented vs. pending — is tracked in [ROADMAP.md](ROADMAP.md). ## License diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..90ac129 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,60 @@ +# Roadmap + +This file tracks the KAS-API surface implemented by `kasapi-cli`, grouped by domain. Checked items are wired up end-to-end (typed module + CLI subcommand + fixture-backed tests); unchecked items are still pending. + +The list is kept in sync with the code on `main`. To claim an unchecked item, please open an issue first so work is not duplicated — see [CONTRIBUTING.md](CONTRIBUTING.md). + +## Transport & authentication + +- [x] SOAP / `ns2:Map` decoder (`internal/soap`) +- [x] `KasFloodDelay` enforcement and retry on `flood_delay` errors +- [x] `KasAuth` credential-token flow (plain + session, optional 2FA via `--otp`) +- [x] Persistent session-token cache (`sessions.toml`) survives across CLI invocations +- [x] Session lifetime extension (`update_lifetime`) +- [ ] Standalone `add_session` / `delete_session` subcommands + +## Configuration + +- [x] TOML config file with named profiles and `default_profile` selection +- [x] Environment overrides (`KAS_LOGIN`, `KAS_AUTHDATA`, `KAS_AUTHTYPE`, `KAS_PROFILE`) +- [x] Secrets are never echoed in `--help` or default log output + +## Accounts & server + +- [x] `account get` (`get_accounts`, `get_accountsettings`, `get_accountresources`) +- [x] `server get` (`get_server_information`) + +## Usage + +- [x] `usage space` (`get_space`) +- [x] `usage space-detail` (`get_space_usage`) +- [x] `usage traffic` (`get_traffic`) + +## Domains, subdomains, DNS + +- [x] `domains list` / `domains get ` (`get_domains`, with `domain_name` filter) +- [x] `subdomains list` / `subdomains get ` (`get_subdomains`, with `subdomain_name` filter) +- [x] `tlds list` (`get_topleveldomains`) +- [x] `dns list --domain [--nameserver ]` (`get_dns_settings`) +- [ ] DNS write paths (`add_dns_settings`, `update_dns_settings`, `delete_dns_settings`) +- [ ] Domain write paths (`add_domain`, `update_domain`, `delete_domain`, transfer flow) +- [ ] Subdomain write paths (`add_subdomain`, `update_subdomain`, `move_subdomain`, `delete_subdomain`) + +## Mail + +- [ ] Mail accounts (`get_mailaccounts`, `add_mailaccount`, `update_mailaccount`, `delete_mailaccount`) +- [ ] Mail forwards (`get_mailforwards`, `add_mailforward`, `update_mailforward`, `delete_mailforward`) +- [ ] Mail standard filters (`get_mailstandardfilter`, `update_mailstandardfilter`) +- [ ] Mailing lists (`get_mailinglists`, `add_mailinglist`, `update_mailinglist`, `delete_mailinglist`) + +## Hosting resources + +- [ ] Databases (`get_databases`, `add_database`, `update_database`, `delete_database`) +- [ ] FTP users (`get_ftpusers`, `add_ftpuser`, `update_ftpuser`, `delete_ftpuser`) +- [ ] Samba users (`get_sambausers`, `add_sambauser`, `update_sambauser`, `delete_sambauser`) +- [ ] DDNS users (`get_ddnsusers`, `add_ddnsuser`, `update_ddnsuser`, `delete_ddnsuser`) +- [ ] Cronjobs (`get_cronjobs`, `add_cronjob`, `update_cronjob`, `delete_cronjob`) +- [ ] Directory protection (`get_directoryprotection`, `add_directoryprotection`, `update_directoryprotection`, `delete_directoryprotection`) +- [ ] Software install entries (`get_softwareinstall`, `add_softwareinstall`, `delete_softwareinstall`) +- [ ] SSL certificate management (`add_lets_encrypt_csr`, `update_ssl_certificate`, …) +- [ ] Filesystem helpers (`chown`, `symlink`)