feat: Added unified way to run command in plugins (similar to plan)

Author: kevinwang5658

src/plugin/plugin.ts

@@ -21,10 +21,11 @@ import { ApplyValidationError } from '../common/errors.js';
 import { Plan } from '../plan/plan.js';
 import { BackgroundPty } from '../pty/background-pty.js';
 import { getPty } from '../pty/index.js';
+import { SequentialPty } from '../pty/seqeuntial-pty.js';
 import { Resource } from '../resource/resource.js';
 import { ResourceController } from '../resource/resource-controller.js';
-import { ptyLocalStorage } from '../utils/pty-local-storage.js';
 import { VerbosityLevel } from '../utils/internal-utils.js';
+import { ptyLocalStorage } from '../utils/pty-local-storage.js';
 
 export class Plugin {
   planStorage: Map<string, Plan<any>>;
@@ -232,7 +233,7 @@ export class Plugin {
       throw new Error('Malformed plan with resource that cannot be found');
     }
 
-    await resource.apply(plan);
+    await ptyLocalStorage.run(new SequentialPty(), async () => resource.apply(plan))
 
     // Validate using desired/desired. If the apply was successful, no changes should be reported back.
     // Default back desired back to current if it is not defined (for destroys only)

src/pty/index.ts

@@ -1,7 +1,7 @@
 import { ptyLocalStorage } from '../utils/pty-local-storage.js';
 
 export interface SpawnResult {
-  status: 'success' | 'error';
+  status: 'error' | 'success';
   exitCode: number;
   data: string;
 }
@@ -11,9 +11,25 @@ export enum SpawnStatus {
   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.
+ */
 export interface SpawnOptions {
   cwd?: string;
   env?: Record<string, unknown>,
+  interactive?: boolean,
 }
 
 export class SpawnError extends Error {

src/pty/seqeuntial-pty.ts

@@ -0,0 +1,105 @@
+import pty from '@homebridge/node-pty-prebuilt-multiarch';
+import { EventEmitter } from 'node:events';
+import stripAnsi from 'strip-ansi';
+
+import { Shell, Utils } from '../utils/index.js';
+import { VerbosityLevel } from '../utils/internal-utils.js';
+import { IPty, SpawnError, SpawnOptions, SpawnResult, SpawnStatus } from './index.js';
+
+EventEmitter.defaultMaxListeners = 1000;
+
+/**
+ * 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, options?: SpawnOptions): Promise<SpawnResult> {
+    const spawnResult = await this.spawnSafe(cmd, options);
+
+    if (spawnResult.status !== 'success') {
+      throw new SpawnError(cmd, spawnResult.exitCode, spawnResult.data);
+    }
+
+    return spawnResult;
+  }
+
+  async spawnSafe(cmd: string, options?: SpawnOptions): Promise<SpawnResult> {
+    console.log(`Running command: ${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
+      const initialCols = process.stdout.columns ?? 80;
+      const initialRows = process.stdout.rows ?? 24;
+
+      const args = (options?.interactive ?? true) ? ['-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 stdinListener = (data) => {
+        mPty.write(data.toString());
+      };
+
+      const resizeListener = () => {
+        const { columns, rows } = process.stdout;
+        mPty.resize(columns, rows);
+      }
+
+      // Listen to resize events for the terminal window;
+      process.stdout.on('resize', resizeListener);
+      // Listen for user input
+      process.stdin.on('data', stdinListener);
+
+      mPty.onExit((result) => {
+        process.stdout.off('resize', resizeListener);
+        process.stdin.off('data', stdinListener);
+
+        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,
+    }
+  }
+
+  private getDefaultShell(): string {
+    return process.env.SHELL!;
+  }
+}

src/pty/sequential-pty.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { SequentialPty } from './seqeuntial-pty.js';
+import { VerbosityLevel } from '../utils/internal-utils.js';
+
+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: 127,
+      data: 'zsh:1: command not found: which sjkdhsakjdhjkash' // 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('It can launch a command in interactive mode', async () => {
+    const pty = new SequentialPty();
+
+    const resultSuccess = await pty.spawnSafe('ls', { interactive: false });
+    expect(resultSuccess).toMatchObject({
+      status: 'success',
+      exitCode: 0,
+    })
+  });
+})