@codifycli/plugin-core 1.0.0-beta1

package/.eslintignore

@@ -0,0 +1,2 @@
+/dist
+/node_modules

package/.eslintrc.json

@@ -0,0 +1,30 @@
+{
+  "extends": [
+    "oclif",
+    "oclif-typescript",
+    "prettier"
+  ],
+  "rules": {
+    "object-curly-spacing": [
+      "warn",
+      "always"
+    ],
+    "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,18 @@
+# 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: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run test

package/.prettierrc.json

@@ -0,0 +1 @@
+"@oclif/prettier-config"

package/bin/build.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { Ajv } from 'ajv';
+import { IpcMessageSchema, MessageStatus, ResourceSchema } from 'codify-schemas';
+import mergeJsonSchemas from 'merge-json-schemas';
+import { fork } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { SequentialPty, VerbosityLevel } from '../dist/index.js';
+
+const ajv = new Ajv({
+  strict: true
+});
+const ipcMessageValidator = ajv.compile(IpcMessageSchema);
+
+function sendMessageAndAwaitResponse(process, message) {
+  return new Promise((resolve, reject) => {
+    process.on('message', (response) => {
+      if (!ipcMessageValidator(response)) {
+        throw new Error(`Invalid message from plugin. ${JSON.stringify(message, null, 2)}`);
+      }
+
+      // Wait for the message response. Other messages such as sudoRequest may be sent before the response returns
+      if (response.cmd === message.cmd + '_Response') {
+        if (response.status === MessageStatus.SUCCESS) {
+          resolve(response.data)
+        } else {
+          reject(new Error(String(response.data)))
+        }
+      }
+    });
+
+    // Send message last to ensure listeners are all registered
+    process.send(message);
+  });
+}
+
+function fetchDocumentationMaps() {
+  console.log('Building documentation...');
+
+  const results = new Map();
+  const resourcesPath = path.resolve(process.cwd(), 'src', 'resources');
+  const resourcesDir = fs.readdirSync(resourcesPath);
+
+  for (const resource of resourcesDir) {
+    const resourcePath = path.join(resourcesPath, resource);
+    if (!isDirectory(resourcePath)) continue;
+
+    const contents = fs.readdirSync(resourcePath);
+    const isGroup = contents.some((content) => isDirectory(path.join(resourcePath, content)));
+    const isAllDir = contents.every((content) => isDirectory(path.join(resourcePath, content)));
+
+    if (isGroup && !isAllDir) {
+      throw new Error(`Documentation groups must only contain directories. ${resourcePath} does not`);
+    }
+
+    if (!isGroup) {
+      if (contents.includes('README.md')) {
+        results.set(resource, resource);
+      }
+    } else {
+      for (const innerDir of contents) {
+        const innerDirReadme = path.join(resourcePath, innerDir, 'README.md');
+        if (isFile(innerDirReadme)) {
+          results.set(innerDir, path.relative('./src/resources', path.join(resourcePath, innerDir)));
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+function isDirectory(path) {
+  try {
+    return fs.statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(path) {
+  try {
+    return fs.statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+VerbosityLevel.set(3);
+const $ = new SequentialPty();
+
+await $.spawn('rm -rf ./dist')
+await $.spawn('npm run rollup -- -f es', { interactive: true });
+
+const plugin = fork(
+  './dist/index.js',
+  [],
+  {
+    // Use default true to test plugins in secure mode (un-able to request sudo directly)
+    detached: true,
+    env: { ...process.env },
+    execArgv: ['--import', 'tsx/esm'],
+  },
+)
+
+const initializeResult = await sendMessageAndAwaitResponse(plugin, {
+  cmd: 'initialize',
+  data: {}
+})
+
+const { resourceDefinitions } = initializeResult;
+const resourceTypes = resourceDefinitions.map((i) => i.type);
+const resourceInfoMap = new Map();
+
+const schemasMap = new Map()
+for (const type of resourceTypes) {
+  const resourceInfo = await sendMessageAndAwaitResponse(plugin, {
+    cmd: 'getResourceInfo',
+    data: { type }
+  })
+
+  schemasMap.set(type, resourceInfo.schema);
+  resourceInfoMap.set(type, resourceInfo);
+}
+
+console.log(resourceInfoMap);
+
+const mergedSchemas = [...schemasMap.entries()].map(([type, schema]) => {
+  // const resolvedSchema = await $RefParser.dereference(schema)
+  const resourceSchema = JSON.parse(JSON.stringify(ResourceSchema));
+
+  delete resourceSchema.$id;
+  delete resourceSchema.$schema;
+  delete resourceSchema.title;
+  delete resourceSchema.oneOf;
+  delete resourceSchema.properties.type;
+
+  if (schema) {
+    delete schema.$id;
+    delete schema.$schema;
+    delete schema.title;
+    delete schema.oneOf;
+  }
+
+  return mergeJsonSchemas([schema ?? {}, resourceSchema, { properties: { type: { const: type, type: 'string' } } }]);
+});
+
+
+await $.spawn('rm -rf ./dist')
+await $.spawn('npm run rollup', { interactive: true }); // re-run rollup without building for es
+
+console.log('Generated JSON Schemas for all resources')
+
+const distFolder = path.resolve(process.cwd(), 'dist');
+const schemaOutputPath = path.resolve(distFolder, 'schemas.json');
+fs.writeFileSync(schemaOutputPath, JSON.stringify(mergedSchemas, null, 2));
+
+console.log('Successfully wrote schema to ./dist/schemas.json');
+
+const documentationMap = fetchDocumentationMaps();
+
+const packageJson = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
+
+fs.writeFileSync('./dist/manifest.json', JSON.stringify({
+  name: packageJson.name,
+  version: packageJson.version,
+  description: packageJson.description,
+  resources: [...resourceInfoMap.values()].map((info) => ({
+    type: info.type,
+    description: info.description ?? info.schema?.description,
+    sensitiveParameters: info.sensitiveParameters,
+    schema: info.schema,
+    operatingSystems: info.operatingSystems,
+    documentationKey: documentationMap.get(info.type),
+  })),
+}, null, 2), 'utf8');
+
+for (const key of documentationMap.values()) {
+  fs.mkdirSync(path.join('dist', 'documentation', key), { recursive: true })
+
+  fs.copyFileSync(
+    path.resolve(path.join('src', 'resources', key, 'README.md')),
+    path.resolve(path.join('dist', 'documentation', key, 'README.md')),
+  );
+}
+
+plugin.kill(9);
+process.exit(0);

package/dist/bin/build.d.ts

@@ -0,0 +1 @@
+export declare function build(): Promise<void>;

package/dist/bin/build.js

@@ -0,0 +1,80 @@
+import { Ajv } from 'ajv';
+import { IpcMessageSchema, MessageStatus, ResourceSchema } from 'codify-schemas';
+// @ts-ignore
+import mergeJsonSchemas from 'merge-json-schemas';
+import { fork } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import * as url from 'node:url';
+import { codifySpawn } from '../utils/codify-spawn.js';
+const ajv = new Ajv({
+    strict: true
+});
+const ipcMessageValidator = ajv.compile(IpcMessageSchema);
+function sendMessageAndAwaitResponse(process, message) {
+    return new Promise((resolve, reject) => {
+        process.on('message', (response) => {
+            if (!ipcMessageValidator(response)) {
+                throw new Error(`Invalid message from plugin. ${JSON.stringify(message, null, 2)}`);
+            }
+            // Wait for the message response. Other messages such as sudoRequest may be sent before the response returns
+            if (response.cmd === message.cmd + '_Response') {
+                if (response.status === MessageStatus.SUCCESS) {
+                    resolve(response.data);
+                }
+                else {
+                    reject(new Error(String(response.data)));
+                }
+            }
+        });
+        // Send message last to ensure listeners are all registered
+        process.send(message);
+    });
+}
+export async function build() {
+    await fs.rm('./dist', { force: true, recursive: true });
+    await codifySpawn('npm run rollup -- -f es');
+    const plugin = fork('./dist/index.js', [], {
+        // Use default true to test plugins in secure mode (un-able to request sudo directly)
+        detached: true,
+        env: { ...process.env },
+        execArgv: ['--import', 'tsx/esm'],
+    });
+    const initializeResult = await sendMessageAndAwaitResponse(plugin, {
+        cmd: 'initialize',
+        data: {}
+    });
+    const { resourceDefinitions } = initializeResult;
+    const resourceTypes = resourceDefinitions.map((i) => i.type);
+    const schemasMap = new Map();
+    for (const type of resourceTypes) {
+        const resourceInfo = await sendMessageAndAwaitResponse(plugin, {
+            cmd: 'getResourceInfo',
+            data: { type }
+        });
+        schemasMap.set(type, resourceInfo.schema);
+    }
+    const mergedSchemas = [...schemasMap.entries()].map(([type, schema]) => {
+        // const resolvedSchema = await $RefParser.dereference(schema)
+        const resourceSchema = JSON.parse(JSON.stringify(ResourceSchema));
+        delete resourceSchema.$id;
+        delete resourceSchema.$schema;
+        delete resourceSchema.title;
+        delete resourceSchema.oneOf;
+        delete resourceSchema.properties.type;
+        if (schema) {
+            delete schema.$id;
+            delete schema.$schema;
+            delete schema.title;
+            delete schema.oneOf;
+        }
+        return mergeJsonSchemas([schema ?? {}, resourceSchema, { properties: { type: { const: type, type: 'string' } } }]);
+    });
+    await fs.rm('./dist', { force: true, recursive: true });
+    await codifySpawn('npm run rollup'); // re-run rollup without building for es
+    console.log('Generated JSON Schemas for all resources');
+    const distFolder = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..', 'dist');
+    const schemaOutputPath = path.resolve(distFolder, 'schemas.json');
+    await fs.writeFile(schemaOutputPath, JSON.stringify(mergedSchemas, null, 2));
+    console.log('Successfully wrote schema to ./dist/schemas.json');
+}

package/dist/bin/deploy-plugin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/deploy-plugin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import * as fs from 'node:fs';
+import { build } from './build.js';
+const packageJson = fs.readFileSync(path.join(process.env['npm_config_local_prefix'], 'package.json'), 'utf8');
+const { name: libraryName, version: libraryVersion } = JSON.parse(packageJson);
+console.log(libraryName, libraryVersion);
+await build();

package/dist/common/errors.d.ts

@@ -0,0 +1,8 @@
+import { Plan } from '../plan/plan.js';
+export declare class ApplyValidationError extends Error {
+    resourceType: string;
+    resourceName?: string;
+    plan: Plan<any>;
+    constructor(plan: Plan<any>);
+    private static prettyPrintPlan;
+}

package/dist/common/errors.js

@@ -0,0 +1,24 @@
+export class ApplyValidationError extends Error {
+    resourceType;
+    resourceName;
+    plan;
+    constructor(plan) {
+        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;
+    }
+    static prettyPrintPlan(plan) {
+        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/dist/entities/change-set.d.ts

@@ -0,0 +1,24 @@
+import { ParameterOperation, ResourceOperation, StringIndexedObject } from 'codify-schemas';
+import { ParameterOptions } from './plan-types.js';
+export interface ParameterChange<T extends StringIndexedObject> {
+    name: keyof T & string;
+    operation: ParameterOperation;
+    previousValue: any | null;
+    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 calculateParameterChangeSet<T extends StringIndexedObject>(desired: T | null, current: T | null, options: {
+        statefulMode: boolean;
+        parameterOptions?: Record<keyof T, ParameterOptions>;
+    }): ParameterChange<T>[];
+    static combineResourceOperations(prev: ResourceOperation, next: ResourceOperation): ResourceOperation;
+    static isSame(desired: unknown, current: unknown, options?: ParameterOptions): boolean;
+    private static calculateStatefulModeChangeSet;
+    private static calculateStatelessModeChangeSet;
+    private static addDefaultValues;
+}

package/dist/entities/change-set.js

@@ -0,0 +1,152 @@
+import { ParameterOperation, ResourceOperation } from 'codify-schemas';
+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 calculateParameterChangeSet(desired, current, options) {
+        if (options.statefulMode) {
+            return ChangeSet.calculateStatefulModeChangeSet(desired, current, options.parameterOptions);
+        }
+        else {
+            return ChangeSet.calculateStatelessModeChangeSet(desired, current, options.parameterOptions);
+        }
+    }
+    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, options) {
+        if (options?.isEqual) {
+            return options.isEqual(desired, current);
+        }
+        if (Array.isArray(desired) && Array.isArray(current)) {
+            const sortedDesired = desired.map((x) => x).sort();
+            const sortedCurrent = current.map((x) => x).sort();
+            if (sortedDesired.length !== sortedCurrent.length) {
+                return false;
+            }
+            if (options?.isElementEqual) {
+                return sortedDesired.every((value, index) => options.isElementEqual(value, sortedCurrent[index]));
+            }
+            return JSON.stringify(sortedDesired) === JSON.stringify(sortedCurrent);
+        }
+        return desired === current;
+    }
+    static calculateStatefulModeChangeSet(desired, current, parameterOptions) {
+        const parameterChangeSet = new Array();
+        const _desired = Object.fromEntries(Object.entries(desired ?? {}).filter(([, v]) => v != null));
+        const _current = Object.fromEntries(Object.entries(current ?? {}).filter(([, v]) => v != null));
+        this.addDefaultValues(_desired, parameterOptions);
+        for (const [k, v] of Object.entries(_current)) {
+            if (_desired[k] == null) {
+                parameterChangeSet.push({
+                    name: k,
+                    previousValue: v,
+                    newValue: null,
+                    operation: ParameterOperation.REMOVE,
+                });
+                delete _current[k];
+                continue;
+            }
+            if (!ChangeSet.isSame(_desired[k], _current[k], parameterOptions?.[k])) {
+                parameterChangeSet.push({
+                    name: k,
+                    previousValue: v,
+                    newValue: _desired[k],
+                    operation: ParameterOperation.MODIFY,
+                });
+                delete _current[k];
+                delete _desired[k];
+                continue;
+            }
+            parameterChangeSet.push({
+                name: k,
+                previousValue: v,
+                newValue: _desired[k],
+                operation: ParameterOperation.NOOP,
+            });
+            delete _current[k];
+            delete _desired[k];
+        }
+        if (Object.keys(_current).length !== 0) {
+            throw Error('Diff algorithm error');
+        }
+        for (const [k, v] of Object.entries(_desired)) {
+            parameterChangeSet.push({
+                name: k,
+                previousValue: null,
+                newValue: v,
+                operation: ParameterOperation.ADD,
+            });
+        }
+        return parameterChangeSet;
+    }
+    static calculateStatelessModeChangeSet(desired, current, parameterOptions) {
+        const parameterChangeSet = new Array();
+        const _desired = Object.fromEntries(Object.entries(desired ?? {}).filter(([, v]) => v != null));
+        const _current = Object.fromEntries(Object.entries(current ?? {}).filter(([, v]) => v != null));
+        this.addDefaultValues(_desired, parameterOptions);
+        for (const [k, v] of Object.entries(_desired)) {
+            if (_current[k] == null) {
+                parameterChangeSet.push({
+                    name: k,
+                    previousValue: null,
+                    newValue: v,
+                    operation: ParameterOperation.ADD,
+                });
+                continue;
+            }
+            if (!ChangeSet.isSame(_desired[k], _current[k], parameterOptions?.[k])) {
+                parameterChangeSet.push({
+                    name: k,
+                    previousValue: _current[k],
+                    newValue: _desired[k],
+                    operation: ParameterOperation.MODIFY,
+                });
+                continue;
+            }
+            parameterChangeSet.push({
+                name: k,
+                previousValue: v,
+                newValue: v,
+                operation: ParameterOperation.NOOP,
+            });
+        }
+        return parameterChangeSet;
+    }
+    static addDefaultValues(obj, options) {
+        Object.entries(options ?? {})
+            .filter(([, option]) => option.default !== undefined)
+            .map(([name, option]) => [name, option.default])
+            .forEach(([key, defaultValue]) => {
+            if (obj[key] === undefined) {
+                obj[key] = defaultValue;
+            }
+        });
+    }
+}

package/dist/entities/errors.d.ts

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

package/dist/entities/errors.js

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

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

@@ -0,0 +1,25 @@
+import { Plan } from './plan.js';
+import { StringIndexedObject } from 'codify-schemas';
+export interface ParameterOptions {
+    modifyOnChange?: boolean;
+    isEqual?: (desired: any, current: any) => boolean;
+    isElementEqual?: (desired: any, current: any) => boolean;
+    default?: unknown;
+    isStatefulParameter?: boolean;
+}
+export interface PlanOptions<T> {
+    statefulMode: boolean;
+    parameterOptions?: Record<keyof T, ParameterOptions>;
+}
+export interface CreatePlan<T extends StringIndexedObject> extends Plan<T> {
+    desiredConfig: T;
+    currentConfig: null;
+}
+export interface DestroyPlan<T extends StringIndexedObject> extends Plan<T> {
+    desiredConfig: null;
+    currentConfig: T;
+}
+export interface ModifyPlan<T extends StringIndexedObject> extends Plan<T> {
+    desiredConfig: T;
+    currentConfig: T;
+}

package/dist/entities/plan-types.js

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

package/dist/entities/plan.d.ts

@@ -0,0 +1,15 @@
+import { ChangeSet } from './change-set.js';
+import { ApplyRequestData, PlanResponseData, ResourceConfig, StringIndexedObject } from 'codify-schemas';
+import { PlanOptions } from './plan-types.js';
+export declare class Plan<T extends StringIndexedObject> {
+    id: string;
+    changeSet: ChangeSet<T>;
+    resourceMetadata: ResourceConfig;
+    constructor(id: string, changeSet: ChangeSet<T>, resourceMetadata: ResourceConfig);
+    static create<T extends StringIndexedObject>(desiredParameters: Partial<T> | null, currentParameters: Partial<T> | null, resourceMetadata: ResourceConfig, options: PlanOptions<T>): Plan<T>;
+    getResourceType(): string;
+    static fromResponse<T extends ResourceConfig>(data: ApplyRequestData['plan'], defaultValues?: Partial<Record<keyof T, unknown>>): Plan<T>;
+    get desiredConfig(): T | null;
+    get currentConfig(): T | null;
+    toResponse(): PlanResponseData;
+}