codify-plugin-lib 1.0.75 → 1.0.77

package/dist/resource/resource-controller.js

@@ -0,0 +1,247 @@
+import { Ajv } from 'ajv';
+import { ParameterOperation, ResourceOperation } from 'codify-schemas';
+import { Plan } from '../plan/plan.js';
+import { ConfigParser } from './config-parser.js';
+import { ParsedResourceSettings } from './parsed-resource-settings.js';
+export class ResourceController {
+    resource;
+    settings;
+    parsedSettings;
+    typeId;
+    dependencies;
+    ajv;
+    schemaValidator;
+    constructor(resource) {
+        this.resource = resource;
+        this.settings = resource.getSettings();
+        this.typeId = this.settings.id;
+        this.dependencies = this.settings.dependencies ?? [];
+        if (this.settings.schema) {
+            this.ajv = new Ajv({
+                allErrors: true,
+                strict: true,
+                strictRequired: false,
+            });
+            this.schemaValidator = this.ajv.compile(this.settings.schema);
+        }
+        this.parsedSettings = new ParsedResourceSettings(this.settings);
+    }
+    async initialize() {
+        return this.resource.initialize();
+    }
+    async validate(parameters, resourceMetaData) {
+        if (this.schemaValidator) {
+            const isValid = this.schemaValidator(parameters);
+            if (!isValid) {
+                return {
+                    isValid: false,
+                    resourceName: resourceMetaData.name,
+                    resourceType: resourceMetaData.type,
+                    schemaValidationErrors: this.schemaValidator?.errors ?? [],
+                };
+            }
+        }
+        let isValid = true;
+        let customValidationErrorMessage;
+        try {
+            await this.resource.validate(parameters);
+        }
+        catch (error) {
+            isValid = false;
+            customValidationErrorMessage = error.message;
+        }
+        if (!isValid) {
+            return {
+                customValidationErrorMessage,
+                isValid: false,
+                resourceName: resourceMetaData.name,
+                resourceType: resourceMetaData.type,
+                schemaValidationErrors: this.schemaValidator?.errors ?? [],
+            };
+        }
+        return {
+            isValid: true,
+            resourceName: resourceMetaData.name,
+            resourceType: resourceMetaData.type,
+            schemaValidationErrors: [],
+        };
+    }
+    async plan(desiredConfig, stateConfig = null, statefulMode = false) {
+        this.validatePlanInputs(desiredConfig, stateConfig, statefulMode);
+        this.addDefaultValues(desiredConfig);
+        await this.applyTransformParameters(desiredConfig);
+        // Parse data from the user supplied config
+        const parsedConfig = new ConfigParser(desiredConfig, stateConfig, this.parsedSettings.statefulParameters);
+        const { coreParameters, desiredParameters, stateParameters, allNonStatefulParameters, allStatefulParameters, } = parsedConfig;
+        // Refresh resource parameters. This refreshes the parameters that configure the resource itself
+        const currentParametersArray = await this.refreshNonStatefulParameters(allNonStatefulParameters);
+        // Short circuit here. If the resource is non-existent, there's no point checking stateful parameters
+        if (currentParametersArray === null
+            || currentParametersArray === undefined
+            || this.settings.allowMultiple // Stateful parameters are not supported currently if allowMultiple is true
+            || currentParametersArray.length === 0
+            || currentParametersArray.filter(Boolean).length === 0) {
+            return Plan.calculate({
+                desiredParameters,
+                currentParametersArray,
+                stateParameters,
+                coreParameters,
+                settings: this.parsedSettings,
+                statefulMode,
+            });
+        }
+        // Refresh stateful parameters. These parameters have state external to the resource. allowMultiple
+        // does not work together with stateful parameters
+        const statefulCurrentParameters = await this.refreshStatefulParameters(allStatefulParameters);
+        return Plan.calculate({
+            desiredParameters,
+            currentParametersArray: [{ ...currentParametersArray[0], ...statefulCurrentParameters }],
+            stateParameters,
+            coreParameters,
+            settings: this.parsedSettings,
+            statefulMode
+        });
+    }
+    async apply(plan) {
+        if (plan.getResourceType() !== this.typeId) {
+            throw new Error(`Internal error: Plan set to wrong resource during apply. Expected ${this.typeId} but got: ${plan.getResourceType()}`);
+        }
+        switch (plan.changeSet.operation) {
+            case ResourceOperation.CREATE: {
+                return this.applyCreate(plan);
+            }
+            case ResourceOperation.MODIFY: {
+                return this.applyModify(plan);
+            }
+            case ResourceOperation.RECREATE: {
+                await this.applyDestroy(plan);
+                return this.applyCreate(plan);
+            }
+            case ResourceOperation.DESTROY: {
+                return this.applyDestroy(plan);
+            }
+        }
+    }
+    async applyCreate(plan) {
+        await this.resource.create(plan);
+        const statefulParameterChanges = this.getSortedStatefulParameterChanges(plan.changeSet.parameterChanges);
+        for (const parameterChange of statefulParameterChanges) {
+            const statefulParameter = this.parsedSettings.statefulParameters.get(parameterChange.name);
+            await statefulParameter.add(parameterChange.newValue, plan);
+        }
+    }
+    async applyModify(plan) {
+        const parameterChanges = plan
+            .changeSet
+            .parameterChanges
+            .filter((c) => c.operation !== ParameterOperation.NOOP);
+        const statelessParameterChanges = parameterChanges
+            .filter((pc) => !this.parsedSettings.statefulParameters.has(pc.name));
+        for (const pc of statelessParameterChanges) {
+            await this.resource.modify(pc, plan);
+        }
+        const statefulParameterChanges = this.getSortedStatefulParameterChanges(plan.changeSet.parameterChanges);
+        for (const parameterChange of statefulParameterChanges) {
+            const statefulParameter = this.parsedSettings.statefulParameters.get(parameterChange.name);
+            switch (parameterChange.operation) {
+                case ParameterOperation.ADD: {
+                    await statefulParameter.add(parameterChange.newValue, plan);
+                    break;
+                }
+                case ParameterOperation.MODIFY: {
+                    await statefulParameter.modify(parameterChange.newValue, parameterChange.previousValue, plan);
+                    break;
+                }
+                case ParameterOperation.REMOVE: {
+                    await statefulParameter.remove(parameterChange.previousValue, plan);
+                    break;
+                }
+            }
+        }
+    }
+    async applyDestroy(plan) {
+        // If this option is set (defaults to false), then stateful parameters need to be destroyed
+        // as well. This means that the stateful parameter wouldn't have been normally destroyed with applyDestroy()
+        if (this.settings.removeStatefulParametersBeforeDestroy) {
+            const statefulParameterChanges = this.getSortedStatefulParameterChanges(plan.changeSet.parameterChanges);
+            for (const parameterChange of statefulParameterChanges) {
+                const statefulParameter = this.parsedSettings.statefulParameters.get(parameterChange.name);
+                await statefulParameter.remove(parameterChange.previousValue, plan);
+            }
+        }
+        await this.resource.destroy(plan);
+    }
+    validateRefreshResults(refresh) {
+        if (!refresh) {
+            return;
+        }
+        if (!this.settings.allowMultiple && refresh.length > 1) {
+            throw new Error(`Resource: ${this.settings.id}. Allow multiple was set to false but multiple refresh results were returned.
+
+${JSON.stringify(refresh, null, 2)}     
+`);
+        }
+    }
+    async applyTransformParameters(desired) {
+        if (!desired) {
+            return;
+        }
+        for (const [key, inputTransformation] of Object.entries(this.parsedSettings.inputTransformations)) {
+            if (desired[key] === undefined || !inputTransformation) {
+                continue;
+            }
+            desired[key] = await inputTransformation(desired[key]);
+        }
+        if (this.settings.inputTransformation) {
+            const transformed = await this.settings.inputTransformation(desired);
+            Object.keys(desired).forEach((k) => delete desired[k]);
+            Object.assign(desired, transformed);
+        }
+    }
+    addDefaultValues(desired) {
+        if (!desired) {
+            return;
+        }
+        for (const [key, defaultValue] of Object.entries(this.parsedSettings.defaultValues)) {
+            if (defaultValue !== undefined && (desired[key] === undefined || desired[key] === null)) {
+                desired[key] = defaultValue;
+            }
+        }
+    }
+    async refreshNonStatefulParameters(resourceParameters) {
+        const result = await this.resource.refresh(resourceParameters);
+        const currentParametersArray = Array.isArray(result) || result === null
+            ? result
+            : [result];
+        this.validateRefreshResults(currentParametersArray);
+        return currentParametersArray;
+    }
+    // Refresh stateful parameters
+    // This refreshes parameters that are stateful (they can be added, deleted separately from the resource)
+    async refreshStatefulParameters(statefulParametersConfig) {
+        const result = {};
+        const sortedEntries = Object.entries(statefulParametersConfig)
+            .sort(([key1], [key2]) => this.parsedSettings.statefulParameterOrder.get(key1) - this.parsedSettings.statefulParameterOrder.get(key2));
+        for (const [key, desiredValue] of sortedEntries) {
+            const statefulParameter = this.parsedSettings.statefulParameters.get(key);
+            if (!statefulParameter) {
+                throw new Error(`Stateful parameter ${key} was not found`);
+            }
+            result[key] = await statefulParameter.refresh(desiredValue ?? null);
+        }
+        return result;
+    }
+    validatePlanInputs(desired, current, statefulMode) {
+        if (!desired && !current) {
+            throw new Error('Desired config and current config cannot both be missing');
+        }
+        if (!statefulMode && !desired) {
+            throw new Error('Desired config must be provided in non-stateful mode');
+        }
+    }
+    getSortedStatefulParameterChanges(parameterChanges) {
+        return parameterChanges
+            .filter((pc) => this.parsedSettings.statefulParameters.has(pc.name))
+            .sort((a, b) => this.parsedSettings.statefulParameterOrder.get(a.name) - this.parsedSettings.statefulParameterOrder.get(b.name));
+    }
+}

