@flowscripter/dynamic-cli-framework 12.1.0 → 12.2.0

package/dist/src/service/configuration/configTargets.js

@@ -0,0 +1,348 @@
+import { MAXIMUM_COMPLEX_OPTION_NESTING_DEPTH, SECRET_SENTINEL_PREFIX, ValueTypeName, } from "@flowscripter/dynamic-cli-framework-api";
+import { isComplexOption } from "../../runtime/argument/ArgumentTypeGuards.js";
+import { getInvalidArgumentString, runCustomValidation, validateGlobalCommandArgumentValue, validateOptionValue, } from "../../runtime/values/argumentValueValidation.js";
+import { getGlobalCommandValueFromEnvVars, getSubCommandValuesFromEnvVars, } from "../../util/envVarHelper.js";
+import { isGlobalModifierCommand } from "../../runtime/command/CommandTypeGuards.js";
+export const MASK = "********";
+/**
+ * Collect all commands in the registry with `enableConfiguration` set, except the `config` modifier.
+ */
+export function getConfigTargets(registry) {
+    const targets = new Map();
+    const globals = [...registry.getGlobalCommands(), ...registry.getGlobalModifierCommands()];
+    for (const command of globals) {
+        if (command.enableConfiguration !== true || command.argument === undefined) {
+            continue;
+        }
+        if (isGlobalModifierCommand(command) && command.name === "config") {
+            continue;
+        }
+        targets.set(command.name, {
+            key: command.name,
+            command,
+            argument: command.argument,
+            options: [],
+        });
+    }
+    for (const command of registry.getSubCommands()) {
+        if (command.enableConfiguration === true) {
+            targets.set(command.name, { key: command.name, command, options: command.options });
+        }
+    }
+    for (const [key, { groupCommand, command }] of registry.getGroupAndMemberCommandsByJoinedName()) {
+        if (command.enableConfiguration === true) {
+            targets.set(key, { key, command, group: groupCommand, options: command.options });
+        }
+    }
+    return targets;
+}
+/**
+ * Parse an option path such as `address[1].port` into steps.
+ */
+export function parseOptionPath(path) {
+    const elements = path.split(".");
+    if (elements.length > MAXIMUM_COMPLEX_OPTION_NESTING_DEPTH) {
+        return `option path '${path}' exceeds the maximum nesting depth`;
+    }
+    const steps = [];
+    for (const element of elements) {
+        const match = /^([^[\]]+)(?:\[(\d+)\])?$/.exec(element);
+        if (match === null) {
+            return `invalid option path '${path}'`;
+        }
+        steps.push(match[2] === undefined ? { name: match[1] } : { name: match[1], index: Number(match[2]) });
+    }
+    return steps;
+}
+/**
+ * Walk the steps through the target's options returning the option the path refers to.
+ */
+export function resolveOptionPath(target, path) {
+    const steps = parseOptionPath(path);
+    if (typeof steps === "string") {
+        return steps;
+    }
+    let candidates = target.options;
+    let leaf;
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        leaf = candidates.find((o) => o.name === step.name);
+        if (leaf === undefined) {
+            return `unknown option '${step.name}' in '${path}'`;
+        }
+        if (step.index !== undefined && leaf.isArray !== true) {
+            return `option '${step.name}' is not an array`;
+        }
+        if (i < steps.length - 1) {
+            if (!isComplexOption(leaf)) {
+                return `option '${step.name}' has no properties`;
+            }
+            if (leaf.isArray === true && step.index === undefined) {
+                return `option '${step.name}' is an array and requires an index`;
+            }
+            candidates = leaf.properties;
+        }
+    }
+    return { steps, leaf: leaf };
+}
+export function containsSecret(option) {
+    if (isComplexOption(option)) {
+        return option.properties.some(containsSecret);
+    }
+    return option.type === ValueTypeName.SECRET;
+}
+function asOptional(option) {
+    if (isComplexOption(option)) {
+        return {
+            ...option,
+            isOptional: true,
+            properties: option.properties.map(asOptional),
+        };
+    }
+    return { ...option, isOptional: true };
+}
+function clone(value) {
+    return value === undefined ? value : structuredClone(value);
+}
+export function getAtPath(root, steps) {
+    let current = root;
+    for (const step of steps) {
+        if (typeof current !== "object" || current === null) {
+            return undefined;
+        }
+        current = current[step.name];
+        if (step.index !== undefined) {
+            if (!Array.isArray(current)) {
+                return undefined;
+            }
+            current = current[step.index];
+        }
+    }
+    return current;
+}
+/**
+ * Set a value at the path in the provided (mutable) root creating parents as needed.
+ */
+export function setAtPath(root, steps, value) {
+    let container = root;
+    steps.forEach((step, i) => {
+        const isLast = i === steps.length - 1;
+        if (step.index === undefined) {
+            if (isLast) {
+                container[step.name] = value;
+                return;
+            }
+            if (typeof container[step.name] !== "object" || container[step.name] === null) {
+                container[step.name] = {};
+            }
+            container = container[step.name];
+            return;
+        }
+        if (!Array.isArray(container[step.name])) {
+            container[step.name] = [];
+        }
+        const array = container[step.name];
+        if (step.index > array.length) {
+            throw new Error(`cannot set '${step.name}[${step.index}]': array has ${array.length} element(s) and sparse arrays are not supported`);
+        }
+        if (isLast) {
+            array[step.index] = value;
+            return;
+        }
+        if (typeof array[step.index] !== "object" || array[step.index] === null) {
+            array[step.index] = {};
+        }
+        container = array[step.index];
+    });
+}
+/**
+ * Remove the value at the path and any parent objects left empty. Returns false if there was no value.
+ */
+export function removeAtPath(root, steps) {
+    if (getAtPath(root, steps) === undefined) {
+        return false;
+    }
+    const last = steps[steps.length - 1];
+    if (last.index !== undefined) {
+        throw new Error("unsetting an array element is not supported: unset the whole option instead");
+    }
+    const parents = [root];
+    let container = root;
+    for (const step of steps.slice(0, -1)) {
+        container =
+            step.index === undefined
+                ? container[step.name]
+                : container[step.name][step.index];
+        parents.push(container);
+    }
+    delete container[last.name];
+    for (let i = steps.length - 2; i >= 0; i--) {
+        const step = steps[i];
+        if (step.index !== undefined || Object.keys(parents[i + 1]).length > 0) {
+            break;
+        }
+        delete parents[i][step.name];
+    }
+    return true;
+}
+/**
+ * All `__SECRET__:` sentinel strings within the value.
+ */
+export function collectSentinels(value) {
+    if (typeof value === "string") {
+        return value.startsWith(SECRET_SENTINEL_PREFIX) ? [value] : [];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap(collectSentinels);
+    }
+    if (typeof value === "object" && value !== null) {
+        return Object.values(value).flatMap(collectSentinels);
+    }
+    return [];
+}
+/**
+ * @param secrets plain text SECRET values which must not appear in the message.
+ */
+function invalidMessage(invalid, secrets = []) {
+    return invalid
+        .map((i) => {
+        const hidden = secrets.includes(i.value) ? { ...i, value: undefined } : i;
+        return getInvalidArgumentString(hidden, false) + (i.message ?? "");
+    })
+        .join("; ");
+}
+/**
+ * Validate and convert the raw (string) value for the option path of the target. Required checks are
+ * not applied. Custom validators of the target are run later by {@link validateChanges}.
+ */
+export function prepareChange(target, path, raw, deferred) {
+    const resolved = resolveOptionPath(target, path);
+    if (typeof resolved === "string") {
+        return resolved;
+    }
+    const { steps, leaf } = resolved;
+    const hasIndex = steps[steps.length - 1].index !== undefined;
+    const whole = isComplexOption(leaf) || (leaf.isArray === true && !hasIndex);
+    const invalid = [];
+    let value;
+    if (whole) {
+        if (!/^\s*[[{]/.test(raw)) {
+            return `option '${path}' requires a JSON ${leaf.isArray === true && !hasIndex ? "array" : "object"} value`;
+        }
+        if (containsSecret(leaf)) {
+            return `option '${path}' contains SECRET values: set each secret property individually`;
+        }
+        try {
+            value = JSON.parse(raw);
+        }
+        catch (err) {
+            return `invalid JSON value for '${path}': ${err.message}`;
+        }
+        value = validateOptionValue(asOptional(leaf), value, invalid, deferred);
+    }
+    else {
+        value = validateOptionValue({ ...asOptional(leaf), isArray: false }, raw, invalid, deferred);
+    }
+    if (invalid.length > 0) {
+        return `${path}: ${invalidMessage(invalid, [raw])}`;
+    }
+    const isSecret = !isComplexOption(leaf) && leaf.type === ValueTypeName.SECRET;
+    return { steps, path, leaf, value, isSecret };
+}
+/**
+ * Validate a raw value for a global command argument.
+ */
+export function prepareGlobalValue(target, raw, deferred) {
+    const invalid = [];
+    const argument = { ...target.argument, isOptional: true };
+    const value = validateGlobalCommandArgumentValue({ ...target.command, argument }, raw, invalid, deferred);
+    if (invalid.length > 0 || value === undefined) {
+        return invalidMessage(invalid, [raw]);
+    }
+    return { value, isSecret: target.argument.type === ValueTypeName.SECRET };
+}
+/**
+ * Apply the changes to a copy of the existing values and run the custom validators of the target.
+ * Returns the new values or an error message.
+ */
+export function applyChanges(target, existing, changes, deferred) {
+    const values = clone(existing ?? {});
+    try {
+        for (const change of changes) {
+            setAtPath(values, change.steps, change.value);
+        }
+    }
+    catch (err) {
+        return err.message;
+    }
+    const invalid = [];
+    runCustomValidation(deferred, target.command, values, invalid);
+    if (invalid.length > 0) {
+        return invalidMessage(invalid, changes.filter((c) => c.isSecret).map((c) => c.value));
+    }
+    return values;
+}
+function maskSentinels(value) {
+    if (typeof value === "string") {
+        return value.startsWith(SECRET_SENTINEL_PREFIX) ? MASK : value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(maskSentinels);
+    }
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, maskSentinels(v)]));
+    }
+    return value;
+}
+function maskOption(option, value) {
+    if (value === undefined || value === null) {
+        return value;
+    }
+    if (isComplexOption(option)) {
+        if (Array.isArray(value)) {
+            return value.map((v) => maskOption({ ...option, isArray: false }, v));
+        }
+        return maskOptions(option.properties, value);
+    }
+    if (option.type === ValueTypeName.SECRET) {
+        return Array.isArray(value) ? value.map(() => MASK) : MASK;
+    }
+    return value;
+}
+function maskOptions(options, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([name, v]) => {
+        const option = options.find((o) => o.name === name);
+        return [name, option === undefined ? v : maskOption(option, v)];
+    }));
+}
+/**
+ * Copy of a stored default value with SECRET typed values and any secret sentinels masked.
+ */
+export function maskDefault(target, value) {
+    let masked = value;
+    if (target?.argument !== undefined) {
+        if (target.argument.type === ValueTypeName.SECRET && value !== undefined) {
+            masked = MASK;
+        }
+    }
+    else if (target !== undefined) {
+        masked = maskOptions(target.options, value);
+    }
+    return maskSentinels(masked);
+}
+/**
+ * Whether an environment variable would override the stored value at the path.
+ */
+export function isOverriddenByEnvVar(provider, cliConfig, target, steps) {
+    if (!provider.envVarsEnabled) {
+        return false;
+    }
+    if (target.argument !== undefined) {
+        return (getGlobalCommandValueFromEnvVars(cliConfig, target.command) !== undefined);
+    }
+    const values = getSubCommandValuesFromEnvVars(cliConfig, target.command, target.group);
+    return getAtPath(values, steps) !== undefined;
+}

