@twin.org/cli-core 0.0.3-next.8 → 0.0.3

package/docs/examples.md

@@ -1 +1,82 @@
-# @twin.org/cli-core - Examples
+# CLI Core Examples
+
+Use these snippets to compose clear command line workflows with consistent output, argument parsing and file handling.
+
+## CLIDisplay
+
+```typescript
+import { CLIDisplay } from '@twin.org/cli-core';
+
+CLIDisplay.header('Data Import', '1.2.0');
+CLIDisplay.section('Validation');
+CLIDisplay.value('Records', 128);
+CLIDisplay.warning('2 rows have missing optional fields');
+CLIDisplay.done();
+```
+
+## CLIParam
+
+```typescript
+import { CLIParam } from '@twin.org/cli-core';
+
+const parsedCount = CLIParam.integer('count', '25');
+const parsedDebug = CLIParam.boolean('debug', 'true');
+const parsedUrl = CLIParam.url('endpoint', 'https://api.example.org');
+
+console.log(parsedCount + 1); // 26
+console.log(parsedDebug); // true
+console.log(parsedUrl.host); // api.example.org
+```
+
+## CLIBase
+
+```typescript
+import { CLIBase } from '@twin.org/cli-core';
+import type { Command } from 'commander';
+
+class ToolCli extends CLIBase {
+  protected getCommands(program: Command): Command[] {
+    return [program.command('status').action(() => {})];
+  }
+}
+
+const cli = new ToolCli();
+const exitCode = await cli.execute(
+  {
+    appName: 'tool-cli',
+    title: 'Tool CLI',
+    version: '1.0.0'
+  },
+  './locales',
+  ['node', 'tool-cli', 'status']
+);
+
+console.log(exitCode); // 0
+```
+
+## CLIUtils
+
+```typescript
+import { CLIUtils } from '@twin.org/cli-core';
+
+console.log(await CLIUtils.fileExists('./config/import.json')); // true
+const config = await CLIUtils.readJsonFile<{ source: string }>('./config/import.json');
+await CLIUtils.writeEnvFile('./dist/import.env', {
+  SOURCE: config.source
+});
+console.log(config.source); // ./data/source.json
+```
+
+## CLIOptions
+
+```typescript
+import { CLIOptions } from '@twin.org/cli-core';
+
+const options = new CLIOptions();
+
+options.output({
+  json: './dist/output.json'
+});
+
+console.log(options.toObject().json); // ./dist/output.json
+```

package/docs/reference/classes/CLIBase.md

@@ -14,7 +14,7 @@ The main entry point for the CLI.
 
 ## Methods
 
-### execute()
+### execute() {#execute}
 
 > **execute**(`options`, `localesDirectory`, `argv`): `Promise`\<`number`\>
 
@@ -48,7 +48,7 @@ The exit code.
 
 ***
 
-### configureRoot()
+### configureRoot() {#configureroot}
 
 > `protected` **configureRoot**(`program`): `void`
 
@@ -68,7 +68,7 @@ The root program command.
 
 ***
 
-### getCommands()
+### getCommands() {#getcommands}
 
 > `protected` **getCommands**(`program`): `Command`[]
 

package/docs/reference/classes/CLIDisplay.md

@@ -14,7 +14,7 @@ Display utilities for the CLI.
 
 ## Properties
 
-### write()
+### write {#write}
 
 > `static` **write**: (`buffer`) => `void`
 
@@ -24,9 +24,9 @@ The default output method for writing standard messages.
 
 ##### buffer
 
-The message to output.
+`string` \| `Uint8Array`\<`ArrayBufferLike`\>
 
-`string` | `Uint8Array`\<`ArrayBufferLike`\>
+The message to output.
 
 #### Returns
 
@@ -34,7 +34,7 @@ The message to output.
 
 ***
 
-### writeError()
+### writeError {#writeerror}
 
 > `static` **writeError**: (`buffer`) => `void`
 
