@codifycli/plugin-core 1.1.0-beta9 → 1.2.0

package/.claude/settings.local.json

@@ -1,5 +1,13 @@
 {
+  "permissions": {
+    "allow": [
+      "Bash(grep -r \"COMMAND_REQUEST\\\\|PRESS_KEY_TO_CONTINUE_REQUEST\\\\|CODIFY_CREDENTIALS_REQUEST\" /Users/kevinwang/Projects/codify-parent/codify/src --include=\"*.ts\" ! -name \"*.test.ts\")",
+      "Read(//Users/kevinwang/Projects/codify-parent/codify-schemas/**)",
+      "Bash(npm run *)"
+    ]
+  },
   "disabledMcpjsonServers": [
-    "supabase"
+    "supabase",
+    "codify"
   ]
 }

package/dist/common/apply-notes.d.ts

@@ -0,0 +1,5 @@
+export declare const ApplyNotes: {
+    readonly RESTART_REQUIRED: "A system restart is required for changes to take effect.";
+    readonly NEW_SHELL_REQUIRED: "Open a new terminal session for the changes to be reflected.";
+    readonly sourceShellRc: () => string;
+};

package/dist/common/apply-notes.js

@@ -0,0 +1,10 @@
+import path from 'node:path';
+import { Utils } from '../utils/index.js';
+export const ApplyNotes = {
+    RESTART_REQUIRED: 'A system restart is required for changes to take effect.',
+    NEW_SHELL_REQUIRED: 'Open a new terminal session for the changes to be reflected.',
+    sourceShellRc() {
+        const rc = path.basename(Utils.getPrimaryShellRc());
+        return `Source '~/${rc}' for the changes to be reflected.`;
+    },
+};

package/dist/common/errors.d.ts

@@ -3,6 +3,7 @@ export declare class ApplyValidationError extends Error {
     resourceType: string;
     resourceName?: string;
     plan: Plan<any>;
-    constructor(plan: Plan<any>);
+    logs: string[];
+    constructor(plan: Plan<any>, logs?: string[]);
     private static prettyPrintPlan;
 }

package/dist/common/errors.js

@@ -2,11 +2,13 @@ export class ApplyValidationError extends Error {
     resourceType;
     resourceName;
     plan;
-    constructor(plan) {
+    logs;
+    constructor(plan, logs = []) {
         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;
+        this.logs = logs;
     }
     static prettyPrintPlan(plan) {
         const { operation, parameters } = plan.toResponse();

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Plugin } from './plugin/plugin.js';
+export * from './common/apply-notes.js';
 export * from './errors.js';
 export * from './messages/sender.js';
 export * from './plan/change-set.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 import { MessageHandler } from './messages/handlers.js';
+export * from './common/apply-notes.js';
 export * from './errors.js';
 export * from './messages/sender.js';
 export * from './plan/change-set.js';

package/dist/messages/handlers.js

@@ -1,6 +1,7 @@
 import { ApplyRequestDataSchema, EmptyResponseDataSchema, GetResourceInfoRequestDataSchema, GetResourceInfoResponseDataSchema, ImportRequestDataSchema, ImportResponseDataSchema, InitializeRequestDataSchema, InitializeResponseDataSchema, IpcMessageSchema, IpcMessageV2Schema, MatchRequestDataSchema, MatchResponseDataSchema, MessageStatus, PlanRequestDataSchema, PlanResponseDataSchema, ResourceSchema, SetVerbosityRequestDataSchema, ValidateRequestDataSchema, ValidateResponseDataSchema } from '@codifycli/schemas';
 import { Ajv } from 'ajv';
 import addFormats from 'ajv-formats';
+import { ApplyValidationError } from '../common/errors.js';
 import { SudoError } from '../errors.js';
 const SupportedRequests = {
     'initialize': {
@@ -113,22 +114,30 @@ export class MessageHandler {
         }
         // @ts-expect-error TS2239
         const cmd = message.cmd + '_Response';
+        // @ts-expect-error TS2239
+        const requestId = message.requestId || undefined;
+        let errorPayload;
         if (e instanceof SudoError) {
-            return process.send?.({
-                cmd,
-                // @ts-expect-error TS2239
-                requestId: message.requestId || undefined,
-                data: `Plugin: '${this.plugin.name}'. Forbidden usage of sudo for command '${e.command}'. Please contact the plugin developer to fix this.`,
-                status: MessageStatus.ERROR,
-            });
+            errorPayload = {
+                errorType: 'sudo_error',
+                message: `Plugin: '${this.plugin.name}'. Forbidden usage of sudo for command '${e.command}'. Please contact the plugin developer to fix this.`,
+                data: { command: e.command, pluginName: this.plugin.name },
+            };
+        }
+        else if (e instanceof ApplyValidationError) {
+            errorPayload = {
+                errorType: 'apply_validation',
+                message: e.message,
+                data: { plan: e.plan.toResponse(), logs: e.logs },
+            };
+        }
+        else {
+            const isDebug = process.env.DEBUG?.includes('*') ?? false;
+            errorPayload = {
+                errorType: 'unknown',
+                message: isDebug ? (e.stack ?? e.message) : e.message,
+            };
         }
-        const isDebug = process.env.DEBUG?.includes('*') ?? false;
-        process.send?.({
-            cmd,
-            // @ts-expect-error TS2239
-            requestId: message.requestId || undefined,
-            data: isDebug ? e.stack : e.message,
-            status: MessageStatus.ERROR,
-        });
+        process.send?.({ cmd, requestId, data: errorPayload, status: MessageStatus.ERROR });
     }
 }

package/dist/messages/sender.d.ts

@@ -4,6 +4,7 @@
 declare class CodifyCliSenderImpl {
     private readonly validateIpcMessageV2;
     requestPressKeyToContinuePrompt(message?: string): Promise<void>;
+    sendApplyNote(message: string, resourceType?: string): Promise<void>;
     getCodifyCliCredentials(): Promise<string>;
     private sendAndWaitForResponse;
 }

package/dist/messages/sender.js

@@ -17,6 +17,18 @@ class CodifyCliSenderImpl {
             }
         });
     }