package/dist/src/service/configuration/resolveSecrets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveSecrets.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/resolveSecrets.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAA8B,cAAc,CAAC,CAAC,EAC5C,KAAK,EAAE,CAAC,EACR,aAAa,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GACzD,OAAO,CAAC,CAAC,CAAC,CAoBZ"}
+{"version":3,"file":"resolveSecrets.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/resolveSecrets.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAA8B,cAAc,CAAC,CAAC,EAC5C,KAAK,EAAE,CAAC,EACR,aAAa,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GACzD,OAAO,CAAC,CAAC,CAAC,CA0BZ"}

package/dist/src/service/configuration/resolveSecrets.js

@@ -23,7 +23,13 @@ export default async function resolveSecrets(value, resolveSecret) {
         }
         const resolved = {};
         for (const [key, val] of Object.entries(value)) {
-            resolved[key] = await resolveSecrets(val, resolveSecret);
+            // defineProperty so a "__proto__" key is an own property rather than replacing the prototype
+            Object.defineProperty(resolved, key, {
+                value: await resolveSecrets(val, resolveSecret),
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
         }
         return resolved;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowscripter/dynamic-cli-framework",
-  "version": "12.1.0",
+  "version": "12.2.0",
   "description": "A framework for developing CLI applications which supports dynamic discovery and installation of new commands",
   "keywords": [
     "bun",

package/src/cli/BaseCLI.ts

@@ -395,6 +395,7 @@ export default class BaseCLI implements CLI {
       this.#options.configFileSupportEnabled,
       this.#options.secretServiceEnabled,
       this.#options.configFormat,
+      this.#commandRegistry,
     );
     this.addServiceProvider(configurationServiceProvider);
     const keyValueServiceProvider = new KeyValueServiceProvider(

package/src/runtime/runner.ts

@@ -121,8 +121,11 @@ async function executeParsedCommand(
       parseResult!.populatedArgumentValues,
     );
 
+    const commandScopeKey = parseResult.groupCommand
+      ? `${parseResult.groupCommand.name}:${parseResult.command.name}`
+      : parseResult.command.name;
     const commandContext = keyValueServiceProvider
-      ? keyValueServiceProvider.getContextForScope(context, "command", parseResult.command.name)
+      ? keyValueServiceProvider.getContextForScope(context, "command", commandScopeKey)
       : context;
     if (isSubCommand(parseResult.command)) {
       await parseResult.command.execute(