@codifycli/plugin-core 1.0.0-beta1

package/src/pty/index.ts

@@ -0,0 +1,66 @@
+import { ptyLocalStorage } from '../utils/pty-local-storage.js';
+
+export interface SpawnResult {
+  status: 'error' | 'success';
+  exitCode: number;
+  data: string;
+}
+
+export enum SpawnStatus {
+  SUCCESS = 'success',
+  ERROR = 'error',
+}
+
+/**
+ * Represents the configuration options for spawning a child process.
+ *
+ * @interface SpawnOptions
+ *
+ * @property {string} [cwd] - Specifies the working directory of the child process.
+ * If not provided, the current working directory of the parent process is used.
+ *
+ * @property {Record<string, unknown>} [env] - Defines environment key-value pairs
+ * that will be available to the child process. If not specified, the child process
+ * will inherit the environment variables of the parent process.
+ *
+ * @property {boolean} [interactive] - Indicates whether the spawned process needs
+ * to be interactive. Only works within apply (not plan). Defaults to true.
+ *
+ * @property {boolean} [disableWrapping] - Forces the terminal width to 10_000 to disable wrapping.
+ * In applys, this is off by default while it is on during plans.
+ */
+export interface SpawnOptions {
+  cwd?: string;
+  env?: Record<string, unknown>;
+  interactive?: boolean;
+  requiresRoot?: boolean;
+  stdin?: boolean;
+  disableWrapping?: boolean;
+}
+
+export class SpawnError extends Error {
+  data: string;
+  cmd: string;
+  exitCode: number;
+
+  constructor(cmd: string, exitCode: number, data: string) {
+    super(`Spawn Error: on command "${cmd}" with exit code: ${exitCode}\nOutput:\n${data}`);
+
+    this.data = data;
+    this.cmd = cmd;
+    this.exitCode = exitCode;
+  }
+
+}
+
+export interface IPty {
+  spawn(cmd: string | string[], options?: SpawnOptions): Promise<SpawnResult>
+
+  spawnSafe(cmd: string | string[], options?: SpawnOptions): Promise<SpawnResult>
+
+  kill(): Promise<{ exitCode: number, signal?: number | undefined }>
+}
+
+export function getPty(): IPty {
+  return ptyLocalStorage.getStore() as IPty;
+}

package/src/pty/promise-queue.ts

@@ -0,0 +1,33 @@
+import { nanoid } from 'nanoid';
+import EventEmitter from 'node:events';
+
+export class PromiseQueue {
+  // Cid stands for command id;
+  private queue: Array<{ cid: string, fn: () => Promise<any> | any }> = [];
+  private eventBus = new EventEmitter()
+
+  async run<T>(fn: () => Promise<T> | T): Promise<T> {
+    const cid = nanoid();
+    this.queue.push({ cid, fn })
+
+    if (this.queue.length !== 1) {
+      await new Promise((resolve) => {
+        const listener = () => {
+          if (this.queue[0].cid === cid) {
+            this.eventBus.removeListener('dequeue', listener);
+            resolve(null);
+          }
+        }
+
+        this.eventBus.on('dequeue', listener);
+      });
+    }
+
+    const result = await fn();
+
+    this.queue.shift();
+    this.eventBus.emit('dequeue');
+
+    return result;
+  }
+}

package/src/pty/seqeuntial-pty.ts

