codify-plugin-lib 1.0.75 → 1.0.77

package/.eslintrc.json

@@ -9,13 +9,20 @@
       "warn",
       "always"
     ],
-    "perfectionist/sort-classes": [
-      "off"
-    ],
+    "perfectionist/sort-classes": "off",
+    "perfectionist/sort-interfaces": "off",
+    "perfectionist/sort-enums": "off",
+    "perfectionist/sort-objects": "off",
+    "perfectionist/sort-object-types": "off",
+    "unicorn/no-array-reduce": "off",
+    "unicorn/no-array-for-each": "off",
+    "unicorn/prefer-object-from-entries": "off",
+    "unicorn/prefer-type-error": "off",
     "quotes": [
       "error",
       "single"
-    ]
+    ],
+    "no-await-in-loop": "off"
   },
   "ignorePatterns": [
     "*.test.ts"

package/.github/workflows/release.yaml

@@ -0,0 +1,19 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Release
+
+on: workflow_dispatch
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+      - run: npm ci
+      - run: tsc
+      - run: npm publish

package/.github/workflows/unit-test-ci.yaml

@@ -0,0 +1,19 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Unit tests
+
+on: [ push ]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+      - run: npm ci
+      - run: tsc
+      - run: npm run test

package/dist/entities/plugin.d.ts

@@ -1,6 +1,6 @@
-import { Resource } from './resource.js';
 import { ApplyRequestData, InitializeResponseData, PlanRequestData, PlanResponseData, ResourceConfig, ValidateRequestData, ValidateResponseData } from 'codify-schemas';
 import { Plan } from './plan.js';
+import { Resource } from './resource.js';
 export declare class Plugin {
     name: string;
     resources: Map<string, Resource<ResourceConfig>>;

package/dist/entities/plugin.js

@@ -1,5 +1,5 @@
-import { Plan } from './plan.js';
 import { splitUserConfig } from '../utils/utils.js';
+import { Plan } from './plan.js';
 export class Plugin {
     name;
     resources;
@@ -20,8 +20,8 @@ export class Plugin {
         return {
             resourceDefinitions: [...this.resources.values()]
                 .map((r) => ({
-                type: r.typeId,
                 dependencies: r.dependencies,
+                type: r.typeId,
             }))
         };
     }
@@ -53,7 +53,7 @@ export class Plugin {
     }
     async apply(data) {
         if (!data.planId && !data.plan) {
-            throw new Error(`For applies either plan or planId must be supplied`);
+            throw new Error('For applies either plan or planId must be supplied');
         }
         const plan = this.resolvePlan(data);
         const resource = this.resources.get(plan.getResourceType());
@@ -63,7 +63,7 @@ export class Plugin {
         await resource.apply(plan);
     }
     resolvePlan(data) {
-        const { planId, plan: planRequest } = data;
+        const { plan: planRequest, planId } = data;
         if (planId) {
             if (!this.planStorage.has(planId)) {
                 throw new Error(`Plan with id: ${planId} was not found`);
@@ -74,7 +74,7 @@ export class Plugin {
             throw new Error('Malformed plan. Resource type must be supplied or resource type was not found');
         }
         const resource = this.resources.get(planRequest.resourceType);
-        return Plan.fromResponse(data.plan, resource.defaultValues);
+        return Plan.fromResponse(planRequest, resource.defaultValues);
     }
     async crossValidateResources(configs) { }
 }

package/dist/entities/resource-options.d.ts

@@ -1,22 +1,22 @@
 import { StringIndexedObject } from 'codify-schemas';
+import { ParameterOptions } from './plan-types.js';
+import { ResourceParameterOptions } from './resource-types.js';
 import { StatefulParameter } from './stateful-parameter.js';
 import { TransformParameter } from './transform-parameter.js';
-import { ResourceParameterOptions } from './resource-types.js';
-import { ParameterOptions } from './plan-types.js';
 export interface ResourceOptions<T extends StringIndexedObject> {
-    type: string;
-    schema?: unknown;
     callStatefulParameterRemoveOnDestroy?: boolean;
     dependencies?: string[];
     parameterOptions?: Partial<Record<keyof T, ResourceParameterOptions | ResourceStatefulParameterOptions<T> | ResourceTransformParameterOptions<T>>>;
+    schema?: unknown;
+    type: string;
 }
 export interface ResourceStatefulParameterOptions<T extends StringIndexedObject> {
-    statefulParameter: StatefulParameter<T, T[keyof T]>;
     order?: number;
+    statefulParameter: StatefulParameter<T, T[keyof T]>;
 }
 export interface ResourceTransformParameterOptions<T extends StringIndexedObject> {
-    transformParameter: TransformParameter<T>;
     order?: number;
+    transformParameter: TransformParameter<T>;
 }
 export declare class ResourceOptionsParser<T extends StringIndexedObject> {
     private options;

package/dist/entities/resource-options.js

@@ -27,15 +27,13 @@ export class ResourceOptionsParser {
         const resourceParameters = Object.fromEntries([...this.resourceParameters.entries()]
             .map(([name, value]) => ([name, { ...value, isStatefulParameter: false }])));
         const statefulParameters = [...this.statefulParameters.entries()]
-            ?.reduce((obj, sp) => {
-            return {
-                ...obj,
-                [sp[0]]: {
-                    ...sp[1].options,
-                    isStatefulParameter: true,
-                }
-            };
-        }, {});
+            ?.reduce((obj, sp) => ({
+            ...obj,
+            [sp[0]]: {
+                ...sp[1].options,
+                isStatefulParameter: true,
+            }
+        }), {});
         return {
             ...resourceParameters,
             ...statefulParameters,

package/dist/entities/resource.d.ts

@@ -1,5 +1,4 @@
-import Ajv from 'ajv';
-import { ValidateFunction } from 'ajv/dist/2020.js';
+import { Ajv, ValidateFunction } from 'ajv';
 import { ResourceConfig, StringIndexedObject, ValidateResponseData } from 'codify-schemas';
 import { ParameterChange } from './change-set.js';
 import { Plan } from './plan.js';
@@ -19,7 +18,7 @@ export declare abstract class Resource<T extends StringIndexedObject> {
     readonly parameterOptions: Record<keyof T, ParameterOptions>;
     readonly options: ResourceOptions<T>;
     readonly defaultValues: Partial<Record<keyof T, unknown>>;
-    protected ajv?: Ajv.default;
+    protected ajv?: Ajv;
     protected schemaValidator?: ValidateFunction;
     protected constructor(options: ResourceOptions<T>);
     onInitialize(): Promise<void>;

package/dist/entities/resource.js

@@ -1,4 +1,4 @@
-import Ajv2020 from 'ajv/dist/2020.js';
+import { Ajv } from 'ajv';
 import { ParameterOperation, ResourceOperation, } from 'codify-schemas';
 import { setsEqual, splitUserConfig } from '../utils/utils.js';
 import { Plan } from './plan.js';
@@ -21,7 +21,7 @@ export class Resource {
         this.dependencies = options.dependencies ?? [];
         this.options = options;
         if (this.options.schema) {
-            this.ajv = new Ajv2020.default({
+            this.ajv = new Ajv({
                 allErrors: true,
                 strict: true,
                 strictRequired: false,

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class SudoError extends Error {
+    command: string;
+    constructor(command: string);
+}

package/dist/errors.js

@@ -0,0 +1,7 @@
+export class SudoError extends Error {
+    command;
+    constructor(command) {
+        super();
+        this.command = command;
+    }
+}

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { Plugin } from './entities/plugin.js';
-export * from './entities/resource.js';
-export * from './entities/resource-types.js';
-export * from './entities/resource-options.js';
-export * from './entities/plugin.js';
-export * from './entities/change-set.js';
-export * from './entities/plan.js';
-export * from './entities/plan-types.js';
-export * from './entities/stateful-parameter.js';
-export * from './entities/errors.js';
+import { Plugin } from './plugin/plugin.js';
+export * from './errors.js';
+export * from './plan/change-set.js';
+export * from './plan/plan.js';
+export * from './plan/plan-types.js';
+export * from './plugin/plugin.js';
+export * from './resource/parsed-resource-settings.js';
+export * from './resource/resource.js';
+export * from './resource/resource-settings.js';
+export * from './resource/stateful-parameter.js';
 export * from './utils/utils.js';
 export declare function runPlugin(plugin: Plugin): Promise<void>;

package/dist/index.js

@@ -1,13 +1,13 @@
 import { MessageHandler } from './messages/handlers.js';
-export * from './entities/resource.js';
-export * from './entities/resource-types.js';
-export * from './entities/resource-options.js';
-export * from './entities/plugin.js';
-export * from './entities/change-set.js';
-export * from './entities/plan.js';
-export * from './entities/plan-types.js';
-export * from './entities/stateful-parameter.js';
-export * from './entities/errors.js';
+export * from './errors.js';
+export * from './plan/change-set.js';
+export * from './plan/plan.js';
+export * from './plan/plan-types.js';
+export * from './plugin/plugin.js';
+export * from './resource/parsed-resource-settings.js';
+export * from './resource/resource.js';
+export * from './resource/resource-settings.js';
+export * from './resource/stateful-parameter.js';
 export * from './utils/utils.js';
 export async function runPlugin(plugin) {
     const messageHandler = new MessageHandler(plugin);

package/dist/messages/handlers.d.ts

@@ -1,4 +1,4 @@
-import { Plugin } from '../entities/plugin.js';
+import { Plugin } from '../plugin/plugin.js';
 export declare class MessageHandler {
     private ajv;
     private readonly plugin;

package/dist/messages/handlers.js

@@ -1,30 +1,30 @@
+import { Ajv } from 'ajv';
 import addFormats from 'ajv-formats';
 import { ApplyRequestDataSchema, ApplyResponseDataSchema, InitializeRequestDataSchema, InitializeResponseDataSchema, IpcMessageSchema, MessageStatus, PlanRequestDataSchema, PlanResponseDataSchema, ResourceSchema, ValidateRequestDataSchema, ValidateResponseDataSchema } from 'codify-schemas';
-import Ajv2020 from 'ajv/dist/2020.js';
-import { SudoError } from '../entities/errors.js';
+import { SudoError } from '../errors.js';
 const SupportedRequests = {
+    'apply': {
+        async handler(plugin, data) {
+            await plugin.apply(data);
+            return null;
+        },
+        requestValidator: ApplyRequestDataSchema,
+        responseValidator: ApplyResponseDataSchema
+    },
     'initialize': {
+        handler: async (plugin) => plugin.initialize(),
         requestValidator: InitializeRequestDataSchema,
-        responseValidator: InitializeResponseDataSchema,
-        handler: async (plugin) => plugin.initialize()
-    },
-    'validate': {
-        requestValidator: ValidateRequestDataSchema,
-        responseValidator: ValidateResponseDataSchema,
-        handler: async (plugin, data) => plugin.validate(data)
+        responseValidator: InitializeResponseDataSchema
     },
     'plan': {
+        handler: async (plugin, data) => plugin.plan(data),
         requestValidator: PlanRequestDataSchema,
-        responseValidator: PlanResponseDataSchema,
-        handler: async (plugin, data) => plugin.plan(data)
+        responseValidator: PlanResponseDataSchema
     },
-    'apply': {
-        requestValidator: ApplyRequestDataSchema,
-        responseValidator: ApplyResponseDataSchema,
-        handler: async (plugin, data) => {
-            await plugin.apply(data);
-            return null;
-        }
+    'validate': {
+        handler: async (plugin, data) => plugin.validate(data),
+        requestValidator: ValidateRequestDataSchema,
+        responseValidator: ValidateResponseDataSchema
     }
 };
 export class MessageHandler {
@@ -34,7 +34,7 @@ export class MessageHandler {
     requestValidators;
     responseValidators;
     constructor(plugin) {
-        this.ajv = new Ajv2020.default({ strict: true, strictRequired: false });
+        this.ajv = new Ajv({ strict: true, strictRequired: false });
         addFormats.default(this.ajv);
         this.ajv.addSchema(ResourceSchema);
         this.plugin = plugin;
@@ -63,12 +63,12 @@ export class MessageHandler {
             }
             process.send({
                 cmd: message.cmd + '_Response',
-                status: MessageStatus.SUCCESS,
                 data: result,
+                status: MessageStatus.SUCCESS,
             });
         }
-        catch (e) {
-            this.handleErrors(message, e);
+        catch (error) {
+            this.handleErrors(message, error);
         }
     }
     validateMessage(message) {
@@ -81,19 +81,20 @@ export class MessageHandler {
         if (!message.hasOwnProperty('cmd')) {
             return;
         }
+        // @ts-ignore
         const cmd = message.cmd + '_Response';
         if (e instanceof SudoError) {
             return process.send?.({
                 cmd,
-                status: MessageStatus.ERROR,
                 data: `Plugin: '${this.plugin.name}'. Forbidden usage of sudo for command '${e.command}'. Please contact the plugin developer to fix this.`,
+                status: MessageStatus.ERROR,
             });
         }
         const isDebug = process.env.DEBUG?.includes('*') ?? false;
         process.send?.({
             cmd,
-            status: MessageStatus.ERROR,
             data: isDebug ? e.stack : e.message,
+            status: MessageStatus.ERROR,
         });
     }
 }

package/dist/plan/change-set.d.ts

@@ -0,0 +1,37 @@
+import { ParameterOperation, ResourceOperation, StringIndexedObject } from 'codify-schemas';
+import { ParameterSetting } from '../resource/resource-settings.js';
+/**
+ * A parameter change describes a parameter level change to a resource.
+ */
+export interface ParameterChange<T extends StringIndexedObject> {
+    /**
+     * The name of the parameter
+     */
+    name: keyof T & string;
+    /**
+     * The operation to be performed on the parameter.
+     */
+    operation: ParameterOperation;
+    /**
+     * The previous value of the resource (the current value on the system)
+     */
+    previousValue: any | null;
+    /**
+     * The new value of the resource (the desired value)
+     */
+    newValue: any | null;
+}
+export declare class ChangeSet<T extends StringIndexedObject> {
+    operation: ResourceOperation;
+    parameterChanges: Array<ParameterChange<T>>;
+    constructor(operation: ResourceOperation, parameterChanges: Array<ParameterChange<T>>);
+    get desiredParameters(): T;
+    get currentParameters(): T;
+    static empty<T extends StringIndexedObject>(): ChangeSet<T>;
+    static create<T extends StringIndexedObject>(desired: Partial<T>): ChangeSet<T>;
+    static destroy<T extends StringIndexedObject>(current: Partial<T>): ChangeSet<T>;
+    static calculateModification<T extends StringIndexedObject>(desired: Partial<T>, current: Partial<T>, parameterSettings?: Partial<Record<keyof T, ParameterSetting>>): ChangeSet<T>;
+    private static calculateParameterChanges;
+    private static combineResourceOperations;
+    private static isSame;
+}

package/dist/plan/change-set.js

@@ -0,0 +1,146 @@
+import { ParameterOperation, ResourceOperation } from 'codify-schemas';
+import { areArraysEqual } from '../utils/utils.js';
+// Change set will coerce undefined values to null because undefined is not valid JSON
+export class ChangeSet {
+    operation;
+    parameterChanges;
+    constructor(operation, parameterChanges) {
+        this.operation = operation;
+        this.parameterChanges = parameterChanges;
+    }
+    get desiredParameters() {
+        return this.parameterChanges
+            .reduce((obj, pc) => ({
+            ...obj,
+            [pc.name]: pc.newValue,
+        }), {});
+    }
+    get currentParameters() {
+        return this.parameterChanges
+            .reduce((obj, pc) => ({
+            ...obj,
+            [pc.name]: pc.previousValue,
+        }), {});
+    }
+    static empty() {
+        return new ChangeSet(ResourceOperation.NOOP, []);
+    }
+    static create(desired) {
+        const parameterChanges = Object.entries(desired)
+            .map(([k, v]) => ({
+            name: k,
+            operation: ParameterOperation.ADD,
+            previousValue: null,
+            newValue: v ?? null,
+        }));
+        return new ChangeSet(ResourceOperation.CREATE, parameterChanges);
+    }
+    static destroy(current) {
+        const parameterChanges = Object.entries(current)
+            .map(([k, v]) => ({
+            name: k,
+            operation: ParameterOperation.REMOVE,
+            previousValue: v ?? null,
+            newValue: null,
+        }));
+        return new ChangeSet(ResourceOperation.DESTROY, parameterChanges);
+    }
+    static calculateModification(desired, current, parameterSettings = {}) {
+        const pc = ChangeSet.calculateParameterChanges(desired, current, parameterSettings);
+        const statefulParameterKeys = new Set(Object.entries(parameterSettings)
+            .filter(([, v]) => v?.type === 'stateful')
+            .map(([k]) => k));
+        const resourceOperation = pc
+            .filter((change) => change.operation !== ParameterOperation.NOOP)
+            .reduce((operation, curr) => {
+            let newOperation;
+            if (statefulParameterKeys.has(curr.name)) {
+                newOperation = ResourceOperation.MODIFY; // All stateful parameters are modify only
+            }
+            else if (parameterSettings[curr.name]?.canModify) {
+                newOperation = ResourceOperation.MODIFY;
+            }
+            else {
+                newOperation = ResourceOperation.RECREATE; // Default to Re-create. Should handle the majority of use cases
+            }
+            return ChangeSet.combineResourceOperations(operation, newOperation);
+        }, ResourceOperation.NOOP);
+        return new ChangeSet(resourceOperation, pc);
+    }
+    static calculateParameterChanges(desiredParameters, currentParameters, parameterOptions) {
+        const parameterChangeSet = new Array();
+        // Filter out null and undefined values or else the diff below will not work
+        const desired = Object.fromEntries(Object.entries(desiredParameters).filter(([, v]) => v !== null && v !== undefined));
+        const current = Object.fromEntries(Object.entries(currentParameters).filter(([, v]) => v !== null && v !== undefined));
+        for (const [k, v] of Object.entries(current)) {
+            if (desired?.[k] === null || desired?.[k] === undefined) {
+                parameterChangeSet.push({
+                    name: k,
+                    previousValue: v ?? null,
+                    newValue: null,
+                    operation: ParameterOperation.REMOVE,
+                });
+                delete current[k];
+                continue;
+            }
+            if (!ChangeSet.isSame(desired[k], current[k], parameterOptions?.[k])) {
+                parameterChangeSet.push({
+                    name: k,
+                    previousValue: v ?? null,
+                    newValue: desired[k] ?? null,
+                    operation: ParameterOperation.MODIFY,
+                });
+                delete current[k];
+                delete desired[k];
+                continue;
+            }
+            parameterChangeSet.push({
+                name: k,
+                previousValue: v ?? null,
+                newValue: desired[k] ?? null,
+                operation: ParameterOperation.NOOP,
+            });
+            delete current[k];
+            delete desired[k];
+        }
+        if (Object.keys(current).length > 0) {
+            throw new Error('Diff algorithm error');
+        }
+        for (const [k, v] of Object.entries(desired)) {
+            parameterChangeSet.push({
+                name: k,
+                previousValue: null,
+                newValue: v ?? null,
+                operation: ParameterOperation.ADD,
+            });
+        }
+        return parameterChangeSet;
+    }
+    static combineResourceOperations(prev, next) {
+        const orderOfOperations = [
+            ResourceOperation.NOOP,
+            ResourceOperation.MODIFY,
+            ResourceOperation.RECREATE,
+            ResourceOperation.CREATE,
+            ResourceOperation.DESTROY,
+        ];
+        const indexPrev = orderOfOperations.indexOf(prev);
+        const indexNext = orderOfOperations.indexOf(next);
+        return orderOfOperations[Math.max(indexPrev, indexNext)];
+    }
+    static isSame(desired, current, setting) {
+        switch (setting?.type) {
+            case 'stateful': {
+                const statefulSetting = setting.definition.getSettings();
+                return ChangeSet.isSame(desired, current, statefulSetting);
+            }
+            case 'array': {
+                const arrayParameter = setting;
+                return areArraysEqual(arrayParameter, desired, current);
+            }
+            default: {
+                return (setting?.isEqual ?? ((a, b) => a === b))(desired, current);
+            }
+        }
+    }
+}

package/dist/plan/plan-types.d.ts

@@ -0,0 +1,23 @@
+import { StringIndexedObject } from 'codify-schemas';
+import { Plan } from './plan.js';
+/**
+ * A narrower type for plans for CREATE operations. Only desiredConfig is not null.
+ */
+export interface CreatePlan<T extends StringIndexedObject> extends Plan<T> {
+    desiredConfig: T;
+    currentConfig: null;
+}
+/**
+ * A narrower type for plans for DESTROY operations. Only currentConfig is not null.
+ */
+export interface DestroyPlan<T extends StringIndexedObject> extends Plan<T> {
+    desiredConfig: null;
+    currentConfig: T;
+}
+/**
+ * A narrower type for plans for MODIFY and RE-CREATE operations.
+ */
+export interface ModifyPlan<T extends StringIndexedObject> extends Plan<T> {
+    desiredConfig: T;
+    currentConfig: T;
+}

package/dist/plan/plan-types.js

@@ -0,0 +1 @@
+export {};

package/dist/plan/plan.d.ts

@@ -0,0 +1,59 @@
+import { ApplyRequestData, PlanResponseData, ResourceConfig, StringIndexedObject } from 'codify-schemas';
+import { ParsedResourceSettings } from '../resource/parsed-resource-settings.js';
+import { ChangeSet } from './change-set.js';
+/**
+ * A plan represents a set of actions that after taken will turn the current resource into the desired one.
+ * A plan consists of list of parameter level changes (ADD, REMOVE, MODIFY or NO-OP) as well as a resource level
+ * operation (CREATE, DESTROY, MODIFY, RE-CREATE, NO-OP).
+ */
+export declare class Plan<T extends StringIndexedObject> {
+    id: string;
+    changeSet: ChangeSet<T>;
+    coreParameters: ResourceConfig;
+    constructor(id: string, changeSet: ChangeSet<T>, resourceMetadata: ResourceConfig);
+    /**
+     * The desired config that a plan will achieve after executing all the actions.
+     */
+    get desiredConfig(): T | null;
+    /**
+     * The current config that the plan is changing.
+     */
+    get currentConfig(): T | null;
+    /**
+     * When multiples of the same resource are allowed, this matching function will match a given config with one of the
+     * existing configs on the system. For example if there are multiple versions of Android Studios installed, we can use
+     * the application name and location to match it to our desired configs name and location.
+     *
+     * @param params
+     * @private
+     */
+    private static matchCurrentParameters;
+    /**
+     * The type (id) of the resource
+     *
+     * @return string
+     */
+    getResourceType(): string;
+    static calculate<T extends StringIndexedObject>(params: {
+        desiredParameters: Partial<T> | null;
+        currentParametersArray: Partial<T>[] | null;
+        stateParameters: Partial<T> | null;
+        coreParameters: ResourceConfig;
+        settings: ParsedResourceSettings<T>;
+        statefulMode: boolean;
+    }): Plan<T>;
+    /**
+     *  Only keep relevant params for the plan. We don't want to change settings that were not already
+     *  defined.
+     *
+     *  1. In stateless mode, filter current by desired. We only want to know about settings that the user has specified
+     *  2. In stateful mode, filter current by state and desired. We only know about the settings the user has previously set
+     *  or wants to set. If a parameter is not specified then it's not managed by Codify.
+     */
+    private static filterCurrentParams;
+    static fromResponse<T extends ResourceConfig>(data: ApplyRequestData['plan'], defaultValues?: Partial<Record<keyof T, unknown>>): Plan<T>;
+    /**
+     * Convert the plan to a JSON response object
+     */
+    toResponse(): PlanResponseData;
+}