package/dist/resource/resource-settings.d.ts

@@ -0,0 +1,149 @@
+import { StringIndexedObject } from 'codify-schemas';
+import { StatefulParameter } from './stateful-parameter.js';
+/**
+ * The configuration and settings for a resource.
+ */
+export interface ResourceSettings<T extends StringIndexedObject> {
+    /**
+     * The typeId of the resource.
+     */
+    id: string;
+    /**
+     * Schema to validate user configs with. Must be in the format JSON Schema draft07
+     */
+    schema?: unknown;
+    /**
+     * Allow multiple of the same resource to unique. Set truthy if
+     * multiples are allowed, for example for applications, there can be multiple copy of the same application installed
+     * on the system. Or there can be multiple git repos. Defaults to false.
+     */
+    allowMultiple?: {
+        /**
+         * If multiple copies are allowed then a matcher must be defined to match the desired
+         * config with one of the resources currently existing on the system. Return null if there is no match.
+         *
+         * @param current An array of resources found installed on the system
+         * @param desired The desired config to match.
+         *
+         * @return The matched resource.
+         */
+        matcher: (desired: Partial<T>, current: Partial<T>[]) => Partial<T>;
+    };
+    /**
+     * If true, {@link StatefulParameter} remove() will be called before resource destruction. This is useful
+     * if the stateful parameter needs to be first uninstalled (cleanup) before the overall resource can be
+     * uninstalled. Defaults to false.
+     */
+    removeStatefulParametersBeforeDestroy?: boolean;
+    /**
+     * An array of type ids of resources that this resource depends on. This affects the order in which multiple resources are
+     * planned and applied.
+     */
+    dependencies?: string[];
+    /**
+     * Options for configuring parameters operations including overriding the equals function, adding default values
+     * and applying any input transformations. Use parameter settings to define stateful parameters as well.
+     */
+    parameterSettings?: Partial<Record<keyof T, ParameterSetting>>;
+    /**
+     * A config level transformation that is only applied to the user supplied desired config. This transformation is allowed
+     * to add, remove or modify keys as well as values. Changing this transformation for existing libraries will mess up existing states.
+     *
+     * @param desired
+     */
+    inputTransformation?: (desired: Partial<T>) => Promise<unknown> | unknown;
+}
+/**
+ * The type of parameter. This value is mainly used to determine a pre-set equality method for comparing the current
+ * config with desired config. Certain types will have additional options to help support it. For example the type
+ * stateful requires a stateful parameter definition and type array takes an isElementEqual method.
+ */
+export type ParameterSettingType = 'any' | 'array' | 'boolean' | 'directory' | 'number' | 'stateful' | 'string' | 'version';
+/**
+ * Typing information for the parameter setting. This represents a setting on a specific parameter within a
+ * resource. Options for configuring parameters operations including overriding the equals function, adding default values
+ * and applying any input transformations. See {@link DefaultParameterSetting } for more information.
+ * Use parameter settings to define stateful parameters as well.
+ */
+export type ParameterSetting = ArrayParameterSetting | DefaultParameterSetting | StatefulParameterSetting;
+/**
+ * The parent class for parameter settings. The options are applicable to array parameter settings
+ * as well.
+ */
+export interface DefaultParameterSetting {
+    /**
+     * The type of the value of this parameter. See {@link ParameterSettingType} for the available options. This value
+     * is mainly used to determine the equality method when performing diffing.
+     */
+    type?: ParameterSettingType;
+    /**
+     * Default value for the parameter. If a value is not provided in the config, then this value will be used.
+     */
+    default?: unknown;
+    /**
+     * A transformation of the input value for this parameter. This transformation is only applied to the desired parameter
+     * value supplied by the user.
+     *
+     * @param input The original parameter value from the desired config.
+     */
+    inputTransformation?: (input: any) => Promise<any> | unknown;
+    /**
+     * Customize the equality comparison for a parameter. This is used in the diffing algorithm for generating the plan.
+     * This value will override the pre-set equality function from the type. Return true if the desired value is
+     * equivalent to the current value.
+     *
+     * @param desired The desired value.
+     * @param current The current value.
+     *
+     * @return Return true if equal
+     */
+    isEqual?: (desired: any, current: any) => boolean;
+    /**
+     * Chose if the resource can be modified instead of re-created when there is a change to this parameter.
+     * Defaults to false (re-create).
+     *
+     * Examples:
+     * 1. Settings like git user name and git user email that have setter calls and don't require the re-installation of git
+     * 2. AWS profile secret keys that can be updated without the re-installation of AWS CLI
+     */
+    canModify?: boolean;
+}
+/**
+ * Array type specific settings. See {@link DefaultParameterSetting } for a full list of options.
+ */
+export interface ArrayParameterSetting extends DefaultParameterSetting {
+    type: 'array';
+    /**
+     * An element level equality function for arrays. The diffing algorithm will take isElementEqual and use it in a
+     * O(n^2) equality comparison to determine if the overall array is equal. This value will override the pre-set equality
+     * function for arrays (desired === current). Return true if the desired element is equivalent to the current element.
+     *
+     * @param desired An element of the desired array
+     * @param current An element of the current array
+     *
+     * @return Return true if desired is equivalent to current.
+     */
+    isElementEqual?: (desired: any, current: any) => boolean;
+}
+/**
+ * Stateful parameter type specific settings. A stateful parameter is a sub-resource that can hold its own
+ * state but is still tied to the overall state of the resource. For example 'homebrew' is represented
+ * as a resource and taps, formulas and casks are represented as a stateful parameter. A formula can be installed,
+ * modified and removed (has state) but it is still tied to the overall lifecycle of homebrew.
+ *
+ */
+export interface StatefulParameterSetting extends DefaultParameterSetting {
+    type: 'stateful';
+    /**
+     * The stateful parameter definition. A stateful parameter is a sub-resource that can hold its own
+     * state but is still tied to the overall state of the resource. For example 'homebrew' is represented
+     * as a resource and taps, formulas and casks are represented as a stateful parameter. A formula can be installed,
+     * modified and removed (has state) but it is still tied to the overall lifecycle of homebrew.
+     */
+    definition: StatefulParameter<any, unknown>;
+    /**
+     * The order multiple stateful parameters should be applied in. The order is applied in ascending order (1, 2, 3...).
+     */
+    order?: number;
+}
+export declare const ParameterEqualsDefaults: Partial<Record<ParameterSettingType, (a: unknown, b: unknown) => boolean>>;