+    async sendApplyNote(message, resourceType) {
+        if (!process.send || !process.connected) {
+            return;
+        }
+        await this.sendAndWaitForResponse({
+            cmd: MessageCmd.APPLY_NOTE_REQUEST,
+            data: {
+                message,
+                ...(resourceType && { resourceType }),
+            }
+        });
+    }
     async getCodifyCliCredentials() {
         const data = await this.sendAndWaitForResponse({
             cmd: MessageCmd.CODIFY_CREDENTIALS_REQUEST,

package/dist/plan/change-set.js

@@ -48,6 +48,7 @@ export class ChangeSet {
     }
     static destroy(current, settings) {
         const parameterChanges = Object.entries(current)
+            .filter(([k]) => !settings?.parameterSettings?.[k]?.setting)
             .map(([k, v]) => ({
             name: k,
             operation: ParameterOperation.REMOVE,

package/dist/plugin/plugin.d.ts

@@ -8,8 +8,13 @@ export declare class Plugin {
     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;
+    minSupportedCliVersion: string | undefined;
+    constructor(name: string, resourceControllers: Map<string, ResourceController<ResourceConfig>>, options?: {
+        minSupportedCliVersion?: string;
+    });
+    static create(name: string, resources: Resource<any>[], options?: {
+        minSupportedCliVersion?: string;
+    }): Plugin;
     initialize(data: InitializeRequestData): Promise<InitializeResponseData>;
     getResourceInfo(data: GetResourceInfoRequestData): GetResourceInfoResponseData;
     match(data: MatchRequestData): Promise<MatchResponseData>;

package/dist/plugin/plugin.js

@@ -11,16 +11,18 @@ export class Plugin {
     resourceControllers;
     planStorage;
     planPty = new BackgroundPty();
-    constructor(name, resourceControllers) {
+    minSupportedCliVersion;
+    constructor(name, resourceControllers, options) {
         this.name = name;
         this.resourceControllers = resourceControllers;
         this.planStorage = new Map();
+        this.minSupportedCliVersion = options?.minSupportedCliVersion;
     }
-    static create(name, resources) {
+    static create(name, resources, options) {
         const controllers = resources
             .map((resource) => new ResourceController(resource));
         const controllersMap = new Map(controllers.map((r) => [r.typeId, r]));
-        return new Plugin(name, controllersMap);
+        return new Plugin(name, controllersMap, options);
     }
     async initialize(data) {
         if (data.verbosityLevel) {
@@ -30,6 +32,7 @@ export class Plugin {
             await controller.initialize();
         }
         return {
+            minSupportedCliVersion: this.minSupportedCliVersion,
             resourceDefinitions: [...this.resourceControllers.values()]
                 .map((r) => {
                 const sensitiveParameters = Object.entries(r.settings.parameterSettings ?? {})
@@ -121,9 +124,9 @@ export class Plugin {
             if (!this.resourceControllers.has(core.type)) {
                 throw new Error(`Resource type not found: ${core.type}`);
             }
-            const validation = await this.resourceControllers
+            const validation = await ptyLocalStorage.run(this.planPty, () => this.resourceControllers
                 .get(core.type)
-                .validate(core, parameters);
+                .validate(core, parameters));
             validationResults.push(validation);
         }
         // Validate that if allow multiple is false, then only 1 of each resource exists
@@ -165,7 +168,11 @@ export class Plugin {
         if (!resource) {
             throw new Error('Malformed plan with resource that cannot be found');
         }
-        await ptyLocalStorage.run(new SequentialPty(), async () => resource.apply(plan));
+        let applyLogs = [];
+        await ptyLocalStorage.run(new SequentialPty(), async () => {
+            await resource.apply(plan);
+            applyLogs = getPty().getLogs();
+        });
         // 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)
         const validationPlan = await ptyLocalStorage.run(new BackgroundPty(), async () => {
@@ -174,7 +181,7 @@ export class Plugin {
             return result;
         });
         if (validationPlan.requiresChanges()) {
-            throw new ApplyValidationError(plan);
+            throw new ApplyValidationError(validationPlan, applyLogs);
         }
     }
     async setVerbosityLevel(data) {

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

@@ -17,5 +17,6 @@ export declare class BackgroundPty implements IPty {
         signal?: number | undefined;
     }>;
     private initialize;
+    getLogs(): string[];
     private getDefaultShell;
 }

package/dist/pty/background-pty.js

@@ -121,6 +121,9 @@ export class BackgroundPty {
             });
         });
     }
+    getLogs() {
+        return [];
+    }
     getDefaultShell() {
         return process.env.SHELL;
     }

package/dist/pty/index.d.ts

@@ -30,6 +30,7 @@ export interface SpawnOptions {
     env?: Record<string, unknown>;
     interactive?: boolean;
     requiresRoot?: boolean;
+    requiresSudoAskpass?: boolean;
     stdin?: boolean;
     disableWrapping?: boolean;
 }
@@ -37,7 +38,7 @@ export declare class SpawnError extends Error {
     data: string;
     cmd: string;
     exitCode: number;
-    constructor(cmd: string, exitCode: number, data: string);
+    constructor(cmd: string, exitCode: number, data: string, logs?: string[]);
 }
 export interface IPty {
     spawn(cmd: string | string[], options?: SpawnOptions): Promise<SpawnResult>;
@@ -46,5 +47,6 @@ export interface IPty {
         exitCode: number;
         signal?: number | undefined;
     }>;
+    getLogs(): string[];
 }
 export declare function getPty(): IPty;

package/dist/pty/index.js

@@ -8,8 +8,11 @@ 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}`);
+    constructor(cmd, exitCode, data, logs) {
+        const logSection = logs?.length
+            ? `\nLast logs:\n${logs.join('\n')}`
+            : '';
+        super(`Spawn Error: on command "${cmd}" with exit code: ${exitCode}\nOutput:\n${data}${logSection}`);
         this.data = data;
         this.cmd = cmd;
         this.exitCode = exitCode;

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

@@ -6,6 +6,10 @@ import { IPty, SpawnOptions, SpawnResult } from './index.js';
  * without a tty (or even a stdin) attached so interactive commands will not work.
  */
 export declare class SequentialPty implements IPty {
+    private logBuffer;
+    private static readonly MAX_LOG_LINES;
+    getLogs(): string[];
+    private appendLog;
     spawn(cmd: string | string[], options?: SpawnOptions): Promise<SpawnResult>;
     spawnSafe(cmd: string | string[], options?: SpawnOptions): Promise<SpawnResult>;
     kill(): Promise<{

package/dist/pty/seqeuntial-pty.js

@@ -19,10 +19,22 @@ const validateSudoRequestResponse = ajv.compile(CommandRequestResponseDataSchema
  * without a tty (or even a stdin) attached so interactive commands will not work.
  */
 export class SequentialPty {
+    logBuffer = [];
+    static MAX_LOG_LINES = 30;
+    getLogs() {
+        return [...this.logBuffer];
+    }
+    appendLog(data) {
+        const lines = data.split('\n');
+        this.logBuffer.push(...lines);
+        if (this.logBuffer.length > SequentialPty.MAX_LOG_LINES) {
+            this.logBuffer = this.logBuffer.slice(-SequentialPty.MAX_LOG_LINES);
+        }
+    }
     async spawn(cmd, options) {
         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);
+            throw new SpawnError(Array.isArray(cmd) ? cmd.join('\n') : cmd, spawnResult.exitCode, spawnResult.data, this.logBuffer);
         }
         return spawnResult;
     }
@@ -32,10 +44,12 @@ export class SequentialPty {
             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) {
+        if (options?.stdin || options?.requiresRoot || options?.requiresSudoAskpass) {
             return this.externalSpawn(cmd, options);
         }
-        console.log(`Running command: ${Array.isArray(cmd) ? cmd.join('\\\n') : cmd}` + (options?.cwd ? `(${options?.cwd})` : ''));
+        const cmdLine = `Running command: ${Array.isArray(cmd) ? cmd.join('\\\n') : cmd}` + (options?.cwd ? `(${options?.cwd})` : '');
+        console.log(cmdLine);
+        this.appendLog(cmdLine);
         return new Promise((resolve) => {
             const output = [];
             const historyIgnore = Utils.getShell() === Shell.ZSH ? { HISTORY_IGNORE: '*' } : { HISTIGNORE: '*' };
@@ -65,6 +79,7 @@ export class SequentialPty {
                     process.stdout.write(data);
                 }
                 output.push(data.toString());
+                this.appendLog(data.toString());
             });
             const resizeListener = () => {
                 const { columns, rows } = process.stdout;

package/dist/resource/parsed-resource-settings.js

@@ -28,7 +28,7 @@ export class ParsedResourceSettings {
                         if (ctx.path.length === 0) {
                             ctx.jsonSchema.title = settings.id;
                             ctx.jsonSchema.description = schema.description ?? settings.description ?? `${settings.id} resource. Can be used to manage ${settings.id}`;
-                            ctx.jsonSchema.$comment = schema.meta().$comment;
+                            ctx.jsonSchema.$comment = schema.meta()?.$comment;
                         }
                     }
                 })

package/dist/utils/file-utils.js

@@ -3,6 +3,8 @@ import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { Readable } from 'node:stream';
 import { finished } from 'node:stream/promises';
+import { ApplyNotes } from '../common/apply-notes.js';
+import { CodifyCliSender } from '../messages/sender.js';
 import { Utils } from './index.js';
 const SPACE_REGEX = /^\s*$/;
 export class FileUtils {
@@ -22,6 +24,7 @@ export class FileUtils {
         await FileUtils.createShellRcIfNotExists();
         const lineToInsert = addLeadingSpacer(addTrailingSpacer(line));
         await fs.appendFile(Utils.getPrimaryShellRc(), lineToInsert);
+        await CodifyCliSender.sendApplyNote(ApplyNotes.sourceShellRc());
         function addLeadingSpacer(line) {
             return line.startsWith('\n')
                 ? line
@@ -40,6 +43,7 @@ export class FileUtils {
         console.log(`Adding to ${path.basename(shellRc)}:
 ${lines.join('\n')}`);
         await fs.appendFile(shellRc, formattedLines);
+        await CodifyCliSender.sendApplyNote(ApplyNotes.sourceShellRc());
     }
     /**
      * This method adds a directory path to the shell rc file if it doesn't already exist.
@@ -56,9 +60,11 @@ ${lines.join('\n')}`);
         console.log(`Saving path: ${value} to ${shellRc}`);
         if (prepend) {
             await fs.appendFile(shellRc, `\nexport PATH=$PATH:${value};`, { encoding: 'utf8' });
-            return;
         }
-        await fs.appendFile(shellRc, `\nexport PATH=${value}:$PATH;`, { encoding: 'utf8' });
+        else {
+            await fs.appendFile(shellRc, `\nexport PATH=${value}:$PATH;`, { encoding: 'utf8' });
+        }
+        await CodifyCliSender.sendApplyNote(ApplyNotes.sourceShellRc());
     }
     static async removeFromFile(filePath, search) {
         const contents = await fs.readFile(filePath, 'utf8');

package/dist/utils/functions.js

@@ -6,9 +6,10 @@ export function splitUserConfig(config) {
         ...(config.name ? { name: config.name } : {}),
         ...(config.dependsOn ? { dependsOn: config.dependsOn } : {}),
         ...(config.os ? { os: config.os } : {}),
+        ...(config.distro ? { distro: config.distro } : {})
     };
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const { type, name, dependsOn, os, ...parameters } = config;
+    const { type, name, dependsOn, os, distro, ...parameters } = config;
     return {
         parameters: parameters,
         coreParameters,

package/dist/utils/index.js

@@ -180,7 +180,21 @@ Brew can be installed using Codify:
                     return;
                 }
                 if (status === SpawnStatus.ERROR) {
-                    throw new Error(`Failed to install package ${packageName} via apt: ${data}`);
+                    // Attempt to fix broken dependencies then retry
+                    const fixResult = await $.spawnSafe('apt-get install -f -y -o Dpkg::Use-Pty=0 -o Dpkg::Progress-Fancy=0', {
+                        requiresRoot: true,
+                        env: { DEBIAN_FRONTEND: 'noninteractive', NEEDRESTART_MODE: 'a' }
+                    });
+                    if (fixResult.status === SpawnStatus.ERROR) {
+                        throw new Error(`Failed to install package ${packageName} via apt: ${data}`);
+                    }
+                    const retryResult = await $.spawnSafe(`apt-get -y -qq install -o Dpkg::Use-Pty=0 -o Dpkg::Progress-Fancy=0 ${packageName}`, {
+                        requiresRoot: true,
+                        env: { DEBIAN_FRONTEND: 'noninteractive', NEEDRESTART_MODE: 'a' }
+                    });
+                    if (retryResult.status === SpawnStatus.ERROR) {
+                        throw new Error(`Failed to install package ${packageName} via apt after fixing dependencies: ${retryResult.data}`);
+                    }
                 }
             }
             const isDnfInstalled = await $.spawnSafe('which dnf');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codifycli/plugin-core",
-  "version": "1.1.0-beta9",
+  "version": "1.2.0",
   "description": "TypeScript library for building Codify plugins to manage system resources (applications, CLI tools, settings) through infrastructure-as-code",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -35,7 +35,7 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@codifycli/schemas": "1.1.0-beta3",
+    "@codifycli/schemas": "^1.2.0",
     "@homebridge/node-pty-prebuilt-multiarch": "^0.13.1",
     "ajv": "^8.18.0",
     "ajv-formats": "^2.1.1",
@@ -43,7 +43,7 @@
     "lodash.isequal": "^4.5.0",
     "nanoid": "^5.0.9",
     "strip-ansi": "^7.1.0",
-    "uuid": "^10.0.0",
+    "uuid": "^14.0.0",
     "zod": "4.1.13"
   },
   "devDependencies": {

package/src/common/apply-notes.ts

@@ -0,0 +1,12 @@
+import path from 'node:path';
+
+import { Utils } from '../utils/index.js';
+
+export const ApplyNotes = {
+  RESTART_REQUIRED: 'A system restart is required for changes to take effect.',
+  NEW_SHELL_REQUIRED: 'Open a new terminal session for the changes to be reflected.',
+  sourceShellRc(): string {
+    const rc = path.basename(Utils.getPrimaryShellRc());
+    return `Source '~/${rc}' for the changes to be reflected.`;
+  },
+} as const;

package/src/common/errors.ts

@@ -4,13 +4,15 @@ export class ApplyValidationError extends Error {
   resourceType: string;
   resourceName?: string;
   plan: Plan<any>;
+  logs: string[];
 
-  constructor(plan: Plan<any>) {
+  constructor(plan: Plan<any>, logs: string[] = []) {
     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;
+    this.logs = logs;
   }
 
   private static prettyPrintPlan(plan: Plan<any>): string {

package/src/index.ts

@@ -1,6 +1,7 @@
 import { MessageHandler } from './messages/handlers.js';
 import { Plugin } from './plugin/plugin.js';
 
+export * from './common/apply-notes.js'
 export * from './errors.js'
 export * from './messages/sender.js'
 export * from './plan/change-set.js'

package/src/messages/handlers.ts

@@ -16,6 +16,7 @@ import {
   MessageStatus,
   PlanRequestDataSchema,
   PlanResponseDataSchema,
+  PluginErrorData,
   ResourceSchema,
   SetVerbosityRequestDataSchema,
   ValidateRequestDataSchema,
@@ -24,6 +25,7 @@ import {
 import { Ajv, SchemaObject, ValidateFunction } from 'ajv';
 import addFormats from 'ajv-formats';
 
+import { ApplyValidationError } from '../common/errors.js';
 import { SudoError } from '../errors.js';
 import { Plugin } from '../plugin/plugin.js';
 
@@ -157,25 +159,31 @@ export class MessageHandler {
 
     // @ts-expect-error TS2239
     const cmd = message.cmd + '_Response';
+    // @ts-expect-error TS2239
+    const requestId = message.requestId || undefined;
+
+    let errorPayload: PluginErrorData;
 
     if (e instanceof SudoError) {
-      return process.send?.({
-        cmd,
-        // @ts-expect-error TS2239
-        requestId: message.requestId || undefined,
-        data: `Plugin: '${this.plugin.name}'. Forbidden usage of sudo for command '${e.command}'. Please contact the plugin developer to fix this.`,
-        status: MessageStatus.ERROR,
-      })
+      errorPayload = {
+        errorType: 'sudo_error',
+        message: `Plugin: '${this.plugin.name}'. Forbidden usage of sudo for command '${e.command}'. Please contact the plugin developer to fix this.`,
+        data: { command: e.command, pluginName: this.plugin.name },
+      };
+    } else if (e instanceof ApplyValidationError) {
+      errorPayload = {
+        errorType: 'apply_validation',
+        message: e.message,
+        data: { plan: e.plan.toResponse(), logs: e.logs },
+      };
+    } else {
+      const isDebug = process.env.DEBUG?.includes('*') ?? false;
+      errorPayload = {
+        errorType: 'unknown',
+        message: isDebug ? (e.stack ?? e.message) : e.message,
+      };
     }
 
-    const isDebug = process.env.DEBUG?.includes('*') ?? false;
-
-    process.send?.({
-      cmd,
-      // @ts-expect-error TS2239
-      requestId: message.requestId || undefined,
-      data: isDebug ? e.stack : e.message,
-      status: MessageStatus.ERROR,
-    })
+    process.send?.({ cmd, requestId, data: errorPayload, status: MessageStatus.ERROR });
   }
 }

package/src/messages/sender.ts

@@ -1,4 +1,10 @@
-import { IpcMessageV2, IpcMessageV2Schema, MessageCmd, PressKeyToContinueRequestData } from '@codifycli/schemas';
+import {
+  ApplyNoteRequestData,
+  IpcMessageV2,
+  IpcMessageV2Schema,
+  MessageCmd,
+  PressKeyToContinueRequestData
+} from '@codifycli/schemas';
 import { Ajv } from 'ajv';
 import { nanoid } from 'nanoid';
 
@@ -21,6 +27,20 @@ class CodifyCliSenderImpl {
     })
   }
 
+  async sendApplyNote(message: string, resourceType?: string): Promise<void> {
+    if (!process.send || !process.connected) {
+      return;
+    }
+
+    await this.sendAndWaitForResponse(<IpcMessageV2>{
+      cmd: MessageCmd.APPLY_NOTE_REQUEST,
+      data: <ApplyNoteRequestData>{
+        message,
+        ...(resourceType && { resourceType }),
+      }
+    });
+  }
+
   async getCodifyCliCredentials(): Promise<string> {
     const data = await this.sendAndWaitForResponse(<IpcMessageV2>{
       cmd: MessageCmd.CODIFY_CREDENTIALS_REQUEST,

package/src/plan/change-set.test.ts

@@ -107,6 +107,7 @@ describe('Change set tests', () => {
 
     const parameterSettings = new ParsedResourceSettings({
       id: 'type',
+      operatingSystems: [],
       parameterSettings: {
         propA: { type: 'array' }
       }
@@ -129,6 +130,7 @@ describe('Change set tests', () => {
 
     const parameterSettings = new ParsedResourceSettings({
       id: 'type',
+      operatingSystems: [],
       parameterSettings: {
         propA: { type: 'array' }
       }
@@ -152,6 +154,7 @@ describe('Change set tests', () => {
 
     const parameterSettings = new ParsedResourceSettings({
       id: 'type',
+      operatingSystems: [],
       parameterSettings: {
         propA: { canModify: true }
       }
@@ -176,6 +179,7 @@ describe('Change set tests', () => {
 
     const parameterSettings = new ParsedResourceSettings({
       id: 'type',
+      operatingSystems: [],
       parameterSettings: {
         propA: { canModify: true },
         propB: { canModify: true }
@@ -196,6 +200,7 @@ describe('Change set tests', () => {
 
     const parameterSettings = new ParsedResourceSettings({
       id: 'type',
+      operatingSystems: [],
       parameterSettings: {
         propA: { type: 'array' }
       },
@@ -213,6 +218,7 @@ describe('Change set tests', () => {
 
     const parameterSettings = new ParsedResourceSettings({
       id: 'type',
+      operatingSystems: [],
       parameterSettings: {
         propA: { type: 'array' }
       },
@@ -229,6 +235,7 @@ describe('Change set tests', () => {
 
     const parameterSettings = new ParsedResourceSettings({
       id: 'type',
+      operatingSystems: [],
       parameterSettings: {
         propA: { type: 'array' }
       },
@@ -245,6 +252,7 @@ describe('Change set tests', () => {
 
     const parameterSettings = new ParsedResourceSettings({
       id: 'type',
+      operatingSystems: [],
       parameterSettings: {
         propA: {
           type: 'array',
@@ -259,12 +267,50 @@ describe('Change set tests', () => {
     expect(result.parameterChanges[0].operation).to.eq(ParameterOperation.MODIFY);
   })
 
+  it('excludes setting parameters from destroy change set', () => {
+    const settings = {
+      id: 'type',
+      operatingSystems: [],
+      parameterSettings: {
+        propA: {},
+        propB: { setting: true },
+      },
+    };
+
+    const cs = ChangeSet.destroy({ propA: 'val', propB: true }, settings as any);
+    expect(cs.parameterChanges.length).to.eq(1);
+    expect(cs.parameterChanges[0].name).to.eq('propA');
+    expect(cs.parameterChanges[0].operation).to.eq(ParameterOperation.REMOVE);
+    expect(cs.operation).to.eq(ResourceOperation.DESTROY);
+  })
+
+  it('excludes multiple setting parameters from destroy change set', () => {
+    const settings = {
+      id: 'type',
+      operatingSystems: [],
+      parameterSettings: {
+        skipAlreadyInstalledCasks: { type: 'boolean', default: true, setting: true },
+        onlyPlanUserInstalled: { type: 'boolean', default: true, setting: true },
+        directory: { type: 'directory' },
+      },
+    };
+
+    const cs = ChangeSet.destroy(
+      { skipAlreadyInstalledCasks: true, onlyPlanUserInstalled: true, directory: '/opt/homebrew' },
+      settings as any
+    );
+    expect(cs.parameterChanges.length).to.eq(1);
+    expect(cs.parameterChanges[0].name).to.eq('directory');
+    expect(cs.operation).to.eq(ResourceOperation.DESTROY);
+  })
+
   it('correctly determines array equality 5', () => {
     const arrA = [{ key1: 'b' }, { key1: 'a' }, { key1: 'a' }];
     const arrB = [{ key1: 'a' }, { key1: 'a' }, { key1: 'b' }];
 
     const parameterSettings = new ParsedResourceSettings({
       id: 'type',
+      operatingSystems: [],
       parameterSettings: {
         propA: {
           type: 'array',

package/src/plan/change-set.ts

@@ -94,6 +94,7 @@ export class ChangeSet<T extends StringIndexedObject> {
 
   static destroy<T extends StringIndexedObject>(current: Partial<T>, settings?: ResourceSettings<T>): ChangeSet<T> {
     const parameterChanges = Object.entries(current)
+      .filter(([k]) => !settings?.parameterSettings?.[k]?.setting)
       .map(([k, v]) => ({
         name: k,
         operation: ParameterOperation.REMOVE,

package/src/plugin/plugin.ts

@@ -31,15 +31,22 @@ import { VerbosityLevel } from '../utils/verbosity-level.js';
 export class Plugin {
   planStorage: Map<string, Plan<any>>;
   planPty = new BackgroundPty();
+  minSupportedCliVersion: string | undefined;
 
   constructor(
     public name: string,
-    public resourceControllers: Map<string, ResourceController<ResourceConfig>>
+    public resourceControllers: Map<string, ResourceController<ResourceConfig>>,
+    options?: { minSupportedCliVersion?: string }
   ) {
     this.planStorage = new Map();
+    this.minSupportedCliVersion = options?.minSupportedCliVersion;
   }
 
-  static create(name: string, resources: Resource<any>[]) {
+  static create(
+    name: string,
+    resources: Resource<any>[],
+    options?: { minSupportedCliVersion?: string }
+  ) {
     const controllers = resources
       .map((resource) => new ResourceController(resource))
 
@@ -47,7 +54,7 @@ export class Plugin {
       controllers.map((r) => [r.typeId, r] as const)
     );
 
-    return new Plugin(name, controllersMap);
+    return new Plugin(name, controllersMap, options);
   }
 
   async initialize(data: InitializeRequestData): Promise<InitializeResponseData> {
@@ -60,6 +67,7 @@ export class Plugin {
     }
 
     return {
+      minSupportedCliVersion: this.minSupportedCliVersion,
       resourceDefinitions: [...this.resourceControllers.values()]
         .map((r) => {
           const sensitiveParameters = Object.entries(r.settings.parameterSettings ?? {})
@@ -174,9 +182,11 @@ export class Plugin {
         throw new Error(`Resource type not found: ${core.type}`);
       }
 
-      const validation = await this.resourceControllers
-        .get(core.type)!
-        .validate(core, parameters);
+      const validation = await ptyLocalStorage.run(this.planPty, () =>
+        this.resourceControllers
+          .get(core.type)!
+          .validate(core, parameters)
+      );
 
       validationResults.push(validation);
     }
@@ -240,7 +250,11 @@ export class Plugin {
       throw new Error('Malformed plan with resource that cannot be found');
     }
 
-    await ptyLocalStorage.run(new SequentialPty(), async () => resource.apply(plan))
+    let applyLogs: string[] = [];
+    await ptyLocalStorage.run(new SequentialPty(), async () => {
+      await resource.apply(plan);
+      applyLogs = getPty().getLogs();
+    });
 
     // 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)
@@ -258,7 +272,7 @@ export class Plugin {
     })
 
     if (validationPlan.requiresChanges()) {
-      throw new ApplyValidationError(plan);
+      throw new ApplyValidationError(validationPlan, applyLogs);
     }
   }
 

package/src/pty/background-pty.ts

@@ -148,6 +148,10 @@ export class BackgroundPty implements IPty {
     })
   }
 
+  getLogs(): string[] {
+    return [];
+  }
+
   private getDefaultShell(): string {
     return process.env.SHELL!;
   }

package/src/pty/index.ts

@@ -34,6 +34,7 @@ export interface SpawnOptions {
   env?: Record<string, unknown>;
   interactive?: boolean;
   requiresRoot?: boolean;
+  requiresSudoAskpass?: boolean;
   stdin?: boolean;
   disableWrapping?: boolean;
 }
@@ -43,8 +44,11 @@ export class SpawnError extends Error {
   cmd: string;
   exitCode: number;
 
-  constructor(cmd: string, exitCode: number, data: string) {
-    super(`Spawn Error: on command "${cmd}" with exit code: ${exitCode}\nOutput:\n${data}`);
+  constructor(cmd: string, exitCode: number, data: string, logs?: string[]) {
+    const logSection = logs?.length
+      ? `\nLast logs:\n${logs.join('\n')}`
+      : '';
+    super(`Spawn Error: on command "${cmd}" with exit code: ${exitCode}\nOutput:\n${data}${logSection}`);
 
     this.data = data;
     this.cmd = cmd;
@@ -59,6 +63,8 @@ export interface IPty {
   spawnSafe(cmd: string | string[], options?: SpawnOptions): Promise<SpawnResult>
 
   kill(): Promise<{ exitCode: number, signal?: number | undefined }>
+
+  getLogs(): string[]
 }
 
 export function getPty(): IPty {

package/src/pty/seqeuntial-pty.ts

@@ -28,11 +28,26 @@ const validateSudoRequestResponse = ajv.compile(CommandRequestResponseDataSchema
  * without a tty (or even a stdin) attached so interactive commands will not work.
  */
 export class SequentialPty implements IPty {
+  private logBuffer: string[] = [];
+  private static readonly MAX_LOG_LINES = 30;
+
+  getLogs(): string[] {
+    return [...this.logBuffer];
+  }
+
+  private appendLog(data: string): void {
+    const lines = data.split('\n');
+    this.logBuffer.push(...lines);
+    if (this.logBuffer.length > SequentialPty.MAX_LOG_LINES) {
+      this.logBuffer = this.logBuffer.slice(-SequentialPty.MAX_LOG_LINES);
+    }
+  }
+
   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);
+      throw new SpawnError(Array.isArray(cmd) ? cmd.join('\n') : cmd, spawnResult.exitCode, spawnResult.data, this.logBuffer);
     }
 
     return spawnResult;
@@ -46,11 +61,13 @@ export class SequentialPty implements IPty {
     }
 
     // If sudo is required, we must delegate to the main codify process.
-    if (options?.stdin || options?.requiresRoot) {
+    if (options?.stdin || options?.requiresRoot || options?.requiresSudoAskpass) {
       return this.externalSpawn(cmd, options);
     }
 
-    console.log(`Running command: ${Array.isArray(cmd) ? cmd.join('\\\n') : cmd}` + (options?.cwd ? `(${options?.cwd})` : ''))
+    const cmdLine = `Running command: ${Array.isArray(cmd) ? cmd.join('\\\n') : cmd}` + (options?.cwd ? `(${options?.cwd})` : '');
+    console.log(cmdLine);
+    this.appendLog(cmdLine);
 
     return new Promise((resolve) => {
       const output: string[] = [];
@@ -87,6 +104,7 @@ export class SequentialPty implements IPty {
         }
 
         output.push(data.toString());
+        this.appendLog(data.toString());
       })
 
       const resizeListener = () => {

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

@@ -76,7 +76,7 @@ export class ParsedResourceSettings<T extends StringIndexedObject> implements Re
             if (ctx.path.length === 0) {
               ctx.jsonSchema.title = settings.id;
               ctx.jsonSchema.description = schema.description ?? settings.description ?? `${settings.id} resource. Can be used to manage ${settings.id}`;
-              ctx.jsonSchema.$comment = (schema.meta() as Record<string, string | undefined>).$comment;
+              ctx.jsonSchema.$comment = (schema.meta() as Record<string, string | undefined> | undefined)?.$comment;
             }
           }
         }) as JSONSchemaType<T>

package/src/utils/file-utils.ts

@@ -4,6 +4,8 @@ import path from 'node:path';
 import { Readable } from 'node:stream';
 import { finished } from 'node:stream/promises';
 
+import { ApplyNotes } from '../common/apply-notes.js';
+import { CodifyCliSender } from '../messages/sender.js';
 import { Utils } from './index.js';
 
 const SPACE_REGEX = /^\s*$/
@@ -33,6 +35,7 @@ export class FileUtils {
     );
 
     await fs.appendFile(Utils.getPrimaryShellRc(), lineToInsert)
+    await CodifyCliSender.sendApplyNote(ApplyNotes.sourceShellRc());
 
     function addLeadingSpacer(line: string): string {
       return line.startsWith('\n')
@@ -57,6 +60,7 @@ export class FileUtils {
 ${lines.join('\n')}`)
 
     await fs.appendFile(shellRc, formattedLines)
+    await CodifyCliSender.sendApplyNote(ApplyNotes.sourceShellRc());
   }
 
   /**
@@ -77,10 +81,11 @@ ${lines.join('\n')}`)
 
     if (prepend) {
       await fs.appendFile(shellRc, `\nexport PATH=$PATH:${value};`, { encoding: 'utf8' });
-      return;
+    } else {
+      await fs.appendFile(shellRc, `\nexport PATH=${value}:$PATH;`, { encoding: 'utf8' });
     }
 
-    await fs.appendFile(shellRc, `\nexport PATH=${value}:$PATH;`, { encoding: 'utf8' });
+    await CodifyCliSender.sendApplyNote(ApplyNotes.sourceShellRc());
   }
 
   static async removeFromFile(filePath: string, search: string): Promise<void> {

package/src/utils/functions.ts

@@ -10,10 +10,11 @@ export function splitUserConfig<T extends StringIndexedObject>(
     ...(config.name ? { name: config.name } : {}),
     ...(config.dependsOn ? { dependsOn: config.dependsOn } : {}),
     ...(config.os ? { os: config.os } : {}),
+    ...(config.distro ? { distro: config.distro } : {})
   };
 
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const { type, name, dependsOn, os, ...parameters } = config;
+  const { type, name, dependsOn, os, distro, ...parameters } = config;
 
   return {
     parameters: parameters as T,

package/src/utils/index.ts

@@ -225,7 +225,24 @@ Brew can be installed using Codify:
         }
 
         if (status === SpawnStatus.ERROR) {
-          throw new Error(`Failed to install package ${packageName} via apt: ${data}`);
+          // Attempt to fix broken dependencies then retry
+          const fixResult = await $.spawnSafe('apt-get install -f -y -o Dpkg::Use-Pty=0 -o Dpkg::Progress-Fancy=0', {
+            requiresRoot: true,
+            env: { DEBIAN_FRONTEND: 'noninteractive', NEEDRESTART_MODE: 'a' }
+          });
+
+          if (fixResult.status === SpawnStatus.ERROR) {
+            throw new Error(`Failed to install package ${packageName} via apt: ${data}`);
+          }
+
+          const retryResult = await $.spawnSafe(`apt-get -y -qq install -o Dpkg::Use-Pty=0 -o Dpkg::Progress-Fancy=0 ${packageName}`, {
+            requiresRoot: true,
+            env: { DEBIAN_FRONTEND: 'noninteractive', NEEDRESTART_MODE: 'a' }
+          });
+
+          if (retryResult.status === SpawnStatus.ERROR) {
+            throw new Error(`Failed to install package ${packageName} via apt after fixing dependencies: ${retryResult.data}`);
+          }
         }
       }
 

package/src/utils/internal-utils.test.ts

@@ -9,6 +9,7 @@ describe('Utils tests', () => {
       name: 'name',
       dependsOn: ['a', 'b', 'c'],
       os: ['linux'],
+      distro: ['debian-based'],
       propA: 'propA',
       propB: 'propB',
       propC: 'propC',