@codifycli/plugin-core 1.0.0-beta1

package/dist/utils/utils.js

@@ -0,0 +1,86 @@
+import os from 'node:os';
+import path from 'node:path';
+export const VerbosityLevel = new class {
+    level = 0;
+    get() {
+        return this.level;
+    }
+    set(level) {
+        this.level = level;
+    }
+};
+export function isDebug() {
+    return process.env.DEBUG != null && process.env.DEBUG.includes('codify'); // TODO: replace with debug library
+}
+export function splitUserConfig(config) {
+    const coreParameters = {
+        type: config.type,
+        ...(config.name ? { name: config.name } : {}),
+        ...(config.dependsOn ? { dependsOn: config.dependsOn } : {}),
+    };
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { type, name, dependsOn, ...parameters } = config;
+    return {
+        parameters: parameters,
+        coreParameters,
+    };
+}
+export function setsEqual(set1, set2) {
+    return set1.size === set2.size && [...set1].every((v) => set2.has(v));
+}
+const homeDirectory = os.homedir();
+export function untildify(pathWithTilde) {
+    return homeDirectory ? pathWithTilde.replace(/^~(?=$|\/|\\)/, homeDirectory) : pathWithTilde;
+}
+export function tildify(pathWithTilde) {
+    return homeDirectory ? pathWithTilde.replace(homeDirectory, '~') : pathWithTilde;
+}
+export function resolvePathWithVariables(pathWithVariables) {
+    // @ts-expect-error Ignore this for now
+    return pathWithVariables.replace(/\$([A-Z_]+[A-Z0-9_]*)|\${([A-Z0-9_]*)}/ig, (_, a, b) => process.env[a || b]);
+}
+export function addVariablesToPath(pathWithoutVariables) {
+    let result = pathWithoutVariables;
+    for (const [key, value] of Object.entries(process.env)) {
+        if (!value || !path.isAbsolute(value) || value === '/' || key === 'HOME' || key === 'PATH' || key === 'SHELL' || key === 'PWD') {
+            continue;
+        }
+        result = result.replaceAll(value, `$${key}`);
+    }
+    return result;
+}
+export function unhome(pathWithHome) {
+    return pathWithHome.includes('$HOME') ? pathWithHome.replaceAll('$HOME', os.homedir()) : pathWithHome;
+}
+export function areArraysEqual(isElementEqual, desired, current) {
+    if (!desired || !current) {
+        return false;
+    }
+    if (!Array.isArray(desired) || !Array.isArray(current)) {
+        throw new Error(`A non-array value:
+          
+Desired: ${JSON.stringify(desired, null, 2)}
+
+Current: ${JSON.stringify(desired, null, 2)}
+
+Was provided even though type array was specified.
+`);
+    }
+    if (desired.length !== current.length) {
+        return false;
+    }
+    const desiredCopy = [...desired];
+    const currentCopy = [...current];
+    // Algorithm for to check equality between two un-ordered; un-hashable arrays using
+    // an isElementEqual method. Time: O(n^2)
+    for (let counter = desiredCopy.length - 1; counter >= 0; counter--) {
+        const idx = currentCopy.findIndex((e2) => (isElementEqual
+            ?? ((a, b) => a === b))(desiredCopy[counter], e2));
+        if (idx === -1) {
+            return false;
+        }
+        desiredCopy.splice(counter, 1);
+        currentCopy.splice(idx, 1);
+    }
+    return currentCopy.length === 0;
+}

package/dist/utils/verbosity-level.d.ts

@@ -0,0 +1,5 @@
+export declare const VerbosityLevel: {
+    level: number;
+    get(): number;
+    set(level: number): void;
+};

package/dist/utils/verbosity-level.js

