@codifycli/plugin-core 1.0.0-beta1

package/src/stateful-parameter/stateful-parameter-controller.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, it } from 'vitest';
+import { spy } from 'sinon';
+import { ParameterOperation, ResourceOperation } from 'codify-schemas';
+import {
+  TestArrayStatefulParameter,
+  TestConfig,
+  testPlan,
+  TestResource,
+  TestStatefulParameter
+} from '../utils/test-utils.test.js';
+import { ArrayParameterSetting, ParameterSetting, ResourceSettings } from '../resource/resource-settings.js';
+import { ResourceController } from '../resource/resource-controller.js';
+import { StatefulParameterController } from './stateful-parameter-controller.js';
+
+describe('Stateful parameter tests', () => {
+  it('addItem is called the correct number of times', async () => {
+    const plan = testPlan<TestConfig>({
+      desired: { propZ: ['a', 'b', 'c'] },
+    });
+
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.CREATE);
+    expect(plan.changeSet.parameterChanges.length).to.eq(1);
+
+    const parameter = spy(new TestArrayStatefulParameter());
+    const controller = new StatefulParameterController(parameter);
+    await controller.add((plan.desiredConfig! as any).propZ, plan);
+
+    expect(parameter.addItem.callCount).to.eq(3);
+    expect(parameter.removeItem.called).to.be.false;
+  })
+
+  it('applyRemoveItem is called the correct number of times', async () => {
+    const plan = testPlan<TestConfig>({
+      desired: null,
+      current: [{ propZ: ['a', 'b', 'c'] }],
+      state: { propZ: ['a', 'b', 'c'] },
+      isStateful: true,
+    });
+
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.DESTROY);
+    expect(plan.changeSet.parameterChanges.length).to.eq(1);
+
+    const parameter = spy(new TestArrayStatefulParameter());
+    const controller = new StatefulParameterController(parameter);
+    await controller.remove((plan.currentConfig as any).propZ, plan);
+
+    expect(parameter.addItem.called).to.be.false;
+    expect(parameter.removeItem.callCount).to.eq(3);
+  })
+
+  it('In stateless mode only applyAddItem is called only for modifies', async () => {
+    const parameter = new TestArrayStatefulParameter()
+    const plan = testPlan<TestConfig>({
+      desired: { propZ: ['a', 'c', 'd', 'e', 'f'] }, // b to remove, d, e, f to add
+      current: [{ propZ: ['a', 'b', 'c'] }],
+      settings: { id: 'type', parameterSettings: { propZ: { type: 'stateful', definition: parameter } } },
+    });
+
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.MODIFY);
+    expect(plan.changeSet.parameterChanges[0]).toMatchObject({
+      name: 'propZ',
+      previousValue: ['c', 'a'], // In stateless mode the previous value gets filtered to prevent deletes
+      newValue: ['a', 'c', 'd', 'e', 'f'],
+      operation: ParameterOperation.MODIFY,
+    })
+
+
+    const testParameter = spy(parameter);
+    const controller = new StatefulParameterController(testParameter);
+    await controller.modify((plan.desiredConfig as any).propZ, (plan.currentConfig as any).propZ, plan);
+
+    expect(testParameter.addItem.calledThrice).to.be.true;
+    expect(testParameter.removeItem.called).to.be.false;
+  })
+
+  it('isElementEqual is called for modifies', async () => {
+    const testParameter = spy(new class extends TestArrayStatefulParameter {
+      getSettings(): ArrayParameterSetting {
+        return {
+          type: 'array',
+          isElementEqual: (desired, current) => current.includes(desired),
+        }
+      }
+    });
+
+    const plan = testPlan<TestConfig>({
+      desired: { propZ: ['9.12', '9.13'] }, // b to remove, d, e, f to add
+      current: [{ propZ: ['9.12.9'] }],
+      settings: { id: 'type', parameterSettings: { propZ: { type: 'stateful', definition: testParameter } } }
+    });
+
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.MODIFY);
+    expect(plan.changeSet.parameterChanges[0]).toMatchObject({
+      name: 'propZ',
+      previousValue: ['9.12.9'],
+      newValue: ['9.12', '9.13'],
+      operation: ParameterOperation.MODIFY,
+    })
+
+    const controller = new StatefulParameterController(testParameter);
+    await controller.modify((plan.desiredConfig as any).propZ, (plan.currentConfig as any).propZ, plan);
+
+    expect(testParameter.addItem.calledOnce).to.be.true;
+    expect(testParameter.removeItem.called).to.be.false;
+  })
+
+  it('isEqual works with type defaults', () => {
+    const testParameter = spy(new class extends TestStatefulParameter {
+      getSettings(): ParameterSetting {
+        return {
+          type: 'version',
+        }
+      }
+    });
+
+    const plan = testPlan<TestConfig>({
+      desired: { propZ: '20' },
+      current: [{ propZ: '20.17.0' }],
+      settings: { id: 'type', parameterSettings: { propZ: { type: 'stateful', definition: testParameter } } }
+    });
+
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.NOOP);
+  })
+
+  it('isElementEquals test', async () => {
+    const testParameter = spy(new class extends TestArrayStatefulParameter {
+      getSettings(): ArrayParameterSetting {
+        return {
+          type: 'array',
+          isElementEqual: (desired, current) => current.includes(desired),
+        }
+      }
+
+      async refresh(): Promise<any> {
+        return [
+          '20.15.0',
+          '20.15.1'
+        ]
+      }
+    });
+
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<any> {
+        return {
+          id: 'type',
+          parameterSettings: { nodeVersions: { type: 'stateful', definition: testParameter } }
+        }
+      }
+
+      async refresh(): Promise<Partial<any> | null> {
+        return {};
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan(
+      { type: 'type' },
+      { nodeVersions: ['20.15'] } as any,
+      null,
+      false
+    )
+
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.NOOP);
+  })
+
+  it('Accepts a string equals value', async () => {
+    const testParameter = spy(new class extends TestStatefulParameter {
+      getSettings(): ParameterSetting {
+        return {
+          type: 'string',
+          isEqual: 'version'
+        }
+      }
+
+      async refresh(): Promise<any> {
+        return '20.15.0';
+      }
+    });
+
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<any> {
+        return {
+          id: 'type',
+          parameterSettings: { propA: { type: 'stateful', definition: testParameter } }
+        }
+      }
+
+      async refresh(): Promise<Partial<any> | null> {
+        return {};
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan(
+      { type: 'type' },
+      { propA: '20.15', } as any,
+      null,
+      false
+    )
+
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.NOOP);
+  })
+
+  it('Accepts a string isElementEquals value', async () => {
+    const testParameter = spy(new class extends TestStatefulParameter {
+      getSettings(): ParameterSetting {
+        return {
+          type: 'array',
+          isElementEqual: 'version'
+        }
+      }
+
+      async refresh(): Promise<any> {
+        return [
+          '20.15.0',
+          '20.18.0'
+        ]
+      }
+    });
+
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<any> {
+        return {
+          id: 'type',
+          parameterSettings: { propA: { type: 'stateful', definition: testParameter } }
+        }
+      }
+
+      async refresh(): Promise<Partial<any> | null> {
+        return {};
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan(
+      { type: 'type' },
+      { propA: ['20.15', '20.18'] } as any,
+      null,
+      false
+    )
+
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.NOOP);
+  })
+})

