Add proof of concept for Json Schema types and JSON input format for CLIs

.gitignore

@@ -1,6 +1,7 @@
 # Distribution
 build/
 documentation.json
+docs.json
 */elm.js
 **/*.elm.js
 *graphqelm-metadata.json

CHANGELOG.md

@@ -9,6 +9,31 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+### Added
+
+- **`Cli.Option.Typed` module** — new option constructors that take a `CliDecoder`
+  for typed CLI parsing and JSON schema generation. Includes `string`, `int`,
+  `float`, and `customDecoder` for custom types.
+- **`Program.toJsonSchema`** — generates a [JSON Schema](https://json-schema.org/)
+  from your CLI configuration, suitable for
+  [MCP tool](https://modelcontextprotocol.io/specification/draft/server/tools)
+  `inputSchema` definitions and
+  [elm-pages script](https://elm-pages.com/docs/elm-pages-scripts) introspection.
+- **JSON input mode** — parsers accept structured JSON in addition to traditional
+  CLI arguments, enabling LLM agents to invoke tools programmatically. The `$cli`
+  object serves as the sentinel, containing positional arguments and subcommand.
+- `x-cli-kind` annotations in JSON schema output (`"keyword"`, `"flag"`,
+  `"keyword-list"`) describing how each option maps to CLI invocation.
+- Schema `description` field includes usage synopsis and invocation instructions.
+- `Option.withDisplayName` for custom metavar display (e.g., `--output-dir <PATH>`).
+- `TypedGreet` example demonstrating the typed options API.
+
+### Changed
+
+- New dependency on `dillonkearns/elm-ts-json` (>= 2.1.2).
+- Improved help text formatting: uppercase metavar names, 80-character line
+  wrapping, description indentation.
+
 ## [4.0.0]
 
 See the [V4 Upgrade Guide](V4-UPGRADE-GUIDE.md) for migration instructions.

README.md

@@ -1,7 +1,11 @@
 # Elm CLI Options Parser
 
 `elm-cli-options-parser` allows you to build command-line options parsers in Elm.
-It uses a syntax similar to `Json.Decode.Pipeline`.
+It uses a syntax similar to `Json.Decode.Pipeline`, with automatic help text
+generation, validation, and [JSON Schema](https://json-schema.org/) output
+for [MCP tool](https://modelcontextprotocol.io/specification/draft/server/tools)
+definitions and [elm-pages script](https://elm-pages.com/docs/elm-pages-scripts)
+introspection.
 
 You can
 play around with `elm-cli-options-parser` in a [live terminal simulation in Ellie here](https://ellie-app.com/8b8QWfcxx4Ca1)!
@@ -95,6 +99,68 @@ git log [--author <author>] [--max-count <max-count>] [--stat] [<revision range>
 
 Note: the `--help` option is a built-in command, so no need to write a `OptionsParser` for that.
 
+## Typed Options & JSON Schema
+
+The [`Cli.Option.Typed`](https://package.elm-lang.org/packages/dillonkearns/elm-cli-options-parser/4.0.0/Cli-Option-Typed/)
+module lets you specify the type of each option (string, int, float, etc.) via a
+`CliDecoder`. This gives you:
+
+- **JSON Schema generation** via `Program.toJsonSchema` — for MCP tool definitions,
+  elm-pages script introspection, or any tooling that needs a machine-readable
+  description of your CLI's inputs
+- **Typed JSON input** — the same parser handles both traditional CLI args and
+  structured JSON, so LLM agents can invoke your tool programmatically
+- **CLI validation** — typed decoders like `int` and `float` automatically reject
+  malformed input
+
+```elm
+import Cli.Option.Typed as Option
+import Cli.OptionsParser as OptionsParser exposing (with)
+import Cli.Program as Program
+
+type alias Options =
+    { name : String
+    , count : Int
+    , verbose : Bool
+    }
+
+programConfig : Program.Config Options
+programConfig =
+    Program.config
+        |> Program.add
+            (OptionsParser.build Options
+                |> with (Option.requiredKeywordArg "name" Option.string)
+                |> with (Option.requiredKeywordArg "count" Option.int)
+                |> with (Option.flag "verbose")
+            )
+```
+
+This parser works with traditional CLI args:
+
+```console
+$ mytool --name hello --count 3 --verbose
+```
+
+And also accepts JSON input (for tool-calling agents):
+
+```json
+{ "name": "hello", "count": 3, "verbose": true, "$cli": {} }
+```
+
+`Program.toJsonSchema "mytool" programConfig` generates a JSON Schema with
+proper types (`"type": "string"`, `"type": "integer"`, etc.) and `x-cli-kind`
+annotations that describe how each option maps to CLI flags.
+
+### When to use `Cli.Option` vs `Cli.Option.Typed`
+
+Use **`Cli.Option.Typed`** when you want JSON schema generation or JSON input support.
+
+Use **`Cli.Option`** (the original API shown in the example above) when you only need
+traditional CLI argument parsing. It's simpler — no decoder argument needed — and
+treats all values as strings, which you then transform with `validateMap`, `map`, etc.
+
+Both modules produce the same `Option` type and work with the same `OptionsParser.with` pipeline.
+
 ## Color Support
 
 The library automatically adds ANSI color codes to help text and error messages when enabled. To enable colors, pass `colorMode: true` in your flags from JavaScript:

elm.json

@@ -1,19 +1,22 @@
 {
     "type": "package",
     "name": "dillonkearns/elm-cli-options-parser",
-    "summary": "Type-safe command line options parsing.",
+    "summary": "Type-safe command line options parsing with JSON schema generation.",
     "license": "BSD-3-Clause",
     "version": "4.0.0",
     "exposed-modules": [
         "Cli.Program",
         "Cli.Option",
         "Cli.OptionsParser",
         "Cli.Validate",
-        "Cli.OptionsParser.BuilderState"
+        "Cli.OptionsParser.BuilderState",
+        "Cli.Option.Typed"
     ],
     "elm-version": "0.19.0 <= v < 0.20.0",
     "dependencies": {
+        "dillonkearns/elm-ts-json": "2.1.2 <= v < 3.0.0",
         "elm/core": "1.0.0 <= v < 2.0.0",
+        "elm/json": "1.1.3 <= v < 2.0.0",
         "elm/regex": "1.0.0 <= v < 2.0.0",
         "elmcraft/core-extra": "2.2.0 <= v < 3.0.0",
         "wolfadex/elm-ansi": "3.0.0 <= v < 4.0.0"

examples/elm.json

@@ -7,20 +7,22 @@
     "elm-version": "0.19.1",
     "dependencies": {
         "direct": {
+            "dillonkearns/elm-ts-json": "2.1.2",
             "elm/browser": "1.0.2",
             "elm/core": "1.0.5",
             "elm/html": "1.0.1",
             "elm/http": "1.0.0",
+            "elm/json": "1.1.4",
             "elm/regex": "1.0.0",
-            "elm-community/list-extra": "8.3.1",
+            "elmcraft/core-extra": "2.3.0",
             "wolfadex/elm-ansi": "3.0.1"
         },
         "indirect": {
             "avh4/elm-color": "1.0.0",
-            "elm/json": "1.1.4",
             "elm/time": "1.0.0",
             "elm/url": "1.0.0",
-            "elm/virtual-dom": "1.0.5"
+            "elm/virtual-dom": "1.0.5",
+            "elm-community/dict-extra": "2.4.0"
         }
     },
     "test-dependencies": {

examples/src/TypedGreet.elm

@@ -0,0 +1,69 @@
+module TypedGreet exposing (main)
+
+{-| A simple example using `Cli.Option.Typed` for typed options with JSON schema support.
+
+This is the typed equivalent of the `Simple.elm` example. The key difference is
+that each option specifies its type via a `CliDecoder`, enabling JSON schema
+generation via `Program.toJsonSchema`.
+
+Try it:
+
+    node -e "require('./create-cli')('TypedGreet')" -- --name "World"
+
+    node -e "require('./create-cli')('TypedGreet')" -- --name "World" --greeting "Hi" --times 3
+
+Or with JSON input:
+
+    node -e "require('./create-cli')('TypedGreet')" -- '{"name": "World", "times": 3, "$cli": {}}'
+
+-}
+
+import Cli.Option.Typed as Option
+import Cli.OptionsParser as OptionsParser
+import Cli.Program as Program
+import Ports
+
+
+type alias GreetOptions =
+    { name : String
+    , greeting : String
+    , times : Int
+    }
+
+
+programConfig : Program.Config GreetOptions
+programConfig =
+    Program.config
+        |> Program.add
+            (OptionsParser.build GreetOptions
+                |> OptionsParser.with (Option.requiredKeywordArg "name" Option.string)
+                |> OptionsParser.with
+                    (Option.optionalKeywordArg "greeting" Option.string
+                        |> Option.withDefault "Hello"
+                    )
+                |> OptionsParser.with
+                    (Option.optionalKeywordArg "times" Option.int
+                        |> Option.withDefault 1
+                    )
+            )
+
+
+init : Flags -> GreetOptions -> Cmd Never
+init flags { name, greeting, times } =
+    List.repeat times (greeting ++ " " ++ name ++ "!")
+        |> String.join "\n"
+        |> Ports.print
+
+
+type alias Flags =
+    Program.FlagsIncludingArgv {}
+
+
+main : Program.StatelessProgram Never {}
+main =
+    Program.stateless
+        { printAndExitFailure = Ports.printAndExitFailure
+        , printAndExitSuccess = Ports.printAndExitSuccess
+        , init = init
+        , config = programConfig
+        }

snapshot-tests/elm.json

@@ -9,10 +9,12 @@
         "direct": {
             "dillonkearns/elm-pages": "10.3.0",
             "dillonkearns/elm-snapshot": "1.0.0",
+            "dillonkearns/elm-ts-json": "2.1.1",
             "elm/core": "1.0.5",
             "elm/json": "1.1.4",
             "elm/regex": "1.0.0",
             "elm-community/list-extra": "8.7.0",
+            "elm-explorations/test": "2.2.1",
             "kraklin/elm-debug-parser": "2.0.0",
             "lue-bird/elm-syntax-format": "1.1.14",
             "miniBill/elm-diff": "1.1.0",
@@ -38,6 +40,7 @@
             "elm/url": "1.0.0",
             "elm/virtual-dom": "1.0.5",
             "elm-community/basics-extra": "4.1.0",
+            "elm-community/dict-extra": "2.4.0",
             "elm-community/maybe-extra": "5.3.0",
             "elmcraft/core-extra": "2.2.0",
             "fredcy/elm-parseint": "2.0.1",