@flowscripter/dynamic-cli-framework-api 1.4.1 → 2.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { default as Argument } from "./src/argument/Argument.ts";
-export type { SingleValueType, Values, ValueType, PopulatedSingleValueType, PopulatedValues, PopulatedValueType, } from "./src/Value.ts";
+export type { SingleValueType, Values, ValueType, ValueNode, PopulatedSingleValueType, PopulatedValues, PopulatedValueType, } from "./src/Value.ts";
 export { ValueTypeName, ComplexValueTypeName } from "./src/Value.ts";
 export type { default as ComplexOption } from "./src/argument/ComplexOption.ts";
 export { MAXIMUM_COMPLEX_OPTION_NESTING_DEPTH } from "./src/argument/ComplexOption.ts";
@@ -22,7 +22,8 @@ export type { default as AsciiBannerGeneratorService } from "./src/service/core/
 export type { BannerColorEffects, BannerGenerateOptions, ColorEffect, ColorEffectDirection, FixedColorEffect, GradientColorEffect, RainbowColorEffect, } from "./src/service/core/AsciiBannerGeneratorService.ts";
 export { KEY_VALUE_SERVICE_ID } from "./src/service/core/KeyValueService.ts";
 export { SECRET_SENTINEL_PREFIX } from "./src/service/core/KeyValueService.ts";
-export type { default as KeyValueService } from "./src/service/core/KeyValueService.ts";
+export { Secret } from "./src/service/core/KeyValueService.ts";
+export type { default as KeyValueService, SettableValueNode, } from "./src/service/core/KeyValueService.ts";
 export type { default as SecretService } from "./src/service/core/SecretService.ts";
 export { FETCH_SERVICE_ID } from "./src/service/core/FetchService.ts";
 export type { default as FetchService } from "./src/service/core/FetchService.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -5,6 +5,7 @@ export { MAXIMUM_ARGUMENT_ARRAY_SIZE } from "./src/argument/SubCommandArgument.j
 export { ASCII_BANNER_GENERATOR_SERVICE_ID } from "./src/service/core/AsciiBannerGeneratorService.js";
 export { KEY_VALUE_SERVICE_ID } from "./src/service/core/KeyValueService.js";
 export { SECRET_SENTINEL_PREFIX } from "./src/service/core/KeyValueService.js";
+export { Secret } from "./src/service/core/KeyValueService.js";
 export { FETCH_SERVICE_ID } from "./src/service/core/FetchService.js";
 export { PRINTER_SERVICE_ID } from "./src/service/core/PrinterService.js";
 export { Icon, Level, ProgressStyle, SpinnerStyle } from "./src/service/core/PrinterService.js";

package/dist/src/Value.d.ts

@@ -29,6 +29,11 @@ export type SingleValueType = number | string | boolean;
  * The type of a value can be: `boolean`, `number` or `string` or an array of these.
  */
 export type ValueType = SingleValueType | Array<SingleValueType>;