package/src/stateful-parameter/stateful-parameter-controller.ts

@@ -0,0 +1,111 @@
+import { StringIndexedObject } from 'codify-schemas';
+
+import { Plan } from '../plan/plan.js';
+import { ParsedArrayParameterSetting, ParsedParameterSetting, } from '../resource/parsed-resource-settings.js';
+import {
+  ArrayParameterSetting,
+  ParameterSetting,
+  resolveElementEqualsFn,
+  resolveEqualsFn,
+} from '../resource/resource-settings.js';
+import { ArrayStatefulParameter, StatefulParameter } from './stateful-parameter.js';
+
+/**
+ * This class is analogous to what {@link ResourceController} is for {@link Resource}
+ * It's a bit messy because this class supports both {@link StatefulParameter} and {@link ArrayStatefulParameter}
+ */
+export class StatefulParameterController<T extends StringIndexedObject, V extends T[keyof T]> {
+  readonly sp: ArrayStatefulParameter<T, V> | StatefulParameter<T, V>
+  readonly settings: ParameterSetting;
+  readonly parsedSettings: ParsedParameterSetting
+
+  private readonly isArrayStatefulParameter: boolean;
+
+  constructor(
+    statefulParameter: ArrayStatefulParameter<T, V> | StatefulParameter<T, V>
+  ) {
+    this.sp = statefulParameter;
+    this.settings = statefulParameter.getSettings();
+    this.isArrayStatefulParameter = this.calculateIsArrayStatefulParameter();
+
+    this.parsedSettings = (this.isArrayStatefulParameter || this.settings.type === 'array') ? {
+      ...this.settings,
+      isEqual: resolveEqualsFn(this.settings),
+      isElementEqual: resolveElementEqualsFn(this.settings as ArrayParameterSetting)
+    } as ParsedParameterSetting : {
+      ...this.settings,
+      isEqual: resolveEqualsFn(this.settings),
+    };
+  }
+
+  async refresh(desired: V | null, config: Partial<T>): Promise<V | null> {
+    return await this.sp.refresh(desired as any, config) as V | null;
+  }
+
+  async add(valueToAdd: V, plan: Plan<T>): Promise<void> {
+    if (!this.isArrayStatefulParameter) {
+      const sp = this.sp as StatefulParameter<T, V>;
+      return sp.add(valueToAdd, plan);
+    }
+
+    const sp = this.sp as ArrayStatefulParameter<any, any>;
+    const valuesToAdd = valueToAdd as Array<any>;
+    for (const value of valuesToAdd) {
+      await sp.addItem(value, plan);
+    }
+  }
+
+  async modify(newValue: V, previousValue: V, plan: Plan<T>): Promise<void> {
+    if (!this.isArrayStatefulParameter) {
+      const sp = this.sp as StatefulParameter<T, V>;
+      return sp.modify(newValue, previousValue, plan);
+    }
+
+    const sp = this.sp as ArrayStatefulParameter<any, any>;
+    const settings = this.parsedSettings as ParsedArrayParameterSetting;
+    const newValues = newValue as Array<unknown>[];
+    const previousValues = previousValue as Array<unknown>[];
+
+    // TODO: I don't think this works with duplicate elements. Solve at another time
+    const valuesToAdd = newValues.filter((n) => !previousValues.some((p) => {
+      if (settings.isElementEqual) {
+        return settings.isElementEqual!(n, p);
+      }
+
+      return n === p;
+    }));
+
+    const valuesToRemove = previousValues.filter((p) => !newValues.some((n) => {
+      if (settings.isElementEqual) {
+        return settings.isElementEqual!(n, p);
+      }
+
+      return n === p;
+    }));
+
+    for (const value of valuesToAdd) {
+      await sp.addItem(value, plan)
+    }
+
+    for (const value of valuesToRemove) {
+      await sp.removeItem(value, plan)
+    }
+  }
+
+  async remove(valueToRemove: V, plan: Plan<T>): Promise<void> {
+    if (!this.isArrayStatefulParameter) {
+      const sp = this.sp as StatefulParameter<T, V>;
+      return sp.remove(valueToRemove, plan);
+    }
+
+    const sp = this.sp as ArrayStatefulParameter<any, any>;
+    const valuesToRemove = valueToRemove as Array<any>;
+    for (const value of valuesToRemove) {
+      await sp.removeItem(value as V, plan);
+    }
+  }
+
+  private calculateIsArrayStatefulParameter() {
+    return 'addItem' in this.sp && 'removeItem' in this.sp;
+  }
+}