@@ -44,9 +44,9 @@ The default output method for writing error messages.
 
 ##### buffer
 
-The message to output.
+`string` \| `Uint8Array`\<`ArrayBufferLike`\>
 
-`string` | `Uint8Array`\<`ArrayBufferLike`\>
+The message to output.
 
 #### Returns
 
@@ -54,7 +54,7 @@ The message to output.
 
 ***
 
-### clearLine()
+### clearLine {#clearline}
 
 > `static` **clearLine**: () => `void`
 
@@ -66,7 +66,7 @@ The default output method for clearing the current line.
 
 ## Methods
 
-### header()
+### header() {#header}
 
 > `static` **header**(`title`, `version`, `icon`): `void`
 
@@ -98,9 +98,9 @@ The icon for the CLI.
 
 ***
 
-### error()
+### error() {#error}
 
-> `static` **error**(`error`, `lineBreaks`): `void`
+> `static` **error**(`error`, `lineBreaks?`, `options?`): `void`
 
 Display an error message.
 
@@ -112,19 +112,35 @@ Display an error message.
 
 The error to display.
 
-##### lineBreaks
+##### lineBreaks?
 
 `boolean` = `true`
 
 Whether to add a line break after the error.
 
+##### options?
+
+Options for formatting the error.
+
+###### includeStack?
+
+`boolean`
+
+Whether to include the stack trace in the output, defaults to false.
+
+###### includeAdditional?
+
+`boolean`
+
+Whether to include additional error information in the output, defaults to false.
+
 #### Returns
 
 `void`
 
 ***
 
-### errorMessage()
+### errorMessage() {#errormessage}
 
 > `static` **errorMessage**(`error`): `void`
 
@@ -144,7 +160,7 @@ The error to display.
 
 ***
 
-### section()
+### section() {#section}
 
 > `static` **section**(`label`): `void`
 
@@ -164,9 +180,9 @@ The label for the section.
 
 ***
 
-### value()
+### value() {#value}
 
-> `static` **value**(`label`, `value`, `indentLevel`): `void`
+> `static` **value**(`label`, `value`, `indentLevel?`): `void`
 
 Display a value with a label.
 
@@ -184,7 +200,7 @@ The label for the value.
 
 The value to display.
 
-##### indentLevel
+##### indentLevel?
 
 `number` = `0`
 
@@ -196,7 +212,7 @@ The level of indentation.
 
 ***
 
-### task()
+### task() {#task}
 
 > `static` **task**(`label`, `task?`): `void`
 
@@ -222,7 +238,7 @@ The task to display.
 
 ***
 
-### break()
+### break() {#break}
 
 > `static` **break**(): `void`
 
@@ -234,7 +250,7 @@ Display a break.
 
 ***
 
-### json()
+### json() {#json}
 
 > `static` **json**(`obj`): `void`
 
@@ -254,7 +270,7 @@ The object to display.
 
 ***
 
-### warning()
+### warning() {#warning}
 
 > `static` **warning**(`label`): `void`
 
@@ -274,7 +290,7 @@ The label for the warning.
 
 ***
 
-### done()
+### done() {#done}
 
 > `static` **done**(): `void`
 
@@ -286,27 +302,27 @@ Display the processing is done.
 
 ***
 
-### spinnerStart()
+### spinnerStart() {#spinnerstart}
 
-> `static` **spinnerStart**(`i18nMessage`, `spinnerCharacters`, `interval`): `void`
+> `static` **spinnerStart**(`i18nMessage?`, `spinnerCharacters?`, `interval?`): `void`
 
 Start the spinner.
 
 #### Parameters
 
-##### i18nMessage
+##### i18nMessage?
 
 `string` = `"cli.progress.pleaseWait"`
 
 The message to display with the spinner.
 
-##### spinnerCharacters
+##### spinnerCharacters?
 
 `string`[] = `...`
 
 The characters to use in the spinner.
 
