feat(cmd): add the encoder mode to the toml-test adapter

Assisted-by: DeepSeek V4.1 Flash

docs/ARCHITECTURE.md

@@ -7,9 +7,9 @@ source tree; nothing is aspirational.
 
 interpres is one public library package, one command, and one example. The
 library implements the whole of TOML 1.1, decoding and encoding, in the
-standard library alone; the command wraps the parser for the toml-test
-compliance harness, against which it stands at 214 valid and 467 invalid cases
-with zero failures; the example demonstrates the API.
+standard library alone; the command wraps the parser and the encoder for the
+toml-test compliance harness, against which it stands at 214 valid, 467 invalid
+and 214 encoder cases with zero failures; the example demonstrates the API.
 
 ```mermaid
 flowchart TD
@@ -36,7 +36,7 @@ strict validation.
 | Path | Responsibility |
 |---|---|
 | `.` (package `interpres`) | The whole library. `interpres.go` declares the exported surface (`Parse`, `Unmarshal`, `Marshal`, the `*Context` variants, `Decoder`, `Encoder`, `Marshaler`, `Unmarshaler`, `SyntaxError`, the local date-time types); everything below it is unexported. |
-| `cmd/interpres-decode` | The toml-test adapter. Reads TOML on stdin, writes tagged JSON on stdout. Owns no parsing logic. |
+| `cmd/interpres-decode` | The toml-test adapter, both directions. Reads TOML on stdin, writes tagged JSON on stdout; with `-encode` it reads tagged JSON and writes TOML. Owns no parsing logic and no emission logic. |
 | `examples/basic` | A runnable tour of the API. Documentation in executable form, not part of the library. |
 
 Inside the library package, one file owns one concern:

docs/CLI.md

@@ -1,8 +1,9 @@
 # Command line
 
 The reference below is taken from the program itself. `interpres-decode` is
-the toml-test harness adapter, and it also validates documents. Install it
-with Go itself, no release assets involved:
+the toml-test harness adapter in both directions, decoding TOML into tagged
+JSON and encoding tagged JSON back into TOML, and it also validates documents.
+Install it with Go itself, no release assets involved:
 
 ```sh
 go install sourcedock.dev/petrbalvin/interpres/v2/cmd/interpres-decode@latest
@@ -12,14 +13,20 @@ go install sourcedock.dev/petrbalvin/interpres/v2/cmd/interpres-decode@latest
 
 ```sh
 interpres-decode [flags]
+interpres-decode -encode
 interpres-decode -validate [file ...]
 ```
 
-Without `-validate` the program is the toml-test adapter: it takes no
-arguments, reads one TOML document from stdin, and writes the toml-test
-tagged-JSON form to stdout. Build it locally with `just build`, which
-compiles it into `bin/interpres-decode`, or run it straight from the module
-directory with `just run`.
+Without `-validate` or `-encode` the program is the decoding half of the
+toml-test adapter: it takes no arguments, reads one TOML document from stdin,
+and writes the toml-test tagged-JSON form to stdout. Build it locally with
+`just build`, which compiles it into `bin/interpres-decode`, or run it
+straight from the module directory with `just run`.
+
+With `-encode` the direction is reversed: the program reads a tagged-JSON
+description from stdin and writes the TOML document it describes to stdout,
+which is the shape toml-test expects of an encoder command. It takes no
+arguments either, and `-validate` and `-encode` cannot be combined.
 
 With `-validate` the program parses each named file instead, or stdin when no
 file is named, and prints one line per invalid document to stderr. It is
@@ -31,15 +38,16 @@ means stdin.
 | Flag | Effect |
 |---|---|
 | `-validate` | validate the documents instead of emitting tagged JSON |
+| `-encode` | read tagged JSON from stdin and write TOML instead |
 | `-h` | print the usage |
 
 ## Exit codes
 
 | Code | Meaning |
 |---|---|
-| `0` | adapter: the document parsed and the tagged JSON was written; validate: every document parsed |
+| `0` | adapter: the document parsed and the tagged JSON was written; encode: the TOML was written; validate: every document parsed |
 | `1` | adapter: parse error; validate: at least one document is invalid |
-| `2` | a usage error, a read failure, or a value with no tagged representation |
+| `2` | a usage error, a read failure, malformed tagged JSON, or a value with no TOML representation |
 
 ## Wire format
 
@@ -66,6 +74,14 @@ wrapped in an object with a `type` and a `value`:
 | local date | `date-local` | `1979-05-27` |
 | local time | `time-local` | `07:32:00.999999` |
 
+The `-encode` mode reads exactly this form back. Two properties of it are
+worth knowing. A float whose value has no fraction and no exponent is written
+as a bare integer string, `{"type": "float", "value": "1"}`, so there the tag
+decides the type and not the literal. And the form cannot tell an array of
+tables from a value array of inline tables, so the adapter writes the header
+form, `[[a]]`, for an array whose every element is a JSON object; a mixed
+array keeps the value form.
+
 ## Examples
 
 Echo a small document through the adapter:
@@ -78,8 +94,18 @@ port = 9090
 ' | ./bin/interpres-decode
 ```
 
-The output is the equivalent value tree as one JSON object. Validate the
-TOML files of another repository in CI:
+The output is the equivalent value tree as one JSON object. Turn a description
+back into TOML with `-encode`:
+
+```sh
+echo '{"title": {"type": "string", "value": "hello"}}' | ./bin/interpres-decode -encode
+```
+
+```toml
+title = "hello"
+```
+
+Validate the TOML files of another repository in CI:
 
 ```sh
 interpres-decode -validate config.toml deploy/example.toml
@@ -101,5 +127,7 @@ just toml-test
 ```
 
 That recipe needs the `toml-test` binary on `PATH`, installed with
-`go install github.com/toml-lang/toml-test/v2/cmd/toml-test@v2.2.0`. The full
+`go install github.com/toml-lang/toml-test/v2/cmd/toml-test@v2.2.0`. It runs
+the suite in both directions: the decoder against the valid and invalid
+corpora, and the encoder against the tagged JSON of the valid one. The full
 reference for the library itself is [API.md](API.md).

docs/DEVELOPMENT.md

@@ -41,7 +41,7 @@ prints the same list.
 | `just run` | `go run ./cmd/interpres-decode`, reads TOML from stdin |
 | `just dev` | the same run, for iterating |
 | `just example` | `go run ./examples/basic`, the usage tour |
-| `just toml-test` | builds the adapter and runs the official toml-test compliance suite against it |
+| `just toml-test` | builds the adapter and runs the official toml-test compliance suite against it, decoder and encoder |
 | `just coverage-html` | `just test`, then `go tool cover -html` into `coverage.html` |
 | `just install` | builds, then copies the binary into `~/.local/bin` (`BINDIR` overrides) |
 | `just uninstall` | removes the installed binary |