+/**
+ * Any node that can appear within a {@link Values} tree: a primitive/array-of-primitives
+ * ({@link ValueType}), a nested keyed object ({@link Values}), or an array of such objects.
+ */
+export type ValueNode = ValueType | Values | Array<Values>;
 /**
  * A container object for populated values.
  *
@@ -50,7 +55,7 @@ export type ValueType = SingleValueType | Array<SingleValueType>;
  * * `{ foo: [ [ 1, 2 ], [3, 4 ] ] }`
  */
 export type Values = {
-    [name: string]: ValueType | Values | Array<Values>;
+    [name: string]: ValueNode;
 };
 /**
  * Populated single value type is very similar to {@link SingleValueType} but allows for an illegal

package/dist/src/Value.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Value.d.ts","sourceRoot":"","sources":["../../src/Value.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,oBAAY,aAAa;IACvB,MAAM,IAAI;IACV,MAAM,IAAI;IACV,OAAO,IAAI;IACX,OAAO,IAAI;IACX,MAAM,IAAI;CACX;AAED;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,OAAO,IAAI;CACZ;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;CACpD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,eAAe,GAAG,SAAS,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,wBAAwB,GAAG,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAE5F;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,CAAC,IAAI,EAAE,MAAM,GACT,kBAAkB,GAClB,eAAe,GACf,KAAK,CAAC,eAAe,GAAG,SAAS,CAAC,GAClC,SAAS,CAAC;CACf"}
+{"version":3,"file":"Value.d.ts","sourceRoot":"","sources":["../../src/Value.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,oBAAY,aAAa;IACvB,MAAM,IAAI;IACV,MAAM,IAAI;IACV,OAAO,IAAI;IACX,OAAO,IAAI;IACX,MAAM,IAAI;CACX;AAED;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,OAAO,IAAI;CACZ;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC,CAAC;AAEjE;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,eAAe,GAAG,SAAS,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,wBAAwB,GAAG,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAE5F;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,CAAC,IAAI,EAAE,MAAM,GACT,kBAAkB,GAClB,eAAe,GACf,KAAK,CAAC,eAAe,GAAG,SAAS,CAAC,GAClC,SAAS,CAAC;CACf"}

package/dist/src/service/core/KeyValueService.d.ts

@@ -1,40 +1,74 @@
+import type { ValueNode } from "../../Value.ts";
 export declare 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}.
+ * String leaves 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 declare const SECRET_SENTINEL_PREFIX = "__SECRET__:";
+/**
+ * Wraps a value to mark it for storage as an OS-native secret via {@link SecretService}, when passed to
+ * {@link KeyValueService.set}. Can wrap the entire value passed to `set`, or be nested at any depth
+ * within a larger object/array passed to `set`.
+ */
+export declare class Secret<T extends ValueNode = ValueNode> {
+    readonly value: T;
+    constructor(value: T);
+}
+/**
+ * The shape of a value passed to {@link KeyValueService.set}.
+ *
+ * Like {@link ValueNode} (primitives, arrays of primitives, nested keyed objects, or arrays of
+ * nested objects) but additionally allows a {@link Secret}-wrapped value at any depth - as a top
+ * level value, a property of a nested object, or an entry of a nested array. A {@link Secret}
+ * itself wraps a plain {@link ValueNode}, so secrets do not nest within secrets.
+ */
+export type SettableValueNode = ValueNode | Secret | {
+    [name: string]: SettableValueNode;
+} | Array<SettableValueNode>;
 /**
  * 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}.
  *
- * 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.
+ * Values are arbitrary JSON-serializable data (see {@link ValueNode}) - not limited to
+ * strings - and may be deep objects or arrays.
+ *
+ * Any node within a value passed to {@link set} can be wrapped in {@link Secret} to have that
+ * node - and only that node - stored as an OS-native secret via {@link SecretService}, with a
+ * sentinel reference (prefixed with `__SECRET__:`) kept in its place in the stored structure.
+ * Everything else in the value is stored as plain (unencrypted) config data. This is symmetric
+ * with {@link get}, which resolves sentinel references found at any depth.
  */
 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.
+     * Get the value for a specified key in the keystore.
+     *
+     * Recursively resolves any string leaf - at any depth within the stored value - which is a
+     * secret sentinel, retrieving its actual value via {@link SecretService}. This covers both
+     * values written via {@link set} using a nested {@link Secret}, and secret references a user
+     * hand-embeds directly (nested arbitrarily deep) in the CLI's JSON config file.
      */
-    getKey(key: string): Promise<string>;
+    get<T extends ValueNode = ValueNode>(key: string): Promise<T>;
     /**
      * 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.
+     * Any node within `value` wrapped in {@link Secret} - at any depth - is serialized as JSON and
+     * stored as an OS-native secret via {@link SecretService}, with a sentinel reference kept in
+     * its place in the stored structure. All other data is stored as plain (unencrypted) config
+     * data. Storing a secret requires that the service was constructed with secret support
+     * enabled.
      */
-    setKey(key: string, value: string, isSecret?: boolean): Promise<void>;
+    set(key: string, value: SettableValueNode): Promise<void>;
     /**
      * Check if a value for a specified key exists in the keystore.
      */
-    hasKey(key: string): Promise<boolean>;
+    has(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.
+     *
+     * Recursively walks the stored (unresolved) structure for `key` and deletes every OS-native
+     * secret referenced - at any depth - via {@link SecretService}, before removing the key itself.
      */
-    deleteKey(key: string): Promise<void>;
+    delete(key: string): Promise<void>;
 }
 //# sourceMappingURL=KeyValueService.d.ts.map

