codify-plugin-lib 1.0.108 → 1.0.110

package/dist/index.d.ts

@@ -4,9 +4,9 @@ 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/index.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/utils.js';
 export declare function runPlugin(plugin: Plugin): Promise<void>;

package/dist/index.js

@@ -4,11 +4,12 @@ export * from './plan/change-set.js';
 export * from './plan/plan.js';
 export * from './plan/plan-types.js';
 export * from './plugin/plugin.js';
+// export * from './utils/utils.js'
+export * from './pty/index.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/utils.js';
 export async function runPlugin(plugin) {
     const messageHandler = new MessageHandler(plugin);
     process.on('message', (message) => messageHandler.onMessage(message));

package/dist/plugin/plugin.d.ts

@@ -2,10 +2,12 @@ import { ApplyRequestData, GetResourceInfoRequestData, GetResourceInfoResponseDa
 import { Plan } from '../plan/plan.js';
 import { Resource } from '../resource/resource.js';
 import { ResourceController } from '../resource/resource-controller.js';
+import { BackgroundPty } from '../pty/background-pty.js';
 export declare class Plugin {
     name: string;
     resourceControllers: Map<string, ResourceController<ResourceConfig>>;
     planStorage: Map<string, Plan<any>>;
+    planPty: BackgroundPty;
     constructor(name: string, resourceControllers: Map<string, ResourceController<ResourceConfig>>);
     static create(name: string, resources: Resource<any>[]): Plugin;
     initialize(): Promise<InitializeResponseData>;

package/dist/plugin/plugin.js

@@ -1,9 +1,12 @@
 import { Plan } from '../plan/plan.js';
 import { ResourceController } from '../resource/resource-controller.js';
+import { ptyLocalStorage } from '../utils/pty-local-storage.js';
+import { BackgroundPty } from '../pty/background-pty.js';
 export class Plugin {
     name;
     resourceControllers;
     planStorage;
+    planPty = new BackgroundPty();
     constructor(name, resourceControllers) {
         this.name = name;
         this.resourceControllers = resourceControllers;
@@ -79,7 +82,9 @@ export class Plugin {
         if (!type || !this.resourceControllers.has(type)) {
             throw new Error(`Resource type not found: ${type}`);
         }
-        const plan = await this.resourceControllers.get(type).plan(data.desired ?? null, data.state ?? null, data.isStateful);
+        const plan = await ptyLocalStorage.run(this.planPty, async () => {
+            return this.resourceControllers.get(type).plan(data.desired ?? null, data.state ?? null, data.isStateful);
+        });
         this.planStorage.set(plan.id, plan);
         return plan.toResponse();
     }

package/dist/pty/background-pty.d.ts

@@ -0,0 +1,19 @@
+import { IPty, SpawnOptions, SpawnResult } from './index.js';
+/**
+ * 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 declare class BackgroundPty implements IPty {
+    private basePty;
+    private promiseQueue;
+    constructor();
+    spawn(cmd: string, options?: SpawnOptions): Promise<SpawnResult>;
+    spawnSafe(cmd: string, options?: SpawnOptions): Promise<SpawnResult>;
+    kill(): Promise<{
+        exitCode: number;
+        signal?: number | undefined;
+    }>;
+    private initialize;
+}

package/dist/pty/background-pty.js

@@ -0,0 +1,119 @@
+import { nanoid } from 'nanoid';
+import * as cp from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import * as fs from 'node:fs/promises';
+import * as net from 'node:net';
+import pty from 'node-pty';
+import stripAnsi from 'strip-ansi';
+import { SpawnError } from './index.js';
+import { PromiseQueue } from './promise-queue.js';
+import { debugLog } from '../utils/debug.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 BackgroundPty {
+    basePty = pty.spawn('zsh', ['-i'], {
+        env: process.env, name: nanoid(6),
+        handleFlowControl: true
+    });
+    promiseQueue = new PromiseQueue();
+    constructor() {
+        this.initialize();
+    }
+    async spawn(cmd, options) {
+        const spawnResult = await this.spawnSafe(cmd, options);
+        if (spawnResult.status !== 'success') {
+            throw new SpawnError(cmd, spawnResult.exitCode, spawnResult.data);
+        }
+        return spawnResult;
+    }
+    async spawnSafe(cmd, options) {
+        // cid is command id
+        const cid = nanoid(10);
+        debugLog(cid);
+        await new Promise((resolve) => {
+            // 600 permissions means only the current user will be able to rw from the FIFO
+            // Create in /tmp so it could be automatically cleaned up if the clean-up was missed
+            const mkfifoSpawn = cp.spawn('mkfifo', ['-m', '600', `/tmp/${cid}`]);
+            mkfifoSpawn.on('close', () => {
+                resolve(null);
+            });
+        });
+        // Use read and write so that the pipe doesn't close
+        const fileHandle = await fs.open(`/tmp/${cid}`, fs.constants.O_RDWR | fs.constants.O_NONBLOCK);
+        let pipe;
+        return new Promise((resolve) => {
+            pipe = new net.Socket({ fd: fileHandle.fd });
+            // pipe.pipe(process.stdout);
+            let output = '';
+            pipe.on('data', (data) => {
+                output += data.toString();
+                if (output.includes('%%%done%%%"')) {
+                    const truncOutput = output.replace('%%%done%%%"\n', '');
+                    const [data, exit] = truncOutput.split('%%%');
+                    // Clean up trailing \n newline if it exists
+                    let strippedData = stripAnsi(data);
+                    if (strippedData.endsWith('\n')) {
+                        strippedData = strippedData.slice(0, -1);
+                    }
+                    resolve({
+                        status: Number.parseInt(exit ?? 1, 10) === 0 ? 'success' : 'error',
+                        exitCode: Number.parseInt(exit ?? 1, 10),
+                        data: strippedData,
+                    });
+                }
+            });
+            this.promiseQueue.run(async () => new Promise((resolve) => {
+                const cdCommand = options?.cwd ? `cd ${options.cwd}; ` : '';
+                // Redirecting everything to the pipe and running in theb background avoids most if not all back-pressure problems
+                // Done is used to denote the end of the command
+                // Use the \\" at the end differentiate between command and response. \\" will evaluate to " in the terminal
+                const command = `((${cdCommand}${cmd}; echo %%%$?%%%done%%%\\") > "/tmp/${cid}" 2>&1 &); echo %%%done%%%${cid}\\";`;
+                let output = '';
+                const listener = this.basePty.onData((data) => {
+                    output += data;
+                    if (output.includes(`%%%done%%%${cid}"`)) {
+                        listener.dispose();
+                        resolve(null);
+                    }
+                });
+                // console.log(`Running command ${cmd}`)
+                this.basePty.write(`${command}\r`);
+            }));
+        }).finally(async () => {
+            // console.log('finally');
+            // await fileHandle?.close();
+            await fs.rm(`/tmp/${cid}`);
+        });
+    }
+    async kill() {
+        return new Promise((resolve) => {
+            this.basePty.onExit((status) => {
+                resolve(status);
+            });
+            this.basePty.kill();
+        });
+    }
+    async initialize() {
+        // this.basePty.onData((data: string) => process.stdout.write(data));
+        await this.promiseQueue.run(async () => {
+            let outputBuffer = '';
+            return new Promise(resolve => {
+                this.basePty.write('unset PS1;\n');
+                this.basePty.write('unset PS0;\n');
+                this.basePty.write('echo setup complete\\"\n');
+                const listener = this.basePty.onData((data) => {
+                    outputBuffer += data;
+                    if (outputBuffer.includes('setup complete"')) {
+                        listener.dispose();
+                        resolve(null);
+                    }
+                });
+            });
+        });
+    }
+}

package/dist/pty/index.d.ts

@@ -0,0 +1,24 @@
+export interface SpawnResult {
+    status: 'success' | 'error';
+    exitCode: number;
+    data: string;
+}
+export interface SpawnOptions {
+    cwd?: string;
+    env?: Record<string, unknown>;
+}
+export declare class SpawnError extends Error {
+    data: string;
+    cmd: string;
+    exitCode: number;
+    constructor(cmd: string, exitCode: number, data: string);
+}
+export interface IPty {
+    spawn(cmd: string, options?: SpawnOptions): Promise<SpawnResult>;
+    spawnSafe(cmd: string, options?: SpawnOptions): Promise<SpawnResult>;
+    kill(): Promise<{
+        exitCode: number;
+        signal?: number | undefined;
+    }>;
+}
+export declare function getPty(): IPty;

package/dist/pty/index.js

@@ -0,0 +1,15 @@
+import { ptyLocalStorage } from '../utils/pty-local-storage.js';
+export class SpawnError extends Error {
+    data;
+    cmd;
+    exitCode;
+    constructor(cmd, exitCode, data) {
+        super(`Spawn Error: on command "${cmd}" with exit code: ${exitCode}\nOutput:\n${data}`);
+        this.data = data;
+        this.cmd = cmd;
+        this.exitCode = exitCode;
+    }
+}
+export function getPty() {
+    return ptyLocalStorage.getStore();
+}

package/dist/pty/promise-queue.d.ts

@@ -0,0 +1,5 @@
+export declare class PromiseQueue {
+    private queue;
+    private eventBus;
+    run<T>(fn: () => Promise<T> | T): Promise<T>;
+}

package/dist/pty/promise-queue.js

@@ -0,0 +1,26 @@
+import { nanoid } from 'nanoid';
+import EventEmitter from 'node:events';
+export class PromiseQueue {
+    // Cid stands for command id;
+    queue = [];
+    eventBus = new EventEmitter();
+    async run(fn) {
+        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/dist/pty/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/dist/pty/vitest.config.js

@@ -0,0 +1,11 @@
+import { defaultExclude, defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        pool: 'forks',
+        fileParallelism: false,
+        exclude: [
+            ...defaultExclude,
+            './src/utils/test-utils.test.ts',
+        ]
+    },
+});

package/dist/resource/resource-controller.js

@@ -263,13 +263,13 @@ ${JSON.stringify(refresh, null, 2)}
         const result = {};
         const sortedEntries = Object.entries(statefulParametersConfig)
             .sort(([key1], [key2]) => this.parsedSettings.statefulParameterOrder.get(key1) - this.parsedSettings.statefulParameterOrder.get(key2));
-        for (const [key, desiredValue] of sortedEntries) {
+        await Promise.all(sortedEntries.map(async ([key, desiredValue]) => {
             const statefulParameter = this.parsedSettings.statefulParameters.get(key);
             if (!statefulParameter) {
                 throw new Error(`Stateful parameter ${key} was not found`);
             }
             result[key] = await statefulParameter.refresh(desiredValue ?? null, allParameters);
-        }
+        }));
         return result;
     }
     validatePlanInputs(desired, current, statefulMode) {

package/dist/utils/debug.d.ts

@@ -0,0 +1,2 @@
+export declare function debugLog(message: any): void;
+export declare function debugWrite(message: any): void;

package/dist/utils/debug.js

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

package/dist/utils/pty-local-storage.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="node" resolution-mode="require"/>
+import { AsyncLocalStorage } from 'node:async_hooks';
+export declare const ptyLocalStorage: AsyncLocalStorage<unknown>;

package/dist/utils/pty-local-storage.js

@@ -0,0 +1,2 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+export const ptyLocalStorage = new AsyncLocalStorage();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codify-plugin-lib",
-  "version": "1.0.108",
+  "version": "1.0.110",
   "description": "Library plugin library",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -17,7 +17,10 @@
     "codify-schemas": "1.0.53",
     "@npmcli/promise-spawn": "^7.0.1",
     "uuid": "^10.0.0",
-    "lodash.isequal": "^4.5.0"
+    "lodash.isequal": "^4.5.0",
+    "nanoid": "^5.0.9",
+    "node-pty": "^1.0.0",
+    "strip-ansi": "^7.1.0"
   },
   "devDependencies": {
     "@oclif/prettier-config": "^0.2.1",

package/src/index.ts

@@ -6,11 +6,12 @@ export * from './plan/change-set.js'
 export * from './plan/plan.js'
 export * from './plan/plan-types.js'
 export * from './plugin/plugin.js'
+// export * from './utils/utils.js'
+export * from './pty/index.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/utils.js'
 
 export async function runPlugin(plugin: Plugin) {
   const messageHandler = new MessageHandler(plugin);

package/src/plugin/plugin.ts

@@ -16,9 +16,12 @@ import {
 import { Plan } from '../plan/plan.js';
 import { Resource } from '../resource/resource.js';
 import { ResourceController } from '../resource/resource-controller.js';
+import { ptyLocalStorage } from '../utils/pty-local-storage.js';
+import { BackgroundPty } from '../pty/background-pty.js';
 
 export class Plugin {
   planStorage: Map<string, Plan<any>>;
+  planPty = new BackgroundPty();
 
   constructor(
     public name: string,
@@ -119,11 +122,14 @@ export class Plugin {
       throw new Error(`Resource type not found: ${type}`);
     }
 
-    const plan = await this.resourceControllers.get(type)!.plan(
-      data.desired ?? null,
-      data.state ?? null,
-      data.isStateful
-    );
+    const plan = await ptyLocalStorage.run(this.planPty, async () => {
+       return this.resourceControllers.get(type)!.plan(
+        data.desired ?? null,
+        data.state ?? null,
+        data.isStateful
+      );
+    })
+
     this.planStorage.set(plan.id, plan);
 
     return plan.toResponse();

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

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { BackgroundPty } from './background-pty.js';
+
+describe('BackgroundPty tests', () => {
+  it('Can launch a simple command', async () => {
+    const pty = new BackgroundPty();
+
+    const result = await pty.spawnSafe('ls');
+    expect(result).toMatchObject({
+      status: 'success',
+      exitCode: 0,
+    })
+
+
+    const exitCode = await pty.kill();
+    expect(exitCode).toMatchObject({
+      exitCode: 1,
+      signal: 0,
+    });
+  })
+
+  it('Can launch 100 commands in parallel', { timeout: 15000 }, async () => {
+    const pty = new BackgroundPty();
+
+    const fn = async () => pty.spawnSafe('ls');
+
+    const results = await Promise.all(
+      Array.from({ length: 100 }, (_, i) => i + 1)
+        .map(() => fn())
+    )
+
+    expect(results.length).to.eq(100);
+    expect(results.every((r) => r.exitCode === 0))
+
+    await pty.kill();
+  })
+
+  it('Reports back the correct exit code and status', async () => {
+    const pty = new BackgroundPty();
+
+    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.
+    })
+
+    await pty.kill();
+  });
+
+  it('Can use a different cwd', async () => {
+    const pty = new BackgroundPty();
+
+    const resultSuccess = await pty.spawnSafe('pwd', { cwd: '/tmp' });
+    expect(resultSuccess).toMatchObject({
+      status: 'success',
+      exitCode: 0,
+      data: '/tmp'
+    })
+
+    await pty.kill();
+  });
+})

package/src/pty/background-pty.ts

@@ -0,0 +1,147 @@
+import { nanoid } from 'nanoid';
+import * as cp from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import * as fs from 'node:fs/promises';
+import * as net from 'node:net';
+import pty from 'node-pty';
+import stripAnsi from 'strip-ansi';
+
+import { IPty, SpawnError, SpawnOptions, SpawnResult } from './index.js';
+import { PromiseQueue } from './promise-queue.js';
+import { debugLog } from '../utils/debug.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 BackgroundPty implements IPty {
+  private basePty = pty.spawn('zsh', ['-i'], {
+    env: process.env, name: nanoid(6),
+    handleFlowControl: true
+  });
+
+  private promiseQueue = new PromiseQueue();
+
+  constructor() {
+    this.initialize();
+  }
+
+  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> {
+    // cid is command id
+    const cid = nanoid(10);
+    debugLog(cid);
+
+    await new Promise((resolve) => {
+      // 600 permissions means only the current user will be able to rw from the FIFO
+      // Create in /tmp so it could be automatically cleaned up if the clean-up was missed
+      const mkfifoSpawn = cp.spawn('mkfifo', ['-m', '600', `/tmp/${cid}`]);
+      mkfifoSpawn.on('close', () => {
+        resolve(null);
+      })
+    })
+
+    // Use read and write so that the pipe doesn't close
+    const fileHandle = await fs.open(`/tmp/${cid}`, fs.constants.O_RDWR | fs.constants.O_NONBLOCK);
+    let pipe: net.Socket;
+
+    return new Promise<SpawnResult>((resolve) => {
+      pipe = new net.Socket({ fd: fileHandle.fd });
+
+      // pipe.pipe(process.stdout);
+
+      let output = '';
+      pipe.on('data', (data) => {
+        output += data.toString();
+
+        if (output.includes('%%%done%%%"')) {
+          const truncOutput = output.replace('%%%done%%%"\n', '');
+          const [data, exit] = truncOutput.split('%%%');
+
+          // Clean up trailing \n newline if it exists
+          let strippedData = stripAnsi(data);
+          if (strippedData.endsWith('\n')) {
+            strippedData = strippedData.slice(0, -1);
+          }
+
+          resolve(<SpawnResult>{
+            status: Number.parseInt(exit ?? 1, 10) === 0 ? 'success' : 'error',
+            exitCode: Number.parseInt(exit ?? 1, 10),
+            data: strippedData,
+          });
+        }
+      })
+
+      this.promiseQueue.run(async () => new Promise((resolve) => {
+        const cdCommand = options?.cwd ? `cd ${options.cwd}; ` : '';
+        // Redirecting everything to the pipe and running in theb background avoids most if not all back-pressure problems
+        // Done is used to denote the end of the command
+        // Use the \\" at the end differentiate between command and response. \\" will evaluate to " in the terminal
+        const command = `((${cdCommand}${cmd}; echo %%%$?%%%done%%%\\") > "/tmp/${cid}" 2>&1 &); echo %%%done%%%${cid}\\";`
+
+        let output = '';
+        const listener = this.basePty.onData((data: any) => {
+          output += data;
+
+          if (output.includes(`%%%done%%%${cid}"`)) {
+            listener.dispose();
+            resolve(null);
+          }
+        });
+
+        // console.log(`Running command ${cmd}`)
+        this.basePty.write(`${command}\r`);
+
+      }));
+    }).finally(async () => {
+      // console.log('finally');
+      // await fileHandle?.close();
+      await fs.rm(`/tmp/${cid}`);
+    })
+  }
+
+  async kill(): Promise<{ exitCode: number, signal?: number | undefined }> {
+    return new Promise((resolve) => {
+      this.basePty.onExit((status) => {
+        resolve(status);
+      })
+
+      this.basePty.kill()
+    })
+  }
+
+  private async initialize() {
+    // this.basePty.onData((data: string) => process.stdout.write(data));
+
+    await this.promiseQueue.run(async () => {
+      let outputBuffer = '';
+
+      return new Promise(resolve => {
+        this.basePty.write('unset PS1;\n');
+        this.basePty.write('unset PS0;\n')
+        this.basePty.write('echo setup complete\\"\n')
+
+        const listener = this.basePty.onData((data: string) => {
+          outputBuffer += data;
+          if (outputBuffer.includes('setup complete"')) {
+            listener.dispose();
+            resolve(null);
+          }
+        })
+      })
+    })
+  }
+}

package/src/pty/index.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it, vitest } from 'vitest';
+import { TestConfig, TestResource } from '../utils/test-utils.test.js';
+import { getPty, IPty } from './index.js';
+import { Plugin } from '../plugin/plugin.js'
+import { CreatePlan } from '../plan/plan-types.js';
+import { ResourceOperation } from 'codify-schemas';
+import { ResourceSettings } from '../resource/resource-settings.js';
+
+describe('General tests for PTYs', () => {
+  it('Can get pty within refresh', async () => {
+    const testResource = new class extends TestResource {
+      async refresh(): Promise<Partial<TestConfig> | null> {
+        const $ = getPty();
+        const lsResult = await $.spawnSafe('ls');
+
+        expect(lsResult.exitCode).to.eq(0);
+        expect(lsResult.data).to.be.not.null;
+        expect(lsResult.status).to.eq('success');
+
+        return {};
+      }
+    }
+
+    const spy = vitest.spyOn(testResource, 'refresh')
+
+    const plugin = Plugin.create('test plugin', [testResource])
+    const plan = await plugin.plan({
+      desired: {
+        type: 'type'
+      },
+      state: undefined,
+      isStateful: false,
+    })
+
+    expect(plan).toMatchObject({
+      operation: 'noop',
+      resourceType: 'type',
+    })
+    expect(spy).toHaveBeenCalledOnce()
+  })
+
+  it('The same pty instance is shared cross multiple resources', async () => {
+    let pty1: IPty;
+    let pty2: IPty;
+
+    const testResource1 = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'type1'
+        }
+      }
+
+      async refresh(): Promise<Partial<TestConfig> | null> {
+        const $ = getPty();
+        const lsResult = await $.spawnSafe('ls');
+
+        expect(lsResult.exitCode).to.eq(0);
+        pty1 = $;
+
+        return {};
+      }
+    }
+
+    const testResource2 = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'type2',
+        }
+      }
+
+      async refresh(): Promise<Partial<TestConfig> | null> {
+        const $ = getPty();
+        const pwdResult = await $.spawnSafe('pwd');
+
+        expect(pwdResult.exitCode).to.eq(0);
+        pty2 = $;
+
+        return {};
+      }
+    }
+
+    const spy1 = vitest.spyOn(testResource1, 'refresh')
+    const spy2 = vitest.spyOn(testResource2, 'refresh')
+
+    const plugin = Plugin.create('test plugin', [testResource1, testResource2]);
+    await plugin.plan({
+      desired: {
+        type: 'type1'
+      },
+      state: undefined,
+      isStateful: false,
+    })
+
+    await plugin.plan({
+      desired: {
+        type: 'type2'
+      },
+      state: undefined,
+      isStateful: false,
+    })
+
+    expect(spy1).toHaveBeenCalledOnce();
+    expect(spy2).toHaveBeenCalledOnce();
+
+    // The main check here is that the refresh method for both are sharing the same pty instance.
+    expect(pty1).to.eq(pty2);
+  })
+
+  it('Currently pty not available for apply', async () => {
+    const testResource = new class extends TestResource {
+      create(plan: CreatePlan<TestConfig>): Promise<void> {
+        const $ = getPty();
+        expect($).to.be.undefined;
+      }
+    }
+
+    const spy = vitest.spyOn(testResource, 'create')
+
+    const plugin = Plugin.create('test plugin', [testResource])
+    await plugin.apply({
+      plan: {
+        operation: ResourceOperation.CREATE,
+        resourceType: 'type',
+        parameters: [],
+      }
+    })
+    expect(spy).toHaveBeenCalledOnce()
+  })
+})

package/src/pty/index.ts

@@ -0,0 +1,39 @@
+import { ptyLocalStorage } from '../utils/pty-local-storage.js';
+
+export interface SpawnResult {
+  status: 'success' | 'error';
+  exitCode: number;
+  data: string;
+}
+
+export interface SpawnOptions {
+  cwd?: string;
+  env?: Record<string, unknown>,
+}
+
+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, options?: SpawnOptions): Promise<SpawnResult>
+
+  spawnSafe(cmd: 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/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defaultExclude, defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    pool: 'forks',
+    fileParallelism: false,
+    exclude: [
+      ...defaultExclude,
+      './src/utils/test-utils.test.ts',
+    ]
+  },
+});

package/src/resource/resource-controller.ts

@@ -362,14 +362,14 @@ ${JSON.stringify(refresh, null, 2)}
         ([key1], [key2]) => this.parsedSettings.statefulParameterOrder.get(key1)! - this.parsedSettings.statefulParameterOrder.get(key2)!
       )
 
-    for (const [key, desiredValue] of sortedEntries) {
+    await Promise.all(sortedEntries.map(async ([key, desiredValue]) => {
       const statefulParameter = this.parsedSettings.statefulParameters.get(key);
       if (!statefulParameter) {
         throw new Error(`Stateful parameter ${key} was not found`);
       }
 
       (result as Record<string, unknown>)[key] = await statefulParameter.refresh(desiredValue ?? null, allParameters)
-    }
+    }))
 
     return result;
   }

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/pty-local-storage.ts

@@ -0,0 +1,3 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export const ptyLocalStorage = new AsyncLocalStorage();

package/tsconfig.json

@@ -20,6 +20,7 @@
   ],
   "exclude": [
     "node_modules",
-    "src/**/*.test.ts"
+    "src/**/*.test.ts",
+    "**/vitest.config.ts"
   ]
 }

package/vitest.config.ts

@@ -4,7 +4,8 @@ export default defineConfig({
   test: {
     exclude: [
       ...defaultExclude,
-      './src/utils/test-utils.test.ts'
+      './src/utils/test-utils.test.ts',
+      './src/pty/*'
     ]
   },
 });