package/dist/resource/resource-settings.js

@@ -0,0 +1,9 @@
+import path from 'node:path';
+import { untildify } from '../utils/utils.js';
+export const ParameterEqualsDefaults = {
+    'boolean': (a, b) => Boolean(a) === Boolean(b),
+    'directory': (a, b) => path.resolve(untildify(String(a))) === path.resolve(untildify(String(b))),
+    'number': (a, b) => Number(a) === Number(b),
+    'string': (a, b) => String(a) === String(b),
+    'version': (desired, current) => String(current).includes(String(desired))
+};

package/dist/resource/resource.d.ts

@@ -0,0 +1,137 @@
+import { StringIndexedObject } from 'codify-schemas';
+import { ParameterChange } from '../plan/change-set.js';
+import { CreatePlan, DestroyPlan, ModifyPlan } from '../plan/plan-types.js';
+import { ResourceSettings } from './resource-settings.js';
+/**
+ * A resource represents an object on the system (application, CLI tool, or setting)
+ * that has state and can be created and destroyed. Examples of resources include CLI tools
+ * like homebrew, docker, and xcode-tools; applications like Google Chrome, Zoom, and OpenVPN;
+ * and settings like AWS profiles, git configs and system preference settings.
+ */
+export declare abstract class Resource<T extends StringIndexedObject> {
+    /**
+     * Return the settings for the resource. Consult the typing for {@link ResourceSettings} for
+     * a description of the options.
+     *
+     * **Parameters**:
+     * - id: The id of the resource. This translates to the `type` id parameter in codify.json configs
+     * - schema: A JSON schema used to validate user input
+     * - allowMultiple: Allow multiple copies of the resource to exist at the same time. If true then,
+     * a matcher must be defined that matches a user defined config and a single resource on the system.
+     * - removeStatefulParametersBeforeDestory: Call the delete methods of stateful parameters before destorying
+     * the base resource. Defaults to false.
+     * - dependencies: Specify the ids of any resources that this resource depends on
+     * - parameterSettings: Parameter specific settings. Use this to define custom equals functions, default values
+     * and input transformations
+     * - inputTransformation: Transform the input value.
+     *
+     * @return ResourceSettings The resource settings
+     */
+    abstract getSettings(): ResourceSettings<T>;
+    initialize(): Promise<void>;
+    /**
+     * Add custom validation logic in-addition to the default schema validation.
+     * In this method throw an error if the object did not validate. The message of the
+     * error will be shown to the user.
+     * @param parameters
+     */
+    validate(parameters: Partial<T>): Promise<void>;
+    /**
+     * Return the status of the resource on the system. If multiple resources exist, then return all instances of
+     * the resource back. Query for the individual parameters specified in the parameter param.
+     * Return null if the resource does not exist.
+     *
+     * Example (Android Studios Resource):
+     * 1. Receive Input:
+     * ```
+     * {
+     *   name: 'Android Studios.app'
+     *   directory: '/Application',
+     *   version: '2023.2'
+     * }
+     * ```
+     * 2. Query the system for any installed Android studio versions.
+     * 3. In this example we find that there is an 2023.2 version installed and an
+     * additional 2024.3-beta version installed as well.
+     * 4. We would return:
+     * ```
+     * [
+     *   { name: 'Android Studios.app', directory: '/Application', version: '2023.2' },
+     *   { name: 'Android Studios Preview.app', directory: '/Application', version: '2024.3' },
+     * ]
+     * ```
+     *
+     * @param parameters The parameters to refresh. In stateless mode this will be the parameters
+     * of the desired config. In stateful mode, this will be parameters of the state config + the desired
+     * config of any new parameters.
+     *
+     * @return A config or an array of configs representing the status of the resource on the
+     * system currently
+     */
+    abstract refresh(parameters: Partial<T>): Promise<Array<Partial<T>> | Partial<T> | null>;
+    /**
+     * Create the resource (install) based on the parameters passed in. Only the desired parameters will
+     * be non-null because in a CREATE plan, the current value is null.
+     *
+     * Example (Android Studios Resource):
+     * 1. We receive a plan of:
+     * ```
+     * Plan {
+     *   desiredConfig: {
+     *     name: 'Android Studios.app',
+     *     directory: '/Application',
+     *     version: '2023.2'
+     *   }
+     *   currentConfig: null,
+     * }
+     * ```
+     * 2. Install version Android Studios 2023.2 and then return.
+     *
+     * @param plan The plan of what to install. Use only the desiredConfig because currentConfig is null.
+     */
+    abstract create(plan: CreatePlan<T>): Promise<void>;
+    /**
+     * Modify a single parameter of a resource. Modify is optional to override and is only called
+     * when a resourceSetting was set to `canModify = true`. This method should only modify
+     * a single parameter at a time as specified by the first parameter: ParameterChange.
+     *
+     * Example (AWS Profile Resource):
+     * 1. We receive a parameter change of:
+     * ```
+     * {
+     *   name: 'awsAccessKeyId',
+     *   operation: ParameterOperation.MODIFY,
+     *   newValue: '123456',
+     *   previousValue: 'abcdef'
+     * }
+     * ```
+     * 2. Use an if statement to only apply this operation for the parameter `awsAccessKeyId`
+     * 3. Update the value of the `aws_access_key_id` to the `newValue` specified in the parameter change
+     *
+     * @param pc ParameterChange, the parameter name and values to modify on the resource
+     * @param plan The overall plan that triggered the modify operation
+     */
+    modify(pc: ParameterChange<T>, plan: ModifyPlan<T>): Promise<void>;
+    /**
+     * Destroy the resource (uninstall) based on the parameters passed in. Only the current parameters will
+     * be non-null because in a DESTROY plan, the desired value is null. This method will only be called in
+     * stateful mode.
+     *
+     * Example (Android Studios Resource):
+     * 1. We receive a plan of:
+     * ```
+     * Plan {
+     *   currentConfig: {
+     *     name: 'Android Studios.app',
+     *     directory: '/Application',
+     *     version: '2022.4'
+     *   },
+     *   desiredConfig: null
+     * }
+     * ```
+     * 2. Uninstall version Android Studios 2022.4 and then return.
+     *
+     * @param plan The plan of what to uninstall. Use only the currentConfig because desiredConfig is null.
+     */
+    abstract destroy(plan: DestroyPlan<T>): Promise<void>;
+}