package/src/stateful-parameter/stateful-parameter.ts

@@ -0,0 +1,160 @@
+import { StringIndexedObject } from 'codify-schemas';
+
+import { Plan } from '../plan/plan.js';
+import { ArrayParameterSetting, ParameterSetting } from '../resource/resource-settings.js';
+
+/**
+ * A stateful parameter represents a parameter that holds state on the system (can be created, destroyed) but
+ * is still tied to the overall lifecycle of a resource.
+ *
+ * **Examples include:**
+ * 1. Homebrew formulas are stateful parameters. They can be installed and uninstalled but they are still tied to the
+ * overall lifecycle of homebrew
+ * 2. Nvm installed node versions are stateful parameters. Nvm can install and uninstall different versions of Node but
+ * these versions are tied to the lifecycle of nvm. If nvm is uninstalled then so are the Node versions.
+ */
+export abstract class StatefulParameter<T extends StringIndexedObject, V extends T[keyof T]> {
+
+  /**
+   * Parameter settings for the stateful parameter. Stateful parameters share the same parameter settings as
+   * regular parameters except that they cannot be of type 'stateful'. See {@link ParameterSetting} for more
+   * information on available settings.
+   *
+   * @return The parameter settings
+   */
+  getSettings(): ParameterSetting {
+    return {}
+  }
+
+  /**
+   * Refresh the status of the stateful parameter on the system. This method works similarly to {@link Resource.refresh}.
+   * Return the value of the stateful parameter or null if not found.
+   *
+   * @param desired The desired value of the user.
+   * @param config The desired config
+   *
+   * @return The value of the stateful parameter currently on the system or null if not found
+   */
+  abstract refresh(desired: V | null, config: Partial<T>): Promise<V | null>;
+
+  /**
+   * Create the stateful parameter on the system. This method is similar {@link Resource.create} except that its only
+   * applicable to the stateful parameter. For resource `CREATE` operations, this method will be called after the
+   * resource is successfully created. The add method is called when a ParameterChange is ADD in a plan. The add
+   * method is only called when the stateful parameter does not currently exist.
+   *
+   * **Example (Homebrew formula):**
+   * 1. Add is called with a value of:
+   * ```
+   * ['jq', 'jenv']
+   * ```
+   * 2. Add handles the request by calling `brew install --formulae jq jenv`
+   *
+   * @param valueToAdd The desired value of the stateful parameter.
+   * @param plan The overall plan that contains the ADD
+   */
+  abstract add(valueToAdd: V, plan: Plan<T>): Promise<void>;
+
+  /**
+   * Modify the state of a stateful parameter on the system. This method is similar to {@link Resource.modify} except that its only
+   * applicable to the stateful parameter.
+   *
+   * **Example (Git email parameter):**
+   * 1. Add is called with a value of:
+   * ```
+   * newValue: 'email+new@gmail.com', previousValue: 'email+old@gmail.com'
+   * ```
+   * 2. Modify handles the request by calling `git config --global user.email email+new@gmail.com`
+   *
+   * @param newValue The desired value of the stateful parameter
+   * @param previousValue The current value of the stateful parameter
+   * @param plan The overall plan
+   */
+  abstract modify(newValue: V, previousValue: V, plan: Plan<T>): Promise<void>;
+
+  /**
+   * Create the stateful parameter on the system. This method is similar {@link Resource.destroy} except that its only
+   * applicable to the stateful parameter. The remove method is only called when the stateful parameter already currently exist.
+   * This method corresponds to REMOVE parameter operations in a plan.
+   * For resource `DESTORY`, this method is only called if the {@link ResourceSettings.removeStatefulParametersBeforeDestroy}
+   * is set to true. This method will be called before the resource is destroyed.
+   *
+   * **Example (Homebrew formula):**
+   * 1. Remove is called with a value of:
+   * ```
+   * ['jq', 'jenv']
+   * ```
+   * 2. Remove handles the request by calling `brew uninstall --formulae jq jenv`
+   *
+   * @param valueToRemove The value to remove from the stateful parameter.
+   * @param plan The overall plan that contains the REMOVE
+   */
+  abstract remove(valueToRemove: V, plan: Plan<T>): Promise<void>;
+}
+
+/**
+ * A specialized version of {@link StatefulParameter } that is used for stateful parameters which are arrays.
+ * A stateful parameter represents a parameter that holds state on the system (can be created, destroyed) but
+ * is still tied to the overall lifecycle of a resource.
+ *
+ * **Examples:**
+ * - Homebrew formulas are arrays
+ * - Pyenv python versions are arrays
+ */
+export abstract class ArrayStatefulParameter<T extends StringIndexedObject, V> {
+
+  /**
+   * Parameter settings for the stateful parameter. Stateful parameters share the same parameter settings as
+   * regular parameters except that they cannot be of type 'stateful'. See {@link ParameterSetting} for more
+   * information on available settings. Type must be 'array'.
+   *
+   * @return The parameter settings
+   */
+  getSettings(): ArrayParameterSetting {
+    return { type: 'array' }
+  }
+
+  /**
+   * See {@link StatefulParameter.refresh} for more info.
+   *
+   * @param desired The desired value to refresh
+   * @param config The desired config
+   *
+   * @return The current value on the system or null if not found.
+   */
+  abstract refresh(desired: V[] | null, config: Partial<T>): Promise<V[] | null>;
+
+  /**
+   * Helper method that gets called when individual elements of the array need to be added. See {@link StatefulParameter.add}
+   * for more information.
+   *
+   * Example (Homebrew formula):
+   * 1. The stateful parameter receives an input of:
+   * ```
+   * ['jq', 'jenv', 'docker']
+   * ```
+   * 2. Internally the stateful parameter will iterate the array and call `addItem` for each element
+   * 3. Override addItem and install each formula using `brew install --formula jq`
+   *
+   * @param item The item to add (install)
+   * @param plan The overall plan
+   */
+  abstract addItem(item: V, plan: Plan<T>): Promise<void>;
+
+  /**
+   * Helper method that gets called when individual elements of the array need to be removed. See {@link StatefulParameter.remove}
+   * for more information.
+   *
+   * Example (Homebrew formula):
+   * 1. The stateful parameter receives an input of:
+   * ```
+   * ['jq', 'jenv', 'docker']
+   * ```
+   * 2. Internally the stateful parameter will iterate the array and call `removeItem` for each element
+   * 3. Override removeItem and uninstall each formula using `brew uninstall --formula jq`
+   *
+   * @param item The item to remove (uninstall)
+   * @param plan The overall plan
+   */
+  abstract removeItem(item: V, plan: Plan<T>): Promise<void>;
+}