@@ -0,0 +1,151 @@
+import pty from '@homebridge/node-pty-prebuilt-multiarch';
+import { Ajv } from 'ajv';
+import { CommandRequestResponseData, CommandRequestResponseDataSchema, IpcMessageV2, MessageCmd } from 'codify-schemas';
+import { nanoid } from 'nanoid';
+import { EventEmitter } from 'node:events';
+import stripAnsi from 'strip-ansi';
+
+import { Shell, Utils } from '../utils/index.js';
+import { VerbosityLevel } from '../utils/verbosity-level.js';
+import { IPty, SpawnError, SpawnOptions, SpawnResult, SpawnStatus } from './index.js';
+
+EventEmitter.defaultMaxListeners = 1000;
+
+const ajv = new Ajv({
+  strict: true,
+});
+const validateSudoRequestResponse = ajv.compile(CommandRequestResponseDataSchema);
+
+/**
+ * The background pty is a specialized pty designed for speed. It can launch multiple tasks
+ * in parallel by moving them to the background. It attaches unix FIFO pipes to each process
+ * to listen to stdout and stderr. One limitation of the BackgroundPty is that the tasks run
+ * without a tty (or even a stdin) attached so interactive commands will not work.
+ */
+export class SequentialPty implements IPty {
+  async spawn(cmd: string | string[], options?: SpawnOptions): Promise<SpawnResult> {
+    const spawnResult = await this.spawnSafe(cmd, options);
+
+    if (spawnResult.status !== 'success') {
+      throw new SpawnError(Array.isArray(cmd) ? cmd.join('\n') : cmd, spawnResult.exitCode, spawnResult.data);
+    }
+
+    return spawnResult;
+  }
+
+  async spawnSafe(cmd: string | string[], options?: SpawnOptions): Promise<SpawnResult> {
+    cmd = Array.isArray(cmd) ? cmd.join(' ') : cmd;
+
+    if (cmd.includes('sudo')) {
+      throw new Error('Do not directly use sudo. Use the option { requiresRoot: true } instead')
+    }
+
+    // If sudo is required, we must delegate to the main codify process.
+    if (options?.stdin || options?.requiresRoot) {
+      return this.externalSpawn(cmd, options);
+    }
+
+    console.log(`Running command: ${Array.isArray(cmd) ? cmd.join('\\\n') : cmd}` + (options?.cwd ? `(${options?.cwd})` : ''))
+
+    return new Promise((resolve) => {
+      const output: string[] = [];
+      const historyIgnore = Utils.getShell() === Shell.ZSH ? { HISTORY_IGNORE: '*' } : { HISTIGNORE: '*' };
+
+      // If TERM_PROGRAM=Apple_Terminal is set then ANSI escape characters may be included
+      // in the response.
+      const env = {
+        ...process.env, ...options?.env,
+        TERM_PROGRAM: 'codify',
+        COMMAND_MODE: 'unix2003',
+        COLORTERM: 'truecolor',
+        ...historyIgnore
+      }
+
+      // Initial terminal dimensions
+      // Set to a really large value to prevent wrapping
+      const initialCols = options?.disableWrapping ? 10_000 : process.stdout.columns ?? 80
+      const initialRows = process.stdout.rows ?? 24;
+
+      const args = options?.interactive ? ['-i', '-c', cmd] : ['-c', cmd]
+
+      // Run the command in a pty for interactivity
+      const mPty = pty.spawn(this.getDefaultShell(), args, {
+        ...options,
+        cols: initialCols,
+        rows: initialRows,
+        env
+      });
+
+      mPty.onData((data) => {
+        if (VerbosityLevel.get() > 0) {
+          process.stdout.write(data);
+        }
+
+        output.push(data.toString());
+      })
+
+      const resizeListener = () => {
+        const { columns, rows } = process.stdout;
+        mPty.resize(columns, options?.disableWrapping ? 10_000 : rows);
+      }
+
+      // Listen to resize events for the terminal window;
+      process.stdout.on('resize', resizeListener);
+
+      mPty.onExit((result) => {
+        process.stdout.off('resize', resizeListener);
+
+        resolve({
+          status: result.exitCode === 0 ? SpawnStatus.SUCCESS : SpawnStatus.ERROR,
+          exitCode: result.exitCode,
+          data: stripAnsi(output.join('\n').trim()),
+        })
+      })
+    })
+  }
+
+  async kill(): Promise<{ exitCode: number, signal?: number | undefined }> {
+    // No-op here. Each pty instance is stand alone and tied to the parent process. Everything should be killed as expected.
+    return {
+      exitCode: 0,
+      signal: 0,
+    }
+  }
+
+  // For safety reasons, requests that require sudo or are interactive must be run via the main client
+  async externalSpawn(
+    cmd: string,
+    opts: SpawnOptions
+  ): Promise<SpawnResult> {
+    return new Promise((resolve) => {
+      const requestId = nanoid(8);
+
+      const listener = (data: IpcMessageV2) => {
+        if (data.requestId === requestId) {
+          process.removeListener('message', listener);
+
+          if (!validateSudoRequestResponse(data.data)) {
+            throw new Error(`Invalid response for sudo request: ${JSON.stringify(validateSudoRequestResponse.errors, null, 2)}`);
+          }
+
+          resolve(data.data as unknown as CommandRequestResponseData);
+        }
+      }
+
+      process.on('message', listener);
+
+      process.send!(<IpcMessageV2>{
+        cmd: MessageCmd.COMMAND_REQUEST,
+        data: {
+          command: cmd,
+          options: opts ?? {},
+        },
+        requestId
+      })
+    });
+  }
+
+  private getDefaultShell(): string {
+    return process.env.SHELL!;
+  }
+}