@@ -0,0 +1,9 @@
+export const VerbosityLevel = new class {
+    level = 0;
+    get() {
+        return this.level;
+    }
+    set(level) {
+        this.level = level;
+    }
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@codifycli/plugin-core",
+  "version": "1.0.0-beta1",
+  "description": "Core library for implementing a plugin for Codify",
+  "main": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "test": "vitest",
+    "posttest": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "bin": {
+    "codify-build": "./bin/build.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@homebridge/node-pty-prebuilt-multiarch": "^0.13.1",
+    "@npmcli/promise-spawn": "^7.0.1",
+    "ajv": "^8.12.0",
+    "ajv-formats": "^2.1.1",
+    "clean-deep": "^3.4.0",
+    "codify-schemas": "1.0.86-beta11",
+    "lodash.isequal": "^4.5.0",
+    "nanoid": "^5.0.9",
+    "strip-ansi": "^7.1.0",
+    "uuid": "^10.0.0",
+    "zod": "4.1.13"
+  },
+  "devDependencies": {
+    "@apidevtools/json-schema-ref-parser": "^11.7.2",
+    "@oclif/prettier-config": "^0.2.1",
+    "@oclif/test": "^3",
+    "@types/lodash.isequal": "^4.5.8",
+    "@types/node": "^20",
+    "@types/npmcli__promise-spawn": "^6.0.3",
+    "@types/semver": "^7.5.4",
+    "@types/sinon": "^17.0.3",
+    "@types/uuid": "^10.0.0",
+    "chai-as-promised": "^7.1.1",
+    "eslint": "^8.51.0",
+    "eslint-config-oclif": "^5",
+    "eslint-config-oclif-typescript": "^3",
+    "eslint-config-prettier": "^9.0.0",
+    "merge-json-schemas": "^1.0.0",
+    "shx": "^0.3.3",
+    "sinon": "^17.0.1",
+    "ts-node": "^10.9.1",
+    "tsc-watch": "^6.0.4",
+    "typescript": "^5",
+    "vitest": "^3.0.5",
+    "vitest-mock-extended": "^1.3.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/rollup.config.js

@@ -0,0 +1,24 @@
+import commonjs from '@rollup/plugin-commonjs';
+import json from '@rollup/plugin-json';
+import nodeResolve from '@rollup/plugin-node-resolve';
+import terser from '@rollup/plugin-terser';
+import typescript from '@rollup/plugin-typescript';
+
+export default {
+  input: 'src/index.ts',
+  output: {
+    dir: 'dist',
+    format: 'cjs',
+    inlineDynamicImports: true,
+  },
+  external: ['@homebridge/node-pty-prebuilt-multiarch'],
+  plugins: [
+    json(),
+    nodeResolve({ exportConditions: ['node'] }),
+    typescript({
+      exclude: ['**/*.test.ts', '**/*.d.ts', 'test']
+    }),
+    commonjs(),
+    terser()
+  ]
+}

package/src/common/errors.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { ApplyValidationError } from './errors.js';
+import { testPlan } from '../utils/test-utils.test.js';
+
+describe('Test file for errors file', () => {
+  it('Can properly format ApplyValidationError', () => {
+    const plan = testPlan({
+      desired: null,
+      current: [{ propZ: ['a', 'b', 'c'] }],
+      state: { propZ: ['a', 'b', 'c'] },
+      core: {
+        type: 'homebrew',
+        name: 'first'
+      },
+      isStateful: true,
+    })
+
+    try {
+      throw new ApplyValidationError(plan);
+    } catch (e) {
+      console.error(e);
+      expect(e.message).toMatch(
+        `Failed to apply changes to resource: "homebrew.first". Additional changes are needed to complete apply.
+Changes remaining:
+{
+  "operation": "destroy",
+  "parameters": [
+    {
+      "name": "propZ",
+      "operation": "remove",
+      "currentValue": [
+        "a",
+        "b",
+        "c"
+      ],
+      "desiredValue": null
+    }
+  ]
+}`
+      )
+    }
+  })
+})

package/src/common/errors.ts

@@ -0,0 +1,31 @@
+import { Plan } from '../plan/plan.js';
+
+export class ApplyValidationError extends Error {
+  resourceType: string;
+  resourceName?: string;
+  plan: Plan<any>;
+
+  constructor(plan: Plan<any>) {
+    super(`Failed to apply changes to resource: "${plan.resourceId}". Additional changes are needed to complete apply.\nChanges remaining:\n${ApplyValidationError.prettyPrintPlan(plan)}`);
+
+    this.resourceType = plan.coreParameters.type;
+    this.resourceName = plan.coreParameters.name;
+    this.plan = plan;
+  }
+
+  private static prettyPrintPlan(plan: Plan<any>): string {
+    const { operation, parameters } = plan.toResponse();
+
+    const prettyParameters = parameters.map(({ name, operation, previousValue, newValue }) => ({
+      name,
+      operation,
+      currentValue: previousValue,
+      desiredValue: newValue,
+    }));
+
+    return JSON.stringify({
+      operation,
+      parameters: prettyParameters,
+    }, null, 2);
+  }
+}

package/src/errors.ts

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

package/src/index.test.ts

@@ -0,0 +1,6 @@
+import { describe, it } from 'vitest';
+
+describe('Library integration tests', () => {
+  it('does something', async () => {
+  })
+});

package/src/index.ts

@@ -0,0 +1,30 @@
+import { MessageHandler } from './messages/handlers.js';
+import { Plugin } from './plugin/plugin.js';
+
+export * from './errors.js'
+export * from './messages/sender.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 './pty/background-pty.js';
+export * from './pty/index.js'
+export * from './pty/seqeuntial-pty.js';
+export * from './resource/parsed-resource-settings.js';
+export * from './resource/resource.js'
+export * from './resource/resource-settings.js'
+export * from './stateful-parameter/stateful-parameter.js'
+export * from './utils/file-utils.js'
+export * from './utils/functions.js'
+export * from './utils/index.js'
+export * from './utils/verbosity-level.js'
+export * from 'zod/v4';
+
+export async function runPlugin(plugin: Plugin) {
+  const messageHandler = new MessageHandler(plugin);
+  process.on('message', (message) => messageHandler.onMessage(message))
+
+  process.on('beforeExit', () => {
+    plugin.kill();
+  })
+}

package/src/messages/handlers.test.ts

@@ -0,0 +1,329 @@
+import { MessageHandler } from './handlers.js';
+import { Plugin } from '../plugin/plugin.js';
+import { describe, expect, it } from 'vitest';
+import { mock } from 'vitest-mock-extended'
+import { Resource } from '../resource/resource.js';
+import { MessageStatus, ResourceOperation } from 'codify-schemas';
+import { TestResource } from '../utils/test-utils.test.js';
+
+describe('Message handler tests', () => {
+  it('handles plan requests', async () => {
+    const plugin = mock<Plugin>();
+    const handler = new MessageHandler(plugin);
+
+    process.send = (message) => {
+      expect(message).toMatchObject({
+        cmd: 'plan_Response',
+        status: MessageStatus.SUCCESS,
+      });
+
+      return true;
+    }
+
+    // Message handler also validates the response. That part does not need to be tested
+    try {
+      await handler.onMessage({
+        cmd: 'plan',
+        data: {
+          core: {
+            type: 'resourceType',
+            name: 'name',
+          },
+          desired: {
+            prop1: 'A',
+            prop2: 'B',
+          },
+          isStateful: false,
+        }
+      })
+    } catch (e) {}
+
+    expect(plugin.plan.mock.calls.length).to.eq(1);
+    process.send = undefined;
+  })
+
+  it('rejects bad plan requests', async () => {
+    const plugin = mock<Plugin>();
+    const handler = new MessageHandler(plugin);
+
+    process.send = (message) => {
+      expect(message).toMatchObject({
+        cmd: 'plan_Response',
+        status: MessageStatus.ERROR,
+      });
+
+      return true;
+    }
+
+    // Message handler also validates the response. That part does not need to be tested
+    try {
+      await handler.onMessage({
+        cmd: 'plan',
+        data: {
+          name: '1name',
+          prop1: 'A',
+          prop2: 'B',
+        }
+      })
+    } catch (e) {
+      console.log(e);
+    }
+
+    expect(plugin.plan.mock.calls.length).to.eq(0);
+    process.send = undefined;
+  })
+
+  it('handles apply requests', async () => {
+    const plugin = mock<Plugin>();
+    const handler = new MessageHandler(plugin);
+
+    // Message handler also validates the response. That part does not need to be tested
+    try {
+      await handler.onMessage({
+        cmd: 'apply',
+        data: {
+          planId: '1803fff7-a378-4006-95bb-7c97cba02c82'
+        }
+      })
+    } catch (e) {}
+
+    expect(plugin.apply.mock.calls.length).to.be.eq(1);
+  })
+
+  it('rejects bad apply requests', async () => {
+    const plugin = mock<Plugin>();
+    const handler = new MessageHandler(plugin);
+
+    // Message handler also validates the response. That part does not need to be tested
+    try {
+      await handler.onMessage({
+        cmd: 'apply',
+        data: {}
+      })
+    } catch (e) {}
+
+    expect(plugin.apply.mock.calls.length).to.be.eq(0);
+  })
+
+  it('handles validate requests', async () => {
+    const plugin = mock<Plugin>();
+    const handler = new MessageHandler(plugin);
+
+    // Message handler also validates the response. That part does not need to be tested
+    try {
+      await handler.onMessage({
+        cmd: 'validate',
+        data: {
+          configs: [
+            {
+              type: 'type1',
+              name: 'name1'
+            },
+            {
+              type: 'type2',
+              name: 'name2'
+            },
+            {
+              type: 'type2',
+              name: 'name3'
+            }
+          ]
+        }
+      })
+    } catch (e) {}
+
+    expect(plugin.validate.mock.calls.length).to.eq(1);
+  })
+
+  it('rejects bad validate requests', async () => {
+    const plugin = mock<Plugin>();
+    const handler = new MessageHandler(plugin);
+
+    process.send = () => true;
+
+    // Message handler also validates the response. That part does not need to be tested
+    // This should not throw
+    expect(await handler.onMessage({
+      cmd: 'validate',
+      data: {}
+    })).to.eq(undefined);
+
+    expect(plugin.apply.mock.calls.length).to.be.eq(0);
+  })
+
+  it('handles errors for plan', async () => {
+    const resource = new TestResource()
+    const plugin = testPlugin(resource);
+
+    const handler = new MessageHandler(plugin);
+
+    process.send = (message) => {
+      expect(message).toMatchObject({
+        cmd: 'plan_Response',
+        status: MessageStatus.ERROR,
+        data: 'Refresh error',
+      })
+      return true;
+    }
+
+    expect(async () => await handler.onMessage({
+      cmd: 'plan',
+      data: {
+        core: {
+          type: 'resourceA',
+        },
+        desired: {
+          type: 'resourceA'
+        },
+        isStateful: false,
+      }
+    })).rejects.to.not.throw;
+
+    process.send = undefined;
+  })
+
+  it('handles errors for apply (create)', async () => {
+    const resource = new TestResource()
+    const plugin = testPlugin(resource);
+
+    const handler = new MessageHandler(plugin);
+
+    process.send = (message) => {
+      expect(message).toMatchObject({
+        cmd: 'apply_Response',
+        status: MessageStatus.ERROR,
+      })
+      return true;
+    }
+
+    expect(async () => await handler.onMessage({
+      cmd: 'apply',
+      data: {
+        plan: {
+          resourceType: 'resourceA',
+          operation: ResourceOperation.CREATE,
+          parameters: []
+        }
+      }
+    })).rejects.to.not.throw;
+  })
+
+  it('handles errors for apply (destroy)', async () => {
+    const resource = new TestResource()
+    const plugin = testPlugin(resource);
+    const handler = new MessageHandler(plugin);
+
+    process.send = (message) => {
+      expect(message).toMatchObject({
+        cmd: 'apply_Response',
+        status: MessageStatus.ERROR,
+      })
+      return true;
+    }
+
+    expect(async () => await handler.onMessage({
+      cmd: 'apply',
+      data: {
+        plan: {
+          resourceType: 'resourceA',
+          operation: ResourceOperation.DESTROY,
+          parameters: []
+        }
+      }
+    })).rejects.to.not.throw;
+
+    process.send = undefined;
+  })
+
+  it('handles changing the verbosity level', async () => {
+    const resource = new TestResource()
+    const plugin = testPlugin(resource);
+    const handler = new MessageHandler(plugin);
+
+    process.send = (message) => {
+      expect(message).toMatchObject({
+        cmd: 'setVerbosityLevel_Response',
+        status: MessageStatus.SUCCESS,
+      })
+      return true;
+    }
+
+    expect(async () => await handler.onMessage({
+      cmd: 'setVerbosityLevel',
+      data: {
+        verbosityLevel: 2,
+      }
+    })).rejects.to.not.throw;
+
+    process.send = undefined;
+  })
+
+  it('Supports ipc message v2 (success)', async () => {
+    const resource = new TestResource()
+    const plugin = testPlugin(resource);
+    const handler = new MessageHandler(plugin);
+
+    process.send = (message) => {
+      console.log(message)
+      expect(message).toMatchObject({
+        cmd: 'plan_Response',
+        requestId: 'abcdef',
+        status: MessageStatus.SUCCESS,
+      })
+      return true;
+    }
+
+    await expect(handler.onMessage({
+      cmd: 'plan',
+      requestId: 'abcdef',
+      data: {
+        core: {
+          type: 'type',
+          name: 'name',
+        },
+        desired: {
+          prop1: 'A',
+          prop2: 'B',
+        },
+        isStateful: false,
+      }
+    })).resolves.to.eq(undefined);
+
+    process.send = undefined;
+  })
+
+  it('Supports ipc message v2 (error)', async () => {
+    const resource = new TestResource()
+    const plugin = testPlugin(resource);
+    const handler = new MessageHandler(plugin);
+
+    process.send = (message) => {
+      expect(message).toMatchObject({
+        cmd: 'apply_Response',
+        requestId: 'abcdef',
+        status: MessageStatus.ERROR,
+      })
+      return true;
+    }
+
+    await expect(handler.onMessage({
+      cmd: 'apply', // Supposed to be a plan so that's why it throws
+      requestId: 'abcdef',
+      data: {
+        desired: {
+          type: 'type',
+          name: 'name',
+          prop1: 'A',
+          prop2: 'B',
+        },
+        isStateful: false,
+      }
+    })).resolves.to.eq(undefined);
+
+    process.send = undefined;
+  })
+});
+
+function testPlugin(resource: Resource<any>) {
+  return Plugin.create('plugin', [resource])
+}