-##### interval
+##### interval?
 
 `number` = `100`
 
@@ -318,7 +334,7 @@ The interval for the spinner.
 
 ***
 
-### spinnerStop()
+### spinnerStop() {#spinnerstop}
 
 > `static` **spinnerStop**(): `void`
 

package/docs/reference/classes/CLIOptions.md

@@ -14,7 +14,7 @@ Utilities for getting standard options.
 
 ## Methods
 
-### output()
+### output() {#output}
 
 > `static` **output**(`command`, `opts`): `void`
 

package/docs/reference/classes/CLIParam.md

@@ -14,7 +14,7 @@ Parameter utilities for the CLI.
 
 ## Methods
 
-### env()
+### env() {#env}
 
 > `static` **env**(`optionName`, `optionValue`, `allowEnvVar`): `string` \| `undefined`
 
@@ -30,9 +30,9 @@ The name of the option.
 
 ##### optionValue
 
-The option value.
+`string` \| `undefined`
 
-`string` | `undefined`
+The option value.
 
 ##### allowEnvVar
 
@@ -52,9 +52,9 @@ An error if the option is invalid.
 
 ***
 
-### stringValue()
+### stringValue() {#stringvalue}
 
-> `static` **stringValue**(`optionName`, `optionValue`, `allowEnvVar`): `string`
+> `static` **stringValue**(`optionName`, `optionValue`, `allowEnvVar?`): `string`
 
 Check the option to see if the String exists.
 
@@ -68,11 +68,11 @@ The name of the option.
 
 ##### optionValue
 
+`string` \| `undefined`
+
 The option value.
 
-`string` | `undefined`
-
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
@@ -90,9 +90,9 @@ An error if the option is invalid.
 
 ***
 
-### arrayOneOf()
+### arrayOneOf() {#arrayoneof}
 
-> `static` **arrayOneOf**\<`T`\>(`optionName`, `optionValue`, `validValues`, `allowEnvVar`): `T`
+> `static` **arrayOneOf**\<`T`\>(`optionName`, `optionValue`, `validValues`, `allowEnvVar?`): `T`
 
 Check the option to see if the value exists in the specific array.
 
@@ -112,9 +112,9 @@ The name of the option.
 
 ##### optionValue
 
-The option value.
+`string` \| `undefined`
 
-`string` | `undefined`
+The option value.
 
 ##### validValues
 
@@ -122,7 +122,7 @@ The option value.
 
 The valid values.
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
@@ -140,9 +140,9 @@ An error if the option is invalid.
 
 ***
 
-### url()
+### url() {#url}
 
-> `static` **url**(`optionName`, `optionValue`, `allowEnvVar`): `string`
+> `static` **url**(`optionName`, `optionValue`, `allowEnvVar?`): `string`
 
 Check the option to see if it is a url.
 
@@ -156,11 +156,11 @@ The name of the option.
 
 ##### optionValue
 
-The option value.
+`string` \| `undefined`
 
-`string` | `undefined`
+The option value.
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
@@ -178,9 +178,9 @@ An error if the option is invalid.
 
 ***
 
-### number()
+### number() {#number}
 
-> `static` **number**(`optionName`, `optionValue`, `allowEnvVar`, `minValue`, `maxValue?`): `number`
+> `static` **number**(`optionName`, `optionValue`, `allowEnvVar?`, `minValue?`, `maxValue?`): `number`
 
 Check the option to see if it exists and is a number.
 
@@ -194,17 +194,17 @@ The name of the option.
 
 ##### optionValue
 
-The option value.
+`string` \| `undefined`
 
-`string` | `undefined`
+The option value.
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
 Allow the option to be read from an env var.
 
-##### minValue
+##### minValue?
 
 `number` = `0`
 
@@ -228,9 +228,9 @@ An error if the option is invalid.
 
 ***
 