package/dist/src/service/core/KeyValueService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KeyValueService.d.ts","sourceRoot":"","sources":["../../../../src/service/core/KeyValueService.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,0DAA0D,CAAC;AAE5F;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,WAAW,eAAe;IACtC;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAErC;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtE;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC"}
+{"version":3,"file":"KeyValueService.d.ts","sourceRoot":"","sources":["../../../../src/service/core/KeyValueService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,eAAO,MAAM,oBAAoB,0DAA0D,CAAC;AAE5F;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,MAAM,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;aACrB,KAAK,EAAE,CAAC;IAApC,YAA4B,KAAK,EAAE,CAAC,EAAI;CACzC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,MAAM,GACN;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAE,GACrC,KAAK,CAAC,iBAAiB,CAAC,CAAC;AAE7B;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,WAAW,eAAe;IACtC;;;;;;;OAOG;IACH,GAAG,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE9D;;;;;;;;OAQG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC"}

package/dist/src/service/core/KeyValueService.js

@@ -1,7 +1,18 @@
 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}.
+ * String leaves 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__:";
+/**
+ * Wraps a value to mark it for storage as an OS-native secret via {@link SecretService}, when passed to
+ * {@link KeyValueService.set}. Can wrap the entire value passed to `set`, or be nested at any depth
+ * within a larger object/array passed to `set`.
+ */
+export class Secret {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+}

package/dist/src/service/core/UpgradeService.d.ts

@@ -24,16 +24,30 @@ export declare enum InstallMethod {
     GITHUB_RELEASE = "github-release"
 }
 /**
- * Outcome of an {@link UpgradeService.checkForUpgrade} call.
+ * Outcome of an {@link UpgradeService.checkForUpgrade} or {@link UpgradeService.getUpgradeCheckResult}
+ * call. The `"pending"` status can only be produced by {@link UpgradeService.getUpgradeCheckResult}'s
+ * non-blocking bounded wait - `checkForUpgrade()` and a `getUpgradeCheckResult(true)` call always
+ * run to completion and so never resolve to it.
  */
-export interface UpgradeCheckResult {
+export type UpgradeCheckResult = {
+    readonly status: "checked";
     readonly currentVersion: string;
     readonly latestVersion: string;
     readonly updateAvailable: boolean;
     readonly os: SupportedOs;
     readonly arch: SupportedArch;
     readonly installMethod: InstallMethod;
-}
+} | {
+    /** The resolved (or overridden) os/arch/installMethod combination is not supported or not configured. */
+    readonly status: "unsupported";
+} | {
+    /** A supported/configured combination was found, but determining the latest version failed. */
+    readonly status: "failed";
+    readonly error: Error;
+} | {
+    /** The non-blocking bounded wait elapsed before the check completed. */
+    readonly status: "pending";
+};
 /**
  * Outcome of an {@link UpgradeService.upgrade} call.
  */
@@ -74,10 +88,10 @@ export default interface UpgradeService {
      * @param arch optional {@link SupportedArch} override, defaults to the detected value.
      * @param installMethod optional {@link InstallMethod} override, defaults to the detected value.
      *
-     * @return the {@link UpgradeCheckResult}, or `undefined` if the resolved os/arch/installMethod
-     * combination is not supported or not configured. Never rejects.
+     * @return the {@link UpgradeCheckResult}. Runs to completion, so never resolves to the
+     * `"pending"` status. Never rejects.
      */
-    checkForUpgrade(os?: SupportedOs, arch?: SupportedArch, installMethod?: InstallMethod): Promise<UpgradeCheckResult | undefined>;
+    checkForUpgrade(os?: SupportedOs, arch?: SupportedArch, installMethod?: InstallMethod): Promise<UpgradeCheckResult>;
     /**
      * Upgrade the CLI to the latest available version.
      *
@@ -93,13 +107,13 @@ export default interface UpgradeService {
      * dependencies were set (or starts one now, with default/no-override detection, if none has
      * started yet). Every call is backed by the same cached promise.
      *
-     * @param waitForResult if `true`, waits for the check to fully resolve. If `false` (default),
-     * gives up and resolves to `undefined` after an internal bounded delay, so callers on a
-     * startup/opportunistic path are never blocked by a slow network/spawn call.
+     * @param waitForResult if `true`, waits for the check to fully resolve, so the result never has
+     * status `"pending"`. If `false` (default), gives up and resolves to a `"pending"` result after
+     * an internal bounded delay, so callers on a startup/opportunistic path are never blocked by a
+     * slow network/spawn call.
      *
-     * @return the {@link UpgradeCheckResult}, or `undefined` if unsupported/unconfigured or the
-     * bounded wait elapsed. Never rejects.
+     * @return the {@link UpgradeCheckResult}. Never rejects.
      */
-    getUpgradeCheckResult(waitForResult?: boolean): Promise<UpgradeCheckResult | undefined>;
+    getUpgradeCheckResult(waitForResult?: boolean): Promise<UpgradeCheckResult>;
 }
 //# sourceMappingURL=UpgradeService.d.ts.map