package/src/pty/sequential-pty.test.ts

@@ -0,0 +1,194 @@
+import { describe, expect, it } from 'vitest';
+import { SequentialPty } from './seqeuntial-pty.js';
+import { VerbosityLevel } from '../utils/verbosity-level.js';
+import { MessageStatus, SpawnStatus } from 'codify-schemas/src/types/index.js';
+import { IpcMessageV2, MessageCmd } from 'codify-schemas';
+
+describe('SequentialPty tests', () => {
+  it('Can launch a simple command', async () => {
+    const pty = new SequentialPty();
+
+    VerbosityLevel.set(1);
+
+    const result = await pty.spawnSafe('ls');
+    expect(result).toMatchObject({
+      status: 'success',
+      exitCode: 0,
+      data: expect.any(String),
+    })
+
+    const exitCode = await pty.kill();
+    expect(exitCode).toMatchObject({
+      exitCode: 0,
+    });
+  })
+
+  it('Reports back the correct exit code and status', async () => {
+    const pty = new SequentialPty();
+
+    const resultSuccess = await pty.spawnSafe('ls');
+    expect(resultSuccess).toMatchObject({
+      status: 'success',
+      exitCode: 0,
+    })
+
+    const resultFailed = await pty.spawnSafe('which sjkdhsakjdhjkash');
+    expect(resultFailed).toMatchObject({
+      status: 'error',
+      exitCode: 1,
+      data: 'sjkdhsakjdhjkash not found' // This might change on different os or shells. Keep for now.
+    })
+  });
+
+  it('Can use a different cwd', async () => {
+    const pty = new SequentialPty();
+
+    const resultSuccess = await pty.spawnSafe('pwd', { cwd: '/tmp' });
+    expect(resultSuccess).toMatchObject({
+      status: 'success',
+      exitCode: 0,
+      data: '/tmp'
+    })
+  });
+
+
+  it('Can use multi-line commands', async () => {
+    const pty = new SequentialPty();
+
+    const resultSuccess = await pty.spawnSafe([
+      'pwd',
+      '&& ls',
+    ], { cwd: '/tmp' });
+    expect(resultSuccess).toMatchObject({
+      status: 'success',
+      exitCode: 0,
+    })
+  });
+
+
+  it('It can launch a command in interactive mode', { timeout: 30_000 }, async () => {
+    const originalSend = process.send;
+    process.send = (req: IpcMessageV2) => {
+      expect(req).toMatchObject({
+        cmd: MessageCmd.COMMAND_REQUEST,
+        requestId: expect.any(String),
+        data: {
+          command: 'ls',
+          options: {
+            cwd: '/tmp',
+            interactive: true,
+          }
+        }
+      })
+
+      // This may look confusing but what we're doing here is directly finding the process listener and calling it without going through serialization
+      const listeners = process.listeners('message');
+      listeners[2](({
+        cmd: MessageCmd.COMMAND_REQUEST,
+        requestId: req.requestId,
+        status: MessageStatus.SUCCESS,
+        data: {
+          status: SpawnStatus.SUCCESS,
+          exitCode: 0,
+          data: 'My data',
+        }
+      }))
+
+      return true;
+    }
+
+    const $ = new SequentialPty();
+    const resultSuccess = await $.spawnSafe('ls', { interactive: true, cwd: '/tmp' });
+
+    expect(resultSuccess).toMatchObject({
+      status: 'success',
+      exitCode: 0,
+    });
+
+    process.send = originalSend;
+  });
+
+  it('It can work with root (sudo)', async () => {
+    const originalSend = process.send;
+    process.send = (req: IpcMessageV2) => {
+      expect(req).toMatchObject({
+        cmd: MessageCmd.COMMAND_REQUEST,
+        requestId: expect.any(String),
+        data: {
+          command: 'ls',
+          options: {
+            interactive: true,
+            requiresRoot: true,
+          }
+        }
+      })
+
+      // This may look confusing but what we're doing here is directly finding the process listener and calling it without going through serialization
+      const listeners = process.listeners('message');
+      listeners[2](({
+        cmd: MessageCmd.COMMAND_REQUEST,
+        requestId: req.requestId,
+        status: MessageStatus.SUCCESS,
+        data: {
+          status: SpawnStatus.SUCCESS,
+          exitCode: 0,
+          data: 'My data',
+        }
+      }))
+
+      return true;
+    }
+
+    const $ = new SequentialPty();
+    const resultSuccess = await $.spawn('ls', { interactive: true, requiresRoot: true });
+
+    expect(resultSuccess).toMatchObject({
+      status: 'success',
+      exitCode: 0,
+    });
+
+    process.send = originalSend;
+  })
+
+  it('It can handle errors when in sudo', async () => {
+    const originalSend = process.send;
+    process.send = (req: IpcMessageV2) => {
+      expect(req).toMatchObject({
+        cmd: MessageCmd.COMMAND_REQUEST,
+        requestId: expect.any(String),
+        data: {
+          command: 'ls',
+          options: {
+            requiresRoot: true,
+            interactive: true,
+          }
+        }
+      })
+
+      // This may look confusing but what we're doing here is directly finding the process listener and calling it without going through serialization
+      const listeners = process.listeners('message');
+      listeners[2](({
+        cmd: MessageCmd.COMMAND_REQUEST,
+        requestId: req.requestId,
+        status: MessageStatus.SUCCESS,
+        data: {
+          status: SpawnStatus.ERROR,
+          exitCode: 127,
+          data: 'My data',
+        }
+      }))
+
+      return true;
+    }
+
+    const $ = new SequentialPty();
+    const resultSuccess = await $.spawnSafe('ls', { interactive: true, requiresRoot: true });
+
+    expect(resultSuccess).toMatchObject({
+      status: SpawnStatus.ERROR,
+      exitCode: 127,
+    });
+
+    process.send = originalSend;
+  })
+})