-### integer()
+### integer() {#integer}
 
-> `static` **integer**(`optionName`, `optionValue`, `allowEnvVar`, `minValue`, `maxValue?`): `number`
+> `static` **integer**(`optionName`, `optionValue`, `allowEnvVar?`, `minValue?`, `maxValue?`): `number`
 
 Check the option to see if it exists and is an integer.
 
@@ -244,17 +244,17 @@ The name of the option.
 
 ##### optionValue
 
+`string` \| `undefined`
+
 The option value.
 
-`string` | `undefined`
-
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
 Allow the option to be read from an env var.
 
-##### minValue
+##### minValue?
 
 `number` = `0`
 
@@ -278,9 +278,9 @@ An error if the option is invalid.
 
 ***
 
-### bigint()
+### bigint() {#bigint}
 
-> `static` **bigint**(`optionName`, `optionValue`, `allowEnvVar`, `minValue`, `maxValue?`): `bigint`
+> `static` **bigint**(`optionName`, `optionValue`, `allowEnvVar?`, `minValue?`, `maxValue?`): `bigint`
 
 Check the option to see if it exists and is a big number.
 
@@ -294,17 +294,17 @@ The name of the option.
 
 ##### optionValue
 
-The option value.
+`string` \| `undefined`
 
-`string` | `undefined`
+The option value.
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
 Allow the option to be read from an env var.
 
-##### minValue
+##### minValue?
 
 `bigint` = `0n`
 
@@ -328,9 +328,9 @@ An error if the option is invalid.
 
 ***
 
-### boolean()
+### boolean() {#boolean}
 
-> `static` **boolean**(`optionName`, `optionValue`, `allowEnvVar`): `boolean`
+> `static` **boolean**(`optionName`, `optionValue`, `allowEnvVar?`): `boolean`
 
 Check the option to see if it exists and is a boolean.
 
@@ -344,11 +344,11 @@ The name of the option.
 
 ##### optionValue
 
-The option value.
+`string` \| `undefined`
 
-`string` | `undefined`
+The option value.
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
@@ -366,9 +366,9 @@ An error if the option is invalid.
 
 ***
 
-### hex()
+### hex() {#hex}
 
-> `static` **hex**(`optionName`, `optionValue`, `allowEnvVar`): `Uint8Array`
+> `static` **hex**(`optionName`, `optionValue`, `allowEnvVar?`): `Uint8Array`
 
 Check the option to see if it exists and is hex.
 
@@ -382,11 +382,11 @@ The name of the option.
 
 ##### optionValue
 
-The option value.
+`string` \| `undefined`
 
-`string` | `undefined`
+The option value.
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
@@ -404,9 +404,9 @@ An error if the option is invalid.
 
 ***
 
-### base64()
+### base64() {#base64}
 
-> `static` **base64**(`optionName`, `optionValue`, `allowEnvVar`): `Uint8Array`
+> `static` **base64**(`optionName`, `optionValue`, `allowEnvVar?`): `Uint8Array`
 
 Check the option to see if it exists and is base64.
 
@@ -420,11 +420,11 @@ The name of the option.
 
 ##### optionValue
 
-The option value.
+`string` \| `undefined`
 
-`string` | `undefined`
+The option value.
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
@@ -442,9 +442,9 @@ An error if the option is invalid.
 
 ***
 
-### hexBase64()
+### hexBase64() {#hexbase64}
 
-> `static` **hexBase64**(`optionName`, `optionValue`, `allowEnvVar`): `Uint8Array`
+> `static` **hexBase64**(`optionName`, `optionValue`, `allowEnvVar?`): `Uint8Array`
 
 Check the option to see if it exists and is hex or base64.
 
@@ -458,11 +458,11 @@ The name of the option.
 
 ##### optionValue
 
-The option value.
+`string` \| `undefined`
 
-`string` | `undefined`
+The option value.
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`