package/dist/resource/resource.js

@@ -0,0 +1,44 @@
+/**
+ * A resource represents an object on the system (application, CLI tool, or setting)
+ * that has state and can be created and destroyed. Examples of resources include CLI tools
+ * like homebrew, docker, and xcode-tools; applications like Google Chrome, Zoom, and OpenVPN;
+ * and settings like AWS profiles, git configs and system preference settings.
+ */
+export class Resource {
+    async initialize() {
+    }
+    ;
+    /**
+     * Add custom validation logic in-addition to the default schema validation.
+     * In this method throw an error if the object did not validate. The message of the
+     * error will be shown to the user.
+     * @param parameters
+     */
+    async validate(parameters) {
+    }
+    ;
+    /**
+     * Modify a single parameter of a resource. Modify is optional to override and is only called
+     * when a resourceSetting was set to `canModify = true`. This method should only modify
+     * a single parameter at a time as specified by the first parameter: ParameterChange.
+     *
+     * Example (AWS Profile Resource):
+     * 1. We receive a parameter change of:
+     * ```
+     * {
+     *   name: 'awsAccessKeyId',
+     *   operation: ParameterOperation.MODIFY,
+     *   newValue: '123456',
+     *   previousValue: 'abcdef'
+     * }
+     * ```
+     * 2. Use an if statement to only apply this operation for the parameter `awsAccessKeyId`
+     * 3. Update the value of the `aws_access_key_id` to the `newValue` specified in the parameter change
+     *
+     * @param pc ParameterChange, the parameter name and values to modify on the resource
+     * @param plan The overall plan that triggered the modify operation
+     */
+    async modify(pc, plan) {
+    }
+    ;
+}