package/src/resource/config-parser.ts

@@ -0,0 +1,42 @@
+import { StringIndexedObject } from 'codify-schemas';
+
+import { StatefulParameterController } from '../stateful-parameter/stateful-parameter-controller.js';
+
+export class ConfigParser<T extends StringIndexedObject> {
+  private readonly desiredConfig: Partial<T> | null;
+  private readonly stateConfig: Partial<T> | null;
+  private statefulParametersMap: Map<keyof T, StatefulParameterController<T, T[keyof T]>>;
+
+  constructor(
+    desiredConfig: Partial<T> | null,
+    stateConfig: Partial<T> | null,
+    statefulParameters: Map<keyof T, StatefulParameterController<T, T[keyof T]>>,
+  ) {
+    this.desiredConfig = desiredConfig;
+    this.stateConfig = stateConfig
+    this.statefulParametersMap = statefulParameters;
+  }
+
+  get allParameters(): Partial<T> {
+    return { ...this.desiredConfig, ...this.stateConfig } as Partial<T>;
+  }
+
+  get allNonStatefulParameters(): Partial<T> {
+    const {
+      allParameters,
+      statefulParametersMap,
+    } = this;
+
+    return Object.fromEntries(
+      Object.entries(allParameters).filter(([key]) => !statefulParametersMap.has(key))
+    ) as Partial<T>;
+  }
+
+  get allStatefulParameters(): Partial<T> {
+    const { allParameters, statefulParametersMap } = this;
+
+    return Object.fromEntries(
+      Object.entries(allParameters).filter(([key]) => statefulParametersMap.has(key))
+    ) as Partial<T>;
+  }
+}

