feat(cmd): add version, plain json, struct inference and schema modes

Assisted-by: GLM 5.3 Flash

docs/CLI.md

@@ -15,37 +15,68 @@ go install sourcedock.dev/petrbalvin/interpres/v2/cmd/interpres-decode@latest
 interpres-decode [flags]
 interpres-decode -encode
 interpres-decode -validate [file ...]
+interpres-decode -validate [directory ...]
+interpres-decode -json
+interpres-decode -struct
+interpres-decode -schema TYPE file.go
+interpres-decode -version
 ```
 
-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`.
+Without `-validate`, `-encode`, `-json` or `-struct` 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.
+arguments either, and the mode flags 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
 quiet on valid documents, which is the shape a CI step wants. The `-` name
-means stdin.
+means stdin. A named directory is walked for `.toml` files, every one of them
+validated, and the walk closes with a summary on stderr naming how many
+documents were checked and how many were invalid.
+
+With `-json` the decoding half prints plain indented JSON instead of the
+tagged form, the shape for people and diffs: the values keep their types as
+JSON sees them, and the date-time wrappers print in their TOML form.
+
+With `-struct` the program reads a TOML document from stdin and prints a Go
+struct definition shaped like it: one field per key in written order, nested
+tables as nested struct types, and an array of tables as a slice. The
+printed type compiles and decodes the document it came from.
+
+With `-schema` the program reads a Go source file and writes a TOML template
+for the named struct type: one key per exported field, the `comment=` tag
+option printed as a comment above it, and the `default=` option as the value
+where one is set. It is the inverse of `-struct`, for config-driven
+applications that generate their example configuration from the type.
+
+`-version` prints the binary's version and exits. The release pipeline builds
+at the tag, so a released binary prints its own tag; a build from a working
+tree prints `(devel)`.
 
 ## Flags
 
 | Flag | Effect |
 |---|---|
-| `-validate` | validate the documents instead of emitting tagged JSON |
+| `-validate` | validate the documents instead of emitting tagged JSON; directories are walked for `.toml` files |
 | `-encode` | read tagged JSON from stdin and write TOML instead |
+| `-json` | with the default mode, print plain indented JSON instead of tagged JSON |
+| `-struct` | infer a Go struct definition from the document on stdin and print it |
+| `-schema TYPE` | write a TOML template for the struct type TYPE from the Go source file named as the first argument |
+| `-version` | print the version and exit |
 | `-h` | print the usage |
 
 ## Exit codes
 
 | Code | Meaning |
 |---|---|
-| `0` | adapter: the document parsed and the tagged JSON was written; encode: the TOML 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; schema, struct, version: the output was written |
 | `1` | adapter: parse error; validate: at least one document is invalid |
 | `2` | a usage error, a read failure, malformed tagged JSON, or a value with no TOML representation |
 
@@ -120,6 +151,52 @@ $ echo $?
 1
 ```
 
+Sweep a whole directory tree of configuration, with the summary the walk
+closes on:
+
+```sh
+$ interpres-decode -validate configs/
+configs/old.toml: interpres: line 3: duplicate key "port"
+checked 14 documents, 1 invalid
+$ echo $?
+1
+```
+
+See the document a `-struct` template would decode:
+
+```sh
+echo 'host = "db"
+port = 5432
+' | ./bin/interpres-decode -struct
+```
+
+```go
+type inferred struct {
+	Host string `toml:"host"`
+	Port int64  `toml:"port"`
+}
+```
+
+Write the template back from the type, comments and defaults included, where
+the Go source declares fields tagged
+`toml:"host,comment=The host to dial,default=example.org"`:
+
+```sh
+./bin/interpres-decode -schema Config config.go
+```
+
+```toml
+# The host to dial
+host = "example.org"
+```
+
+Print the binary's version:
+
+```sh
+$ ./bin/interpres-decode -version
+interpres-decode v2.0.0
+```
+
 Run the official compliance suite against the adapter:
 
 ```sh