package/src/utils/debug.ts

@@ -0,0 +1,11 @@
+export function debugLog(message: any): void {
+  if (process.env.DEBUG) {
+    console.log(message);
+  }
+}
+
+export function debugWrite(message: any): void {
+  if (process.env.DEBUG) {
+    process.stdout.write(message);
+  }
+}

package/src/utils/file-utils.test.ts

@@ -0,0 +1,7 @@
+import { describe, it } from 'vitest';
+
+describe('File utils tests', { timeout: 100_000_000 }, () => {
+  it('Can download a file', async () => {
+    // await FileUtils.downloadFile('https://download.jetbrains.com/webstorm/WebStorm-2025.3.1-aarch64.dmg?_gl=1*1huoi7o*_gcl_aw*R0NMLjE3NjU3NDAwMTcuQ2p3S0NBaUEzZm5KQmhBZ0Vpd0F5cW1ZNVhLVENlbHJOcTk2YXdjZVlfMS1wdE91MXc0WDk2bFJkVDM3QURhUFNJMUtwNVVSVUhxWTJob0NuZ0FRQXZEX0J3RQ..*_gcl_au*MjA0MDQ0MjE2My4xNzYzNjQzNzMz*FPAU*MjA0MDQ0MjE2My4xNzYzNjQzNzMz*_ga*MTYxMDg4MTkzMi4xNzYzNjQzNzMz*_ga_9J976DJZ68*czE3NjYzNjI5ODAkbzEyJGcxJHQxNzY2MzYzMDQwJGo2MCRsMCRoMA..', path.join(process.cwd(), 'google.html'));
+  })
+})