package/src/resource/parsed-resource-settings.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'vitest';
+import { ResourceSettings } from './resource-settings.js';
+import { ParsedResourceSettings } from './parsed-resource-settings.js';
+import { TestConfig } from '../utils/test-utils.test.js';
+import { z } from 'zod';
+import { OS } from 'codify-schemas';
+
+describe('Resource options parser tests', () => {
+  it('Parses default values from options', () => {
+    const option: ResourceSettings<TestConfig> = {
+      id: 'typeId',
+      parameterSettings: {
+        propA: { default: 'propA' },
+        propB: { default: 'propB' },
+        propC: { isEqual: () => true },
+        propD: {},
+      }
+    }
+
+    const result = new ParsedResourceSettings(option);
+    expect(result.defaultValues).to.deep.eq({
+      propA: 'propA',
+      propB: 'propB'
+    })
+  })
+
+  it('Throws an error when an import.requiredParameters is not declared', () => {
+    const schema = {
+      '$schema': 'http://json-schema.org/draft-07/schema',
+      '$id': 'https://www.codifycli.com/git-clone.json',
+      'title': 'Git-clone resource',
+      'type': 'object',
+      'properties': {
+        'remote': {
+          'type': 'string',
+          'description': 'Remote tracking url to clone repo from. Equivalent to repository and only one should be specified'
+        },
+        'repository': {
+          'type': 'string',
+          'description': 'Remote repository to clone repo from. Equivalent to remote and only one should be specified'
+        },
+        'parentDirectory': {
+          'type': 'string',
+          'description': 'Parent directory to clone into. The folder name will use default git semantics which extracts the last part of the clone url. Only one of parentDirectory or directory can be specified'
+        },
+        'directory': {
+          'type': 'string',
+          'description': 'Directory to clone contents into. This value is directly passed into git clone. This differs from parent directory in that the last part of the path will be the folder name of the repo'
+        },
+        'autoVerifySSH': {
+          'type': 'boolean',
+          'description': 'Automatically verifies the ssh connection for ssh git clones. Defaults to true.'
+        }
+      },
+      'additionalProperties': false,
+      'oneOf': [
+        { 'required': ['repository', 'directory'] },
+        { 'required': ['repository', 'parentDirectory'] },
+        { 'required': ['remote', 'directory'] }
+      ]
+    }
+
+    const option: ResourceSettings<TestConfig> = {
+      id: 'typeId',
+      schema,
+    }
+
+    expect(() => new ParsedResourceSettings(option)).toThrowError();
+  })
+
+  it('Throws an error when an import.requiredParameters is declared improperly', () => {
+    const schema = {
+      '$schema': 'http://json-schema.org/draft-07/schema',
+      'type': 'object',
+      'properties': {
+        'remote': {
+          'type': 'string',
+        },
+      },
+      'additionalProperties': false,
+    }
+
+    const option: ResourceSettings<TestConfig> = {
+      id: 'typeId',
+      schema,
+      importAndDestroy: {
+        requiredParameters: ['import-error']
+      }
+    }
+
+    expect(() => new ParsedResourceSettings(option)).toThrowError();
+  })
+
+  it('Throws an error when an import.refreshKeys is declared improperly', () => {
+    const schema = {
+      '$schema': 'http://json-schema.org/draft-07/schema',
+      'type': 'object',
+      'properties': {
+        'remote': {
+          'type': 'string',
+        },
+      },
+      'additionalProperties': false,
+    }
+
+    const option: ResourceSettings<TestConfig> = {
+      id: 'typeId',
+      schema,
+      importAndDestroy: {
+        refreshKeys: ['import-error']
+      }
+    }
+
+    expect(() => new ParsedResourceSettings(option)).toThrowError();
+  })
+
+  it('Doesn\'t throw an error when an import.refreshValues is declared properly', () => {
+    const schema = {
+      '$schema': 'http://json-schema.org/draft-07/schema',
+      'type': 'object',
+      'properties': {
+        'remote': {
+          'type': 'string',
+        },
+      },
+      'additionalProperties': false,
+    }
+
+    const option: ResourceSettings<TestConfig> = {
+      id: 'typeId',
+      schema,
+      importAndDestroy: {
+        refreshKeys: ['remote'],
+      }
+    }
+
+    expect(() => new ParsedResourceSettings(option)).not.toThrowError()
+  })
+
+  it('Throws an error if defaultRefreshValue is not found in refreshKeys', () => {
+    const schema = {
+      '$schema': 'http://json-schema.org/draft-07/schema',
+      'type': 'object',
+      'properties': {
+        'remote': {
+          'type': 'string',
+        },
+      },
+      'additionalProperties': false,
+    }
+
+    const option: ResourceSettings<TestConfig> = {
+      id: 'typeId',
+      schema,
+      importAndDestroy: {
+        defaultRefreshValues: {
+          repository: 'abc'
+        }
+      }
+    }
+
+    expect(() => new ParsedResourceSettings(option)).toThrowError()
+  })
+
+  it('Can handle a zod schema', () => {
+
+    const schema = z.object({
+      propA: z.string(),
+      repository: z.string(),
+    })
+
+    const option: ResourceSettings<z.infer<typeof schema>> = {
+      id: 'typeId',
+      operatingSystems: [OS.Darwin],
+      schema,
+      importAndDestroy: {
+        defaultRefreshValues: {
+          repository: 'abc'
+        }
+      }
+    }
+
+    console.log(new ParsedResourceSettings(option))
+
+  })
+})