diff --git a/draft.md b/draft.md index 256331d..985e47e 100644 --- a/draft.md +++ b/draft.md @@ -13,6 +13,7 @@ This document is licensed under the MIT license | Date | Author | Description | |------|--------|-------------| +| 2026-04-19 | Bob Lail | Made the root command an instance of [Command Object](#command-object) | | 2026-03-24 | Bob Lail | Add default value for `arity` to [Argument Object](#argument-object) | | 2025-07-15 | Patrik Svensson | Added `interactive` to root command and commands | | 2025-07-16 | Patrik Svensson | Added [Metadata Object](#metadata-object) | @@ -102,15 +103,9 @@ This is the root object of the OpenCLI Description. | Field Name | Type | Default Value | Description | |------------|:----:|---------------|-------------| | opencli | `string` | - | **REQUIRED** The OpenCLI version number | +| command | [Command Object](#command-object) | - | **REQUIRED** The root command | | info | [CliInfo Object](#cliinfo-object) | - | **REQUIRED** Information about the CLI | | conventions | [Conventions Object](#conventions-object) | - | The conventions used by the CLI | -| arguments | [[Argument Object](#argument-object)] | - | Root command arguments | -| options | [[Option Object](#option-object)] | - | Root command options | -| commands | [[Command Object](#command-object)] | - | Root command sub commands | -| exitCodes | [[ExitCode Object](#exitcode-object)] | - | Root command exit codes | -| examples | [`string`] | - | Examples of how to use the CLI | -| interactive | `bool` | `false` | Indicates whether or not the command requires interactive input | -| metadata | [[Metadata Object](#metadata-object)] | - | Custom metadata | #### CliInfo Object diff --git a/examples/dotnet.json b/examples/dotnet.json index 2e09554..ac92ea0 100644 --- a/examples/dotnet.json +++ b/examples/dotnet.json @@ -1,6 +1,56 @@ { "$schema": "../schema.json", "opencli": "0.1", + "command": { + "name": "dotnet", + "options": [ + { + "name": "--help", + "aliases": [ "-h" ], + "description": "Display help." + }, + { + "name": "--info", + "description": "Display .NET information." + }, + { + "name": "--list-sdks", + "description": "Display the installed SDKs." + }, + { + "name": "--list-runtimes", + "description": "Display the installed runtimes." + } + ], + "commands": [ + { + "name": "build", + "arguments": [ + { + "name": "PROJECT | SOLUTION", + "description": "The project or solution file to operate on. If a file is not specified, the command will search the current directory for one.", + } + ], + "options": [ + { + "name": "--configuration", + "aliases": [ "-c" ], + "description": "The configuration to use for building the project. The default for most projects is 'Debug'.", + "arguments": [ + { + "name": "CONFIGURATION", + "required": true, + "arity": { + "minimum": 1, + "maximum": 1 + } + } + ] + } + ] + } + ] + }, "info": { "title": "dotnet", "version": "9.0.1", @@ -10,52 +60,5 @@ "identifier": "MIT", "url": "https://opensource.org/license/mit" } - }, - "options": [ - { - "name": "--help", - "aliases": [ "-h" ], - "description": "Display help." - }, - { - "name": "--info", - "description": "Display .NET information." - }, - { - "name": "--list-sdks", - "description": "Display the installed SDKs." - }, - { - "name": "--list-runtimes", - "description": "Display the installed runtimes." - } - ], - "commands": [ - { - "name": "build", - "arguments": [ - { - "name": "PROJECT | SOLUTION", - "description": "The project or solution file to operate on. If a file is not specified, the command will search the current directory for one.", - } - ], - "options": [ - { - "name": "--configuration", - "aliases": [ "-c" ], - "description": "The configuration to use for building the project. The default for most projects is 'Debug'.", - "arguments": [ - { - "name": "CONFIGURATION", - "required": true, - "arity": { - "minimum": 1, - "maximum": 1 - } - } - ] - } - ] - } - ] + } } diff --git a/schema.json b/schema.json index c6b476b..219942b 100644 --- a/schema.json +++ b/schema.json @@ -7,6 +7,10 @@ "type": "string", "description": "The OpenCLI version number" }, + "command": { + "$ref": "#/$defs/Command", + "description": "The root command" + }, "info": { "$ref": "#/$defs/CliInfo", "description": "Information about the CLI" @@ -14,60 +18,91 @@ "conventions": { "$ref": "#/$defs/Conventions", "description": "The conventions used by the CLI" - }, - "arguments": { - "type": "array", - "items": { - "$ref": "#/$defs/Argument" - }, - "description": "Root command arguments" - }, - "options": { - "type": "array", - "items": { - "$ref": "#/$defs/Option" - }, - "description": "Root command options" - }, - "commands": { - "type": "array", - "items": { - "$ref": "#/$defs/Command" - }, - "description": "Root command sub commands" - }, - "exitCodes": { - "type": "array", - "items": { - "$ref": "#/$defs/ExitCode" - }, - "description": "Root command exit codes" - }, - "examples": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Examples of how to use the CLI" - }, - "interactive": { - "type": "boolean", - "description": "Indicates whether or not the command requires interactive input" - }, - "metadata": { - "type": "array", - "items": { - "$ref": "#/$defs/Metadata" - }, - "description": "Custom metadata" } }, "required": [ "opencli", + "command", "info" ], "description": "The OpenCLI description", "$defs": { + "Command": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The command name" + }, + "aliases": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true, + "description": "The command aliases" + }, + "options": { + "type": "array", + "items": { + "$ref": "#/$defs/Option" + }, + "description": "The command options" + }, + "arguments": { + "type": "array", + "items": { + "$ref": "#/$defs/Argument" + }, + "description": "The command arguments" + }, + "commands": { + "type": "array", + "items": { + "$ref": "#/$defs/Command" + }, + "description": "The command's sub commands" + }, + "exitCodes": { + "type": "array", + "items": { + "$ref": "#/$defs/ExitCode" + }, + "description": "The command's exit codes" + }, + "description": { + "type": "string", + "description": "The command description" + }, + "hidden": { + "type": "boolean", + "default": false, + "description": "Whether or not the command is hidden" + }, + "examples": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Examples of how to use the command" + }, + "interactive": { + "type": "boolean", + "default": false, + "description": "Indicate whether or not the command requires interactive input" + }, + "metadata": { + "type": "array", + "items": { + "$ref": "#/$defs/Metadata" + }, + "description": "Custom metadata" + } + }, + "required": [ + "name" + ] + }, "CliInfo": { "type": "object", "properties": { @@ -116,57 +151,6 @@ } } }, - "Argument": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The argument name" - }, - "required": { - "type": "boolean", - "description": "Whether or not the argument is required" - }, - "arity": { - "$ref": "#/$defs/Arity", - "default": { - "minimum": 1, - "maximum": 1 - }, - "description": "The argument arity. Arity defines the minimum and maximum number of argument values" - }, - "acceptedValues": { - "type": "array", - "items": { - "type": "string" - }, - "description": "A list of accepted values" - }, - "group": { - "type": "string", - "description": "The argument group" - }, - "description": { - "type": "string", - "description": "The argument description" - }, - "hidden": { - "type": "boolean", - "default": false, - "description": "Whether or not the argument is hidden" - }, - "metadata": { - "type": "array", - "items": { - "$ref": "#/$defs/Metadata" - }, - "description": "Custom metadata" - } - }, - "required": [ - "name" - ] - }, "Option": { "type": "object", "properties": { @@ -176,6 +160,7 @@ }, "required": { "type": "boolean", + "default": false, "description": "Whether or not the option is required" }, "aliases": { @@ -223,68 +208,45 @@ "name" ] }, - "Command": { + "Argument": { "type": "object", "properties": { "name": { "type": "string", - "description": "The command name" - }, - "aliases": { - "type": "array", - "items": { - "type": "string" - }, - "uniqueItems": true, - "description": "The command aliases" + "description": "The argument name" }, - "options": { - "type": "array", - "items": { - "$ref": "#/$defs/Option" - }, - "description": "The command options" + "required": { + "type": "boolean", + "default": false, + "description": "Whether or not the argument is required" }, - "arguments": { - "type": "array", - "items": { - "$ref": "#/$defs/Argument" + "arity": { + "$ref": "#/$defs/Arity", + "default": { + "minimum": 1, + "maximum": 1 }, - "description": "The command arguments" + "description": "The argument arity. Arity defines the minimum and maximum number of argument values" }, - "commands": { + "acceptedValues": { "type": "array", "items": { - "$ref": "#/$defs/Command" + "type": "string" }, - "description": "The command's sub commands" + "description": "A list of accepted values" }, - "exitCodes": { - "type": "array", - "items": { - "$ref": "#/$defs/ExitCode" - }, - "description": "The command's exit codes" + "group": { + "type": "string", + "description": "The argument group" }, "description": { "type": "string", - "description": "The command description" + "description": "The argument description" }, "hidden": { "type": "boolean", "default": false, - "description": "Whether or not the command is hidden" - }, - "examples": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Examples of how to use the command" - }, - "interactive": { - "type": "boolean", - "description": "Indicate whether or not the command requires interactive input" + "description": "Whether or not the argument is hidden" }, "metadata": { "type": "array", @@ -367,11 +329,13 @@ "properties": { "minimum": { "type": "integer", + "default": 1, "minimum": 0, "description": "The minimum number of values allowed" }, "maximum": { "type": "integer", + "default": 1, "minimum": 0, "description": "The maximum number of values allowed" } diff --git a/typespec/main.tsp b/typespec/main.tsp index 2744ce8..6320cbd 100644 --- a/typespec/main.tsp +++ b/typespec/main.tsp @@ -9,32 +9,14 @@ model OpenCLI { @doc("The OpenCLI version number") opencli: string; + @doc("The root command") + command: Command; + @doc("Information about the CLI") info: CliInfo; @doc("The conventions used by the CLI") conventions?: Conventions; - - @doc("Root command arguments") - arguments?: Argument[]; - - @doc("Root command options") - options?: Option[]; - - @doc("Root command sub commands") - commands?: Command[]; - - @doc("Root command exit codes") - exitCodes?: ExitCode[]; - - @doc("Examples of how to use the CLI") - examples?: string[]; - - @doc("Indicates whether or not the command requires interactive input") - interactive?: boolean = false; - - @doc("Custom metadata") - metadata?: Metadata[]; } model CliInfo {