@flowscripter/dynamic-cli-framework 1.1.6 → 1.2.1

package/bun.lock

@@ -1,39 +1,41 @@
 {
   "lockfileVersion": 1,
+  "configVersion": 1,
   "workspaces": {
     "": {
-      "name": "@flowscripter/dynamic-plugin-framework",
+      "name": "@flowscripter/dynamic-cli-framework",
       "dependencies": {
         "emphasize": "^7.0.0",
         "fastest-levenshtein": "^1.0.16",
-        "figlet": "^1.8.1",
+        "figlet": "^1.11.0",
         "highlight.js": "^11.11.1",
-        "prettier": "^3.5.3",
-        "supports-color": "^10.0.0",
-        "ts-log": "^2.2.7",
+        "prettier": "^3.8.3",
+        "supports-color": "^10.2.2",
+        "supports-terminal-graphics": "^0.1.0",
       },
       "devDependencies": {
-        "@types/bun": "^1.2.9",
+        "@types/bun": "^1.3.14",
+        "@types/node": "^25.9.2",
       },
       "peerDependencies": {
-        "typescript": "^5.8.3",
+        "typescript": "^6.0.3",
       },
     },
   },
   "packages": {
-    "@types/bun": ["@types/bun@1.2.9", "", { "dependencies": { "bun-types": "1.2.9" } }, "sha512-epShhLGQYc4Bv/aceHbmBhOz1XgUnuTZgcxjxk+WXwNyDXavv5QHD1QEFV0FwbTSQtNq6g4ZcV6y0vZakTjswg=="],
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
 
     "@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ=="],
 
-    "@types/node": ["@types/node@22.13.4", "", { "dependencies": { "undici-types": "~6.20.0" } }, "sha512-ywP2X0DYtX3y08eFVx5fNIw7/uIv8hYUKgXoK8oayJlLnKcRfEYCxWMVE1XagUdVtCJlZT1AU4LXEABW+L1Peg=="],
+    "@types/node": ["@types/node@25.9.2", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-G05zqtJhcDLb8uslf5EjCxXg9G1KQxiV8OS0R26IC//Eoyitzqe8z37I7cqvnZlrlSfgocQRfSn/AHBZJJFyGw=="],
 
     "@types/unist": ["@types/unist@3.0.3", "", {}, "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q=="],
 
-    "@types/ws": ["@types/ws@8.5.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-bd/YFLW+URhBzMXurx7lWByOu+xzU9+kb3RboOteXYDfW+tr+JZa99OyNmPINEGB/ahzKrEuc8rcv4gnpJmxTw=="],
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
 
-    "bun-types": ["bun-types@1.2.9", "", { "dependencies": { "@types/node": "*", "@types/ws": "*" } }, "sha512-dk/kOEfQbajENN/D6FyiSgOKEuUi9PWfqKQJEgwKrCMWbjS/S6tEXp178mWvWAcUSYm9ArDlWHZKO3T/4cLXiw=="],
+    "chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
 
-    "chalk": ["chalk@5.4.1", "", {}, "sha512-zgVZuo2WcZgfUEmsn6eO3kINexW8RAE4maiQ8QNs8CtpPCSyMiYsULR3HQYkm3w8FIA3SberyMJMSldGsW+U3w=="],
+    "commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
 
     "dequal": ["dequal@2.0.3", "", {}, "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA=="],
 
@@ -43,21 +45,23 @@
 
     "fastest-levenshtein": ["fastest-levenshtein@1.0.16", "", {}, "sha512-eRnCtTTtGZFpQCwhJiUOuxPQWRXVKYDn0b2PeHfXL6/Zi53SLAzAHfVhVWK2AryC/WH05kGfxhFIPvTF0SXQzg=="],
 
-    "figlet": ["figlet@1.8.1", "", { "bin": { "figlet": "bin/index.js" } }, "sha512-kEC3Sme+YvA8Hkibv0NR1oClGcWia0VB2fC1SlMy027cwe795Xx40Xiv/nw/iFAwQLupymWh+uhAAErn/7hwPg=="],
+    "figlet": ["figlet@1.11.0", "", { "dependencies": { "commander": "^14.0.0" }, "bin": { "figlet": "bin/index.js" } }, "sha512-EEx3OS/l2bFqcUNN2NM9FPJp8vAMrgbCxsbl2hbcJNNxOEwVe3mEzrhan7TbJQViZa8mMqhihlbCaqD+LyYKTQ=="],
 
     "highlight.js": ["highlight.js@11.11.1", "", {}, "sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w=="],
 
     "lowlight": ["lowlight@3.1.0", "", { "dependencies": { "@types/hast": "^3.0.0", "devlop": "^1.0.0", "highlight.js": "~11.9.0" } }, "sha512-CEbNVoSikAxwDMDPjXlqlFYiZLkDJHwyGu/MfOsJnF3d7f3tds5J3z8s/l9TMXhzfsJCCJEAsD78842mwmg0PQ=="],
 
-    "prettier": ["prettier@3.5.3", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-QQtaxnoDJeAkDvDKWCLiwIXkTgRhwYDEQCghU9Z6q03iyek/rxRh/2lC3HB7P8sWT2xC/y5JDctPLBIGzHKbhw=="],
+    "prettier": ["prettier@3.8.3", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw=="],
 
-    "supports-color": ["supports-color@10.0.0", "", {}, "sha512-HRVVSbCCMbj7/kdWF9Q+bbckjBHLtHMEoJWlkmYzzdwhYMkjkOwubLM6t7NbWKjgKamGDrWL1++KrjUO1t9oAQ=="],
+    "supports-color": ["supports-color@10.2.2", "", {}, "sha512-SS+jx45GF1QjgEXQx4NJZV9ImqmO2NPz5FNsIHrsDjh2YsHnawpan7SNQ1o8NuhrbHZy9AZhIoCUiCeaW/C80g=="],
 
-    "ts-log": ["ts-log@2.2.7", "", {}, "sha512-320x5Ggei84AxzlXp91QkIGSw5wgaLT6GeAH0KsqDmRZdVWW2OiSeVvElVoatk3f7nicwXlElXsoFkARiGE2yg=="],
+    "supports-terminal-graphics": ["supports-terminal-graphics@0.1.0", "", {}, "sha512-+KdfozhS0Fw8y5Sghw8kkZNGT8nWYzJ1EzcoIvVjxhl+26TJTs26y02yfBgvc1jh5AS/c8jcI3xtahhR95KRyQ=="],
 
-    "typescript": ["typescript@5.8.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ=="],
+    "typescript": ["typescript@6.0.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw=="],
 
-    "undici-types": ["undici-types@6.20.0", "", {}, "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg=="],
+    "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+
+    "bun-types/@types/node": ["@types/node@25.9.1", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg=="],
 
     "emphasize/highlight.js": ["highlight.js@11.9.0", "", {}, "sha512-fJ7cW7fQGCYAkgv4CPfwFHrfd/cLS4Hau96JuJ+ZTOWhjnhoeN1ub1tFmALm/+lW5z4WCAuAV9bm05AP0mS6Gw=="],
 

package/index.ts

@@ -39,21 +39,43 @@ export type { default as ServiceProviderRegistry } from "./src/runtime/registry/
 // Core Services
 export { ASCII_BANNER_GENERATOR_SERVICE_ID } from "./src/api/service/core/AsciiBannerGeneratorService.ts";
 export type { default as AsciiBannerGeneratorService } from "./src/api/service/core/AsciiBannerGeneratorService.ts";
+export type {
+  BannerColorEffects,
+  BannerGenerateOptions,
+  ColorEffect,
+  ColorEffectDirection,
+  FixedColorEffect,
+  GradientColorEffect,
+  RainbowColorEffect,
+} from "./src/api/service/core/AsciiBannerGeneratorService.ts";
 export { default as DefaultAsciiBannerGeneratorService } from "./src/service/asciiBannerGenerator/DefaultAsciiBannerGeneratorService.ts";
 export { default as AsciiBannerGeneratorServiceProvider } from "./src/service/asciiBannerGenerator/AsciiBannerGeneratorServiceProvider.ts";
+export { default as ChiselFontAsciiBannerGeneratorService } from "./src/service/chiselAsciiBannerGenerator/ChiselFontAsciiBannerGeneratorService.ts";
+export type {
+  ChiselBannerColors,
+  ChiselBannerGenerateOptions,
+} from "./src/service/chiselAsciiBannerGenerator/ChiselFontAsciiBannerGeneratorService.ts";
 
 export { default as BannerServiceProvider } from "./src/service/banner/BannerServiceProvider.ts";
 
 export { KEY_VALUE_SERVICE_ID } from "./src/api/service/core/KeyValueService.ts";
+export { SECRET_SENTINEL_PREFIX } from "./src/api/service/core/KeyValueService.ts";
 export type { default as KeyValueService } from "./src/api/service/core/KeyValueService.ts";
+export type { default as SecretService } from "./src/api/service/core/SecretService.ts";
 export { default as DefaultKeyValueService } from "./src/service/configuration/DefaultKeyValueService.ts";
+export { default as DefaultSecretService } from "./src/service/configuration/DefaultSecretService.ts";
 export { default as ConfigurationServiceProvider } from "./src/service/configuration/ConfigurationServiceProvider.ts";
 
 export { PRINTER_SERVICE_ID } from "./src/api/service/core/PrinterService.ts";
 export type {
   default as PrinterService,
 } from "./src/api/service/core/PrinterService.ts";
-export { Icon, Level } from "./src/api/service/core/PrinterService.ts";
+export {
+  Icon,
+  Level,
+  ProgressStyle,
+  SpinnerStyle,
+} from "./src/api/service/core/PrinterService.ts";
 export { default as DefaultPrinterService } from "./src/service/printer/DefaultPrinterService.ts";
 export { default as PrinterServiceProvider } from "./src/service/printer/PrinterServiceProvider.ts";
 
@@ -73,6 +95,69 @@ export type { default as PrettyPrinterService } from "./src/api/service/core/Pre
 export { default as DefaultPrettyPrinterService } from "./src/service/prettyPrinter/DefaultPrettyPrinterService.ts";
 export { default as PrettyPrinterServiceProvider } from "./src/service/prettyPrinter/PrettyPrinterServiceProvider.ts";
 
+export { IMAGE_PRINTER_SERVICE_ID } from "./src/api/service/core/ImagePrinterService.ts";
+export type { default as ImagePrinterService } from "./src/api/service/core/ImagePrinterService.ts";
+export { default as DefaultImagePrinterService } from "./src/service/imagePrinter/DefaultImagePrinterService.ts";
+export { default as ImagePrinterServiceProvider } from "./src/service/imagePrinter/ImagePrinterServiceProvider.ts";
+
+export { TREE_PRINTER_SERVICE_ID } from "./src/api/service/core/TreePrinterService.ts";
+export type { default as TreePrinterService } from "./src/api/service/core/TreePrinterService.ts";
+export type { TreeNode } from "./src/api/service/core/TreePrinterService.ts";
+export { default as DefaultTreePrinterService } from "./src/service/treePrinter/DefaultTreePrinterService.ts";
+export { default as TreePrinterServiceProvider } from "./src/service/treePrinter/TreePrinterServiceProvider.ts";
+
+export { TABLE_GENERATOR_SERVICE_ID } from "./src/api/service/core/TableGeneratorService.ts";
+export type { default as TableGeneratorService } from "./src/api/service/core/TableGeneratorService.ts";
+export {
+  Align,
+  type CellOptions,
+  type ColumnOptions,
+  type RowOptions,
+  type TableOptions,
+} from "./src/api/service/core/TableGeneratorService.ts";
+export { default as Table } from "./src/api/service/core/Table.ts";
+export { default as DefaultTableGeneratorService } from "./src/service/tableGenerator/DefaultTableGeneratorService.ts";
+export { default as TableGeneratorServiceProvider } from "./src/service/tableGenerator/TableGeneratorServiceProvider.ts";
+
+export { DATA_DUMP_GENERATOR_SERVICE_ID } from "./src/api/service/core/DataDumpGeneratorService.ts";
+export type { default as DataDumpGeneratorService } from "./src/api/service/core/DataDumpGeneratorService.ts";
+export {
+  type ByteRangeColor,
+  DumpFormat,
+  type HexDumpGenerateOptions,
+} from "./src/api/service/core/DataDumpGeneratorService.ts";
+export { default as DefaultDataDumpGeneratorService } from "./src/service/dataDumpGenerator/DefaultDataDumpGeneratorService.ts";
+export { default as DataDumpGeneratorServiceProvider } from "./src/service/dataDumpGenerator/DataDumpGeneratorServiceProvider.ts";
+
+export { COMPLETION_SERVICE_ID } from "./src/api/service/core/CompletionService.ts";
+export type { default as CompletionService } from "./src/api/service/core/CompletionService.ts";
+export {
+  type CompletionItem,
+  ShellType,
+} from "./src/api/service/core/CompletionService.ts";
+export { default as DefaultCompletionService } from "./src/service/completion/DefaultCompletionService.ts";
+export { default as CompletionServiceProvider } from "./src/service/completion/CompletionServiceProvider.ts";
+
+export { PROMPTER_SERVICE_ID } from "./src/api/service/core/PrompterService.ts";
+export type { default as PrompterService } from "./src/api/service/core/PrompterService.ts";
+export {
+  type Prompt,
+  type PromptOption,
+  type PromptResult,
+  PromptType,
+} from "./src/api/service/core/PrompterService.ts";
+export { default as DefaultPrompterService } from "./src/service/prompter/DefaultPrompterService.ts";
+export {
+  DEFAULT_PROMPTER_CONFIG,
+  type PrompterServiceConfig,
+} from "./src/service/prompter/DefaultPrompterService.ts";
+export { default as PrompterServiceProvider } from "./src/service/prompter/PrompterServiceProvider.ts";
+
+export { ARGUMENT_PROMPTER_SERVICE_ID } from "./src/api/service/core/ArgumentPrompterService.ts";
+export type { default as ArgumentPrompterService } from "./src/api/service/core/ArgumentPrompterService.ts";
+export { default as DefaultArgumentPrompterService } from "./src/service/argumentPrompter/DefaultArgumentPrompterService.ts";
+export { default as ArgumentPrompterServiceProvider } from "./src/service/argumentPrompter/ArgumentPrompterServiceProvider.ts";
+
 // CLI API
 export type { InvalidArgument } from "./src/api/RunResult.ts";
 export type { default as Context } from "./src/api/Context.ts";
@@ -81,6 +166,7 @@ export type {
   InvalidArgumentReason,
   RunState,
 } from "./src/api/RunResult.ts";
+export type { default as BaseCLIFeatureOptions } from "./src/api/BaseCLIFeatureOptions.ts";
 export type { default as CLIConfig } from "./src/api/CLIConfig.ts";
 export type { default as CLI } from "./src/api/CLI.ts";
 
@@ -88,6 +174,16 @@ export type { default as CLI } from "./src/api/CLI.ts";
 export { default as BaseCLI } from "./src/cli/BaseCLI.ts";
 export { default as DefaultRuntimeCLI } from "./src/cli/DefaultRuntimeCLI.ts";
 
+// Terminal API
+export type { default as Terminal } from "./src/terminal/Terminal.ts";
+export type { default as Styler } from "./src/terminal/Styler.ts";
+export type {
+  default as KeyReader,
+  KeyEvent,
+} from "./src/terminal/KeyReader.ts";
+export { SpecialKey } from "./src/terminal/KeyReader.ts";
+export { default as TtyKeyReader } from "./src/terminal/TtyKeyReader.ts";
+
 // Convenience functions
 export {
   launchMultiCommandCLI,

package/package.json

@@ -18,23 +18,24 @@
   ],
   "module": "index.ts",
   "type": "module",
-  "version": "1.1.6",
+  "version": "1.2.1",
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.9"
+    "@types/bun": "^1.3.14",
+    "@types/node": "^25.9.2"
   },
   "peerDependencies": {
-    "typescript": "^5.8.3"
+    "typescript": "^6.0.3"
   },
   "dependencies": {
     "emphasize": "^7.0.0",
     "fastest-levenshtein": "^1.0.16",
-    "figlet": "^1.8.1",
+    "figlet": "^1.11.0",
     "highlight.js": "^11.11.1",
-    "prettier": "^3.5.3",
-    "supports-color": "^10.0.0",
-    "ts-log": "^2.2.7"
+    "prettier": "^3.8.3",
+    "supports-color": "^10.2.2",
+    "supports-terminal-graphics": "^0.1.0"
   }
 }

package/src/api/BaseCLIFeatureOptions.ts

@@ -0,0 +1,10 @@
+export default interface BaseCLIFeatureOptions {
+  readonly configFileSupportEnabled?: boolean;
+  readonly envVarsSupportEnabled?: boolean;
+  readonly keyValueServiceEnabled?: boolean;
+  readonly secretServiceEnabled?: boolean;
+  readonly argumentPrompterServiceEnabled?: boolean;
+  readonly completionServiceEnabled?: boolean;
+  readonly imagePrinterServiceEnabled?: boolean;
+  readonly validateAllCommands?: boolean;
+}

package/src/api/CLIConfig.ts

@@ -12,6 +12,11 @@ export default interface CLIConfig {
    */
   readonly description?: string;
 
+  /**
+   * Optional sub-message to display below the banner.
+   */
+  readonly subMessage?: string;
+
   /**
    * Version of the CLI application.
    */

package/src/api/RunResult.ts

@@ -34,6 +34,11 @@ export enum RunState {
    * General runtime error related to the framework.
    */
   RUNTIME_ERROR = 4,
+
+  /**
+   * Execution was interrupted by a signal (e.g. Ctrl-C or SIGTERM).
+   */
+  INTERRUPTED = 130,
 }
 
 /**
@@ -84,6 +89,11 @@ export enum InvalidArgumentReason {
    * Attempt to set a primitive value on a complex object object.
    */
   OPTION_IS_COMPLEX = 8,
+
+  /**
+   * The value failed a custom validation function defined on the argument.
+   */
+  CUSTOM_VALIDATION = 9,
 }
 
 /**
@@ -114,6 +124,12 @@ export interface InvalidArgument {
     | PopulatedArgumentValues
     | PopulatedArgumentValueType
     | Array<PopulatedArgumentValues | PopulatedArgumentValueType>;
+
+  /**
+   * An optional message providing detail about the validation failure.
+   * Populated when {@link reason} is {@link InvalidArgumentReason.CUSTOM_VALIDATION}.
+   */
+  readonly message?: string;
 }
 
 /**

package/src/api/argument/Argument.ts

@@ -1,5 +1,7 @@
 import type {
   ArgumentSingleValueType,
+  ArgumentValues,
+  ArgumentValueType,
   ArgumentValueTypeName,
 } from "./ArgumentValueTypes.ts";
 
@@ -48,4 +50,26 @@ export default interface Argument {
    * it will only be used if the parent {@link Command} has specified {@link Command.enableConfiguration} as `true`.
    */
   readonly configurationKey?: string;
+
+  /**
+   * Optional custom validation function invoked after all built-in validation
+   * has passed. Receives the validated and type-converted value.
+   *
+   * Return `undefined` if the value is valid, or a string describing the
+   * validation error. The error string is associated with
+   * {@link InvalidArgumentReason.CUSTOM_VALIDATION}.
+   *
+   * Example: ensure array values are unique:
+   * ```typescript
+   * validate: (value) => {
+   *   const arr = value as string[];
+   *   return new Set(arr).size !== arr.length
+   *     ? "values must be unique"
+   *     : undefined;
+   * }
+   * ```
+   */
+  readonly validate?: (
+    value: ArgumentValueType | ArgumentValues | Array<ArgumentValues>,
+  ) => string | undefined;
 }

package/src/api/service/ServiceProvider.ts

@@ -18,7 +18,7 @@ export interface ServiceInfo {
 }
 
 /**
- * Interface allowing services to be provided to the CLI.
+ * Interface allowing a service to be provided to the CLI.
  */
 export interface ServiceProvider {
   /**
@@ -33,11 +33,11 @@ export interface ServiceProvider {
   readonly servicePriority: number;
 
   /**
-   * Return {@link ServiceInfo} containing the service and any commands which should be registered in the CLI.
+   * Return {@link ServiceInfo} containing the service and any commands it provides which should be registered in the CLI.
    *
    * @param cliConfig the {@link CLIConfig} for the CLI.
    */
-  provide(cliConfig: CLIConfig): Promise<ServiceInfo>;
+  getServiceInfo(cliConfig: CLIConfig): Promise<ServiceInfo>;
 
   /**
    * Initialise the service. This will be invoked AFTER any {@link GlobalModifierCommand} provided in the

package/src/api/service/core/ArgumentPrompterService.ts

@@ -0,0 +1,10 @@
+import type { ParseResult } from "../../../runtime/parser.ts";
+
+export const ARGUMENT_PROMPTER_SERVICE_ID =
+  "@flowscripter/dynamic-cli-framework/argument-prompter-service";
+
+export default interface ArgumentPrompterService {
+  promptForMissingArguments(
+    parseResult: ParseResult,
+  ): Promise<ParseResult>;
+}

package/src/api/service/core/AsciiBannerGeneratorService.ts

@@ -1,8 +1,46 @@
 export const ASCII_BANNER_GENERATOR_SERVICE_ID =
   "@flowscripter/dynamic-cli-framework/ascii-banner-generator-service";
 
+export type ColorEffectDirection = "horizontal" | "vertical";
+
+export interface FixedColorEffect {
+  type: "fixed";
+  color: string; // hex "#rrggbb"
+}
+
+export interface GradientColorEffect {
+  type: "gradient";
+  colors: string[]; // 2+ hex color stops
+  direction: ColorEffectDirection;
+}
+
+export interface RainbowColorEffect {
+  type: "rainbow";
+  spread?: number; // default 8.0
+  frequency?: number; // default 0.3
+  seed?: number; // default 0 = random seed
+  direction: ColorEffectDirection;
+}
+
+export type ColorEffect =
+  | FixedColorEffect
+  | GradientColorEffect
+  | RainbowColorEffect;
+
+export interface BannerColorEffects {
+  background?: ColorEffect;
+  messageForeground?: ColorEffect;
+  subMessageForeground?: ColorEffect;
+}
+
+export interface BannerGenerateOptions {
+  fontName?: string;
+  subMessage?: string;
+  colorEffects?: BannerColorEffects;
+}
+
 /**
- * Service allowing a text string to be rendered using an ASCII banner [FIGlet](http://www.figlet.org) font.
+ * Service allowing a text string to be rendered using an ASCII banner font.
  */
 export default interface AsciiBannerGeneratorService {
   /**
@@ -12,11 +50,10 @@ export default interface AsciiBannerGeneratorService {
    * (replacing newlines with `\n`) and placing in a simple JSON file: `{ "font": "<figlet font definition>" }`.
    * This can then be imported as follows:
    *
-   * `import { font as myFont } from "./myfont.json" with { type: "json" };
+   * `import { font as myFont } from "./myfont.json" with { type: "json" };`
    *
    * @param fontName the name used to refer to the font.
-   * @param fontDefinition the definition for the syntax conforming to the
-   * [FIGfont format](http://www.jave.de/figlet/figfont.html#creating).
+   * @param fontDefinition the definition for the syntax conforming to the FIGfont format.
    */
   registerFont(fontName: string, fontDefinition: string): void;
 
@@ -26,10 +63,10 @@ export default interface AsciiBannerGeneratorService {
   getRegisteredFonts(): ReadonlyArray<string>;
 
   /**
-   * Generate an ASCII banner text for the message using the specified font.
+   * Generate an ASCII banner text for the message using the specified options.
    *
    * @param message the message to output.
-   * @param fontName the font to use.
+   * @param options optional generation options.
    */
-  generate(message: string, fontName: string): Promise<string>;
+  generate(message: string, options?: BannerGenerateOptions): Promise<string>;
 }

package/src/api/service/core/CompletionService.ts

@@ -0,0 +1,36 @@
+export const COMPLETION_SERVICE_ID =
+  "@flowscripter/dynamic-cli-framework/completion-service";
+
+export enum ShellType {
+  BASH = "bash",
+  ZSH = "zsh",
+  FISH = "fish",
+  POWERSHELL = "powershell",
+}
+
+export interface CompletionItem {
+  readonly value: string;
+  readonly description?: string;
+}
+
+/**
+ * Interface for a service providing shell auto-completion support.
+ */
+export default interface CompletionService {
+  generateCompletions(
+    shellType: ShellType,
+    line: string,
+    cursorPosition: number,
+  ): Promise<ReadonlyArray<CompletionItem>>;
+
+  getBootstrapScript(shellType: ShellType, cliName: string): string;
+
+  getDefaultConfigPath(shellType: ShellType): string;
+
+  validateShellEnvironment(shellType: ShellType): Promise<boolean>;
+
+  formatCompletions(
+    shellType: ShellType,
+    completions: ReadonlyArray<CompletionItem>,
+  ): string;
+}

package/src/api/service/core/DataDumpGeneratorService.ts

@@ -0,0 +1,27 @@
+import { Buffer } from "node:buffer";
+
+export const DATA_DUMP_GENERATOR_SERVICE_ID =
+  "@flowscripter/dynamic-cli-framework/data-dump-generator-service";
+
+export enum DumpFormat {
+  HEX = "HEX",
+  ASCII = "ASCII",
+}
+
+export interface ByteRangeColor {
+  start: number;
+  end: number;
+  color: string;
+}
+
+export interface HexDumpGenerateOptions {
+  format?: DumpFormat;
+  bytesPerGroup?: number;
+  groupsPerRow?: number;
+  spacesBetweenGroups?: number;
+  colorScheme?: ByteRangeColor[];
+}
+
+export default interface DataDumpGeneratorService {
+  generate(data: Buffer, options?: HexDumpGenerateOptions): string;
+}

package/src/api/service/core/ImagePrinterService.ts

@@ -0,0 +1,26 @@
+export const IMAGE_PRINTER_SERVICE_ID =
+  "@flowscripter/dynamic-cli-framework/image-printer-service";
+
+/**
+ * Service for rendering images in the terminal.
+ *
+ * Uses the Kitty or iTerm2 graphics protocol when supported, otherwise falls back
+ * to ANSI half-block character rendering. Terminal multiplexers (tmux, screen) always
+ * use the ANSI fallback as they do not pass through graphics protocol escape sequences.
+ */
+export default interface ImagePrinterService {
+  /**
+   * Render an image as a string suitable for terminal output.
+   *
+   * @param imageBuffer the raw image data (e.g. PNG file contents).
+   * @param widthPercentage the percentage of terminal width to use for rendering. Defaults to 100.
+   * @param hexFormattedBackgroundColor optional background color for transparent pixels.
+   *   This should be a valid hex formatted string e.g. "#rrggbb". If not specified,
+   *   transparent pixels show through to the terminal background.
+   */
+  image(
+    imageBuffer: Uint8Array,
+    widthPercentage?: number,
+    hexFormattedBackgroundColor?: string,
+  ): Promise<string>;
+}

package/src/api/service/core/KeyValueService.ts

@@ -1,28 +1,45 @@
 export const KEY_VALUE_SERVICE_ID =
   "@flowscripter/dynamic-cli-framework/key-value-service";
 
+/**
+ * The sentinel prefix used to indicate a value is stored as an OS-native secret.
+ * Values starting with this prefix are resolved via the {@link SecretService}.
+ * This prefix is reserved and must not be used for regular key-value data.
+ */
+export const SECRET_SENTINEL_PREFIX = "__SECRET__:";
+
 /**
  * Service providing keystore functionality for the CLI. The keystore data is scoped to the
- * service or {@link Command} instances accessing this service via {@link Context.getServiceById}
+ * service or {@link Command} instances accessing this service via {@link Context.getServiceById}.
+ *
+ * Values can optionally be stored as OS-native secrets using the `isSecret` parameter on
+ * {@link setKey}. Secret values are stored via {@link SecretService} and only a sentinel
+ * reference is kept in the key-value Map. The sentinel prefix `__SECRET__:` is reserved.
  */
 export default interface KeyValueService {
   /**
    * Get a value for a specified key in the keystore.
+   * If the stored value is a secret sentinel, the actual value is retrieved from the OS secret store.
    */
-  getKey(key: string): string;
+  getKey(key: string): Promise<string>;
 
   /**
    * Set a value for a specified key in the keystore.
+   *
+   * @param isSecret if true, the value is stored in the OS-native secret store and a sentinel
+   *   reference is kept in the key-value Map. Requires that the service was constructed with
+   *   secret support enabled.
    */
-  setKey(key: string, value: string): void;
+  setKey(key: string, value: string, isSecret?: boolean): Promise<void>;
 
   /**
    * Check if a value for a specified key exists in the keystore.
    */
-  hasKey(key: string): boolean;
+  hasKey(key: string): Promise<boolean>;
 
   /**
    * Delete the value for a specified key in the keystore.
+   * If the stored value is a secret sentinel, the secret is also deleted from the OS secret store.
    */
-  deleteKey(key: string): void;
+  deleteKey(key: string): Promise<void>;
 }