package/dist/src/service/core/UpgradeService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UpgradeService.d.ts","sourceRoot":"","sources":["../../../../src/service/core/UpgradeService.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,wDAAwD,CAAC;AAExF;;GAEG;AACH,oBAAY,WAAW;IACrB,KAAK,UAAU;IACf,KAAK,UAAU;IACf,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,oBAAY,aAAa;IACvB,GAAG,QAAQ;IACX,KAAK,UAAU;CAChB;AAED;;GAEG;AACH,oBAAY,aAAa;IACvB,YAAY,iBAAiB;IAC7B,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,cAAc,mBAAmB;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,WAAW,cAAc;IACrC;;;;OAIG;IACH,QAAQ,IAAI,WAAW,GAAG,SAAS,CAAC;IAEpC;;;;OAIG;IACH,UAAU,IAAI,aAAa,GAAG,SAAS,CAAC;IAExC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IAEzE;;;;;;;;;OASG;IACH,eAAe,CACb,EAAE,CAAC,EAAE,WAAW,EAChB,IAAI,CAAC,EAAE,aAAa,EACpB,aAAa,CAAC,EAAE,aAAa,GAC5B,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAE3C;;;;;;;;OAQG;IACH,OAAO,CACL,EAAE,CAAC,EAAE,WAAW,EAChB,IAAI,CAAC,EAAE,aAAa,EACpB,aAAa,CAAC,EAAE,aAAa,GAC5B,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B;;;;;;;;;;;OAWG;IACH,qBAAqB,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;CACzF"}
+{"version":3,"file":"UpgradeService.d.ts","sourceRoot":"","sources":["../../../../src/service/core/UpgradeService.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,wDAAwD,CAAC;AAExF;;GAEG;AACH,oBAAY,WAAW;IACrB,KAAK,UAAU;IACf,KAAK,UAAU;IACf,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,oBAAY,aAAa;IACvB,GAAG,QAAQ;IACX,KAAK,UAAU;CAChB;AAED;;GAEG;AACH,oBAAY,aAAa;IACvB,YAAY,iBAAiB;IAC7B,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,cAAc,mBAAmB;CAClC;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;CACvC,GACD;IACE,yGAAyG;IACzG,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC,GACD;IACE,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB,GACD;IACE,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;CAC5B,CAAC;AAEN;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,WAAW,cAAc;IACrC;;;;OAIG;IACH,QAAQ,IAAI,WAAW,GAAG,SAAS,CAAC;IAEpC;;;;OAIG;IACH,UAAU,IAAI,aAAa,GAAG,SAAS,CAAC;IAExC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IAEzE;;;;;;;;;OASG;IACH,eAAe,CACb,EAAE,CAAC,EAAE,WAAW,EAChB,IAAI,CAAC,EAAE,aAAa,EACpB,aAAa,CAAC,EAAE,aAAa,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/B;;;;;;;;OAQG;IACH,OAAO,CACL,EAAE,CAAC,EAAE,WAAW,EAChB,IAAI,CAAC,EAAE,aAAa,EACpB,aAAa,CAAC,EAAE,aAAa,GAC5B,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B;;;;;;;;;;;OAWG;IACH,qBAAqB,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC7E"}

package/index.ts

@@ -4,6 +4,7 @@ export type {
   SingleValueType,
   Values,
   ValueType,
+  ValueNode,
   PopulatedSingleValueType,
   PopulatedValues,
   PopulatedValueType,
@@ -47,7 +48,11 @@ export type {
 
 export { KEY_VALUE_SERVICE_ID } from "./src/service/core/KeyValueService.ts";
 export { SECRET_SENTINEL_PREFIX } from "./src/service/core/KeyValueService.ts";
-export type { default as KeyValueService } from "./src/service/core/KeyValueService.ts";
+export { Secret } from "./src/service/core/KeyValueService.ts";
+export type {
+  default as KeyValueService,
+  SettableValueNode,
+} from "./src/service/core/KeyValueService.ts";
 export type { default as SecretService } from "./src/service/core/SecretService.ts";
 
 export { FETCH_SERVICE_ID } from "./src/service/core/FetchService.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowscripter/dynamic-cli-framework-api",
-  "version": "1.4.1",
+  "version": "2.0.0",
   "description": "API for https://github.com/flowscripter/dynamic-cli-framework",
   "keywords": [
     "bun",

package/src/Value.ts

@@ -34,6 +34,12 @@ export type SingleValueType = number | string | boolean;
  */
 export type ValueType = SingleValueType | Array<SingleValueType>;
 
+/**
+ * Any node that can appear within a {@link Values} tree: a primitive/array-of-primitives
+ * ({@link ValueType}), a nested keyed object ({@link Values}), or an array of such objects.
+ */
+export type ValueNode = ValueType | Values | Array<Values>;
+
 /**
  * A container object for populated values.
  *
@@ -55,7 +61,7 @@ export type ValueType = SingleValueType | Array<SingleValueType>;
  * * `{ foo: [ [ 1, 2 ], [3, 4 ] ] }`
  */
 export type Values = {
-  [name: string]: ValueType | Values | Array<Values>;
+  [name: string]: ValueNode;
 };
 
 /**

package/src/service/core/KeyValueService.ts

@@ -1,44 +1,82 @@
+import type { ValueNode } from "../../Value.ts";
+
 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}.
+ * String leaves 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__:";
 
+/**
+ * Wraps a value to mark it for storage as an OS-native secret via {@link SecretService}, when passed to
+ * {@link KeyValueService.set}. Can wrap the entire value passed to `set`, or be nested at any depth
+ * within a larger object/array passed to `set`.
+ */
+export class Secret<T extends ValueNode = ValueNode> {
+  constructor(public readonly value: T) {}
+}
+
+/**
+ * The shape of a value passed to {@link KeyValueService.set}.
+ *
+ * Like {@link ValueNode} (primitives, arrays of primitives, nested keyed objects, or arrays of
+ * nested objects) but additionally allows a {@link Secret}-wrapped value at any depth - as a top
+ * level value, a property of a nested object, or an entry of a nested array. A {@link Secret}
+ * itself wraps a plain {@link ValueNode}, so secrets do not nest within secrets.
+ */
+export type SettableValueNode =
+  | ValueNode
+  | Secret
+  | { [name: string]: SettableValueNode }
+  | Array<SettableValueNode>;
+
 /**
  * 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}.
  *
- * 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.
+ * Values are arbitrary JSON-serializable data (see {@link ValueNode}) - not limited to
+ * strings - and may be deep objects or arrays.
+ *
+ * Any node within a value passed to {@link set} can be wrapped in {@link Secret} to have that
+ * node - and only that node - stored as an OS-native secret via {@link SecretService}, with a
+ * sentinel reference (prefixed with `__SECRET__:`) kept in its place in the stored structure.
+ * Everything else in the value is stored as plain (unencrypted) config data. This is symmetric
+ * with {@link get}, which resolves sentinel references found at any depth.
  */
 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.
+   * Get the value for a specified key in the keystore.
+   *
+   * Recursively resolves any string leaf - at any depth within the stored value - which is a
+   * secret sentinel, retrieving its actual value via {@link SecretService}. This covers both
+   * values written via {@link set} using a nested {@link Secret}, and secret references a user
+   * hand-embeds directly (nested arbitrarily deep) in the CLI's JSON config file.
    */
-  getKey(key: string): Promise<string>;
+  get<T extends ValueNode = ValueNode>(key: string): Promise<T>;
 
   /**
    * 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.
+   * Any node within `value` wrapped in {@link Secret} - at any depth - is serialized as JSON and
+   * stored as an OS-native secret via {@link SecretService}, with a sentinel reference kept in
+   * its place in the stored structure. All other data is stored as plain (unencrypted) config
+   * data. Storing a secret requires that the service was constructed with secret support
+   * enabled.
    */
-  setKey(key: string, value: string, isSecret?: boolean): Promise<void>;
+  set(key: string, value: SettableValueNode): Promise<void>;
 
   /**
    * Check if a value for a specified key exists in the keystore.
    */
-  hasKey(key: string): Promise<boolean>;
+  has(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.
+   *
+   * Recursively walks the stored (unresolved) structure for `key` and deletes every OS-native
+   * secret referenced - at any depth - via {@link SecretService}, before removing the key itself.
    */
-  deleteKey(key: string): Promise<void>;
+  delete(key: string): Promise<void>;
 }

package/src/service/core/UpgradeService.ts

@@ -28,16 +28,34 @@ export enum InstallMethod {
 }
 
 /**
- * Outcome of an {@link UpgradeService.checkForUpgrade} call.
+ * Outcome of an {@link UpgradeService.checkForUpgrade} or {@link UpgradeService.getUpgradeCheckResult}
+ * call. The `"pending"` status can only be produced by {@link UpgradeService.getUpgradeCheckResult}'s
+ * non-blocking bounded wait - `checkForUpgrade()` and a `getUpgradeCheckResult(true)` call always
+ * run to completion and so never resolve to it.
  */
-export interface UpgradeCheckResult {
-  readonly currentVersion: string;
-  readonly latestVersion: string;
-  readonly updateAvailable: boolean;
-  readonly os: SupportedOs;
-  readonly arch: SupportedArch;
-  readonly installMethod: InstallMethod;
-}
+export type UpgradeCheckResult =
+  | {
+      readonly status: "checked";
+      readonly currentVersion: string;
+      readonly latestVersion: string;
+      readonly updateAvailable: boolean;
+      readonly os: SupportedOs;
+      readonly arch: SupportedArch;
+      readonly installMethod: InstallMethod;
+    }
+  | {
+      /** The resolved (or overridden) os/arch/installMethod combination is not supported or not configured. */
+      readonly status: "unsupported";
+    }
+  | {
+      /** A supported/configured combination was found, but determining the latest version failed. */
+      readonly status: "failed";
+      readonly error: Error;
+    }
+  | {
+      /** The non-blocking bounded wait elapsed before the check completed. */
+      readonly status: "pending";
+    };
 
 /**
  * Outcome of an {@link UpgradeService.upgrade} call.
@@ -83,14 +101,14 @@ export default interface UpgradeService {
    * @param arch optional {@link SupportedArch} override, defaults to the detected value.
    * @param installMethod optional {@link InstallMethod} override, defaults to the detected value.
    *
-   * @return the {@link UpgradeCheckResult}, or `undefined` if the resolved os/arch/installMethod
-   * combination is not supported or not configured. Never rejects.
+   * @return the {@link UpgradeCheckResult}. Runs to completion, so never resolves to the
+   * `"pending"` status. Never rejects.
    */
   checkForUpgrade(
     os?: SupportedOs,
     arch?: SupportedArch,
     installMethod?: InstallMethod,
-  ): Promise<UpgradeCheckResult | undefined>;
+  ): Promise<UpgradeCheckResult>;
 
   /**
    * Upgrade the CLI to the latest available version.
@@ -112,12 +130,12 @@ export default interface UpgradeService {
    * dependencies were set (or starts one now, with default/no-override detection, if none has
    * started yet). Every call is backed by the same cached promise.
    *
-   * @param waitForResult if `true`, waits for the check to fully resolve. If `false` (default),
-   * gives up and resolves to `undefined` after an internal bounded delay, so callers on a
-   * startup/opportunistic path are never blocked by a slow network/spawn call.
+   * @param waitForResult if `true`, waits for the check to fully resolve, so the result never has
+   * status `"pending"`. If `false` (default), gives up and resolves to a `"pending"` result after
+   * an internal bounded delay, so callers on a startup/opportunistic path are never blocked by a
+   * slow network/spawn call.
    *
-   * @return the {@link UpgradeCheckResult}, or `undefined` if unsupported/unconfigured or the
-   * bounded wait elapsed. Never rejects.
+   * @return the {@link UpgradeCheckResult}. Never rejects.
    */
-  getUpgradeCheckResult(waitForResult?: boolean): Promise<UpgradeCheckResult | undefined>;
+  getUpgradeCheckResult(waitForResult?: boolean): Promise<UpgradeCheckResult>;
 }