applescript-node 1.0.1

package/dist/index.js

@@ -0,0 +1,3220 @@
+'use strict';
+
+var child_process = require('child_process');
+var util = require('util');
+var crypto = require('crypto');
+var promises = require('fs/promises');
+var os = require('os');
+var path = require('path');
+var fastXmlParser = require('fast-xml-parser');
+
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/expressions.ts
+var ExprBuilder = class {
+  /**
+   * Greater than comparison: left > right
+   * @param left - Variable or expression. Scoped variables (from loops) get autocomplete.
+   *   The type `TScope | (string & Record<never, never>)` provides autocomplete for scoped
+   *   variables while still accepting any string expression.
+   * @param right - Value to compare against (string or number)
+   * @returns AppleScript expression: "left > right"
+   * @example
+   * e.gt('counter', 10)  // => "counter > 10"
+   * e.gt('aPerson', 5)   // => "aPerson > 5" (with autocomplete for 'aPerson' if in scope)
+   */
+  gt(left, right) {
+    const rightValue = typeof right === "number" ? right.toString() : `"${right}"`;
+    return `${left} > ${rightValue}`;
+  }
+  /**
+   * Less than comparison: left < right
+   * @param left - Variable or expression (scoped variables get autocomplete)
+   */
+  lt(left, right) {
+    const rightValue = typeof right === "number" ? right.toString() : `"${right}"`;
+    return `${left} < ${rightValue}`;
+  }
+  /**
+   * Greater than or equal: left >= right
+   * @param left - Variable or expression (scoped variables get autocomplete)
+   */
+  gte(left, right) {
+    const rightValue = typeof right === "number" ? right.toString() : `"${right}"`;
+    return `${left} >= ${rightValue}`;
+  }
+  /**
+   * Less than or equal: left <= right
+   * @param left - Variable or expression (scoped variables get autocomplete)
+   */
+  lte(left, right) {
+    const rightValue = typeof right === "number" ? right.toString() : `"${right}"`;
+    return `${left} <= ${rightValue}`;
+  }
+  /**
+   * Equality comparison: left = right
+   * @param left - Variable or expression (scoped variables get autocomplete)
+   */
+  eq(left, right) {
+    let rightValue;
+    if (typeof right === "string") {
+      rightValue = `"${right}"`;
+    } else if (typeof right === "boolean") {
+      rightValue = right.toString();
+    } else {
+      rightValue = right.toString();
+    }
+    return `${left} = ${rightValue}`;
+  }
+  /**
+   * Inequality comparison: left is not equal to right
+   * @param left - Variable or expression (scoped variables get autocomplete)
+   */
+  ne(left, right) {
+    let rightValue;
+    if (typeof right === "string") {
+      rightValue = `"${right}"`;
+    } else if (typeof right === "boolean") {
+      rightValue = right.toString();
+    } else {
+      rightValue = right.toString();
+    }
+    return `${left} is not equal to ${rightValue}`;
+  }
+  /**
+   * Logical AND: combines multiple conditions
+   * Example: expr.and(expr.gt('x', 5), expr.lt('x', 10))
+   */
+  and(...conditions) {
+    return conditions.join(" and ");
+  }
+  /**
+   * Logical OR: combines multiple conditions
+   * Example: expr.or(expr.eq('status', 'done'), expr.eq('status', 'skipped'))
+   */
+  or(...conditions) {
+    return conditions.join(" or ");
+  }
+  /**
+   * Logical NOT: negates a condition
+   * Example: expr.not(expr.eq('status', 'pending'))
+   */
+  not(condition) {
+    return `not ${condition}`;
+  }
+  /**
+   * String length: length of str
+   * Often used in conditions like: expr.gt(expr.length('name'), 5)
+   */
+  length(str) {
+    return `length of ${str}`;
+  }
+  /**
+   * Property access: prop of obj
+   * @param obj - Variable name. Scoped variables (from loops) get autocomplete.
+   *   The type allows both scoped variables and arbitrary string expressions.
+   * @param prop - Property name to access
+   * @returns AppleScript expression: "prop of obj"
+   * @example
+   * e.property('aNote', 'name')      // => "name of aNote"
+   * e.property('aPerson', 'emails')  // => "emails of aPerson" (with autocomplete for 'aPerson')
+   */
+  property(obj, prop) {
+    return `${prop} of ${obj}`;
+  }
+  /**
+   * Count: count of items
+   * Example: expr.gt(expr.count('notes'), 10)
+   */
+  count(items) {
+    return `count of ${items}`;
+  }
+  /**
+   * Existence check: exists item
+   * Example: expr.exists('window "Settings"')
+   */
+  exists(item) {
+    return `exists ${item}`;
+  }
+  /**
+   * String contains: haystack contains needle
+   * Example: expr.contains('name', '"test"')
+   */
+  contains(haystack, needle) {
+    const needleValue = typeof needle === "number" ? needle.toString() : needle;
+    return `${haystack} contains ${needleValue}`;
+  }
+  /**
+   * String starts with: str begins with prefix
+   * Example: expr.startsWith('name', '"John"')
+   */
+  startsWith(str, prefix) {
+    return `${str} begins with ${prefix}`;
+  }
+  /**
+   * String ends with: str ends with suffix
+   * Example: expr.endsWith('name', '"son"')
+   */
+  endsWith(str, suffix) {
+    return `${str} ends with ${suffix}`;
+  }
+  /**
+   * Type checking: the type of item is typeName
+   * Common types: 'text', 'number', 'list', 'record', 'boolean'
+   */
+  typeEquals(item, type) {
+    return `the type of ${item} is ${type}`;
+  }
+  /**
+   * Matches wildcard pattern
+   * Example: expr.matches('name', '"*Smith*"')
+   */
+  matches(str, pattern) {
+    return `${str} contains ${pattern}`;
+  }
+  /**
+   * Parentheses for explicit grouping
+   * Useful when combining complex boolean expressions
+   * Example: expr.or(expr.paren(expr.and(...)), expr.eq(...))
+   */
+  paren(condition) {
+    return `(${condition})`;
+  }
+  /**
+   * Create a comparison between two expressions
+   * Useful for comparing two computed properties
+   * Example: expr.compare('length of name1', '>', 'length of name2')
+   */
+  compare(left, operator, right) {
+    return `${left} ${operator} ${right}`;
+  }
+  /**
+   * Collection accessor: every element of container
+   * Example: expr.every('participant', 'aChat') => "every participant of aChat"
+   * Example: expr.every('note', 'folder "Notes"') => "every note of folder \"Notes\""
+   */
+  every(element, container) {
+    return `every ${element} of ${container}`;
+  }
+  /**
+   * Nested property accessor: chains multiple properties
+   * Example: expr.nestedProperty('aChat', 'account', 'id') => "id of account of aChat"
+   * Example: expr.nestedProperty('note', 'folder', 'name') => "name of folder of note"
+   * @param obj - Variable name (scoped variables get autocomplete)
+   */
+  nestedProperty(obj, ...properties) {
+    if (properties.length === 0) {
+      return obj;
+    }
+    return properties.reduce((acc, prop) => `${prop} of ${acc}`, obj);
+  }
+  /**
+   * Type casting: expression as type
+   * Example: expr.asType('creation date of aNote', 'string') => "creation date of aNote as string"
+   * Example: expr.asType(expr.property('aNote', 'id'), 'text') => "id of aNote as text"
+   */
+  asType(expression, type) {
+    return `${expression} as ${type}`;
+  }
+  /**
+   * Substring/range accessor: text start thru end of source
+   * Example: expr.text(1, 100, 'notePlaintext') => "text 1 thru 100 of notePlaintext"
+   * Example: expr.text(5, 10, 'myString') => "text 5 thru 10 of myString"
+   */
+  text(start, end, source) {
+    return `text ${start} thru ${end} of ${source}`;
+  }
+  /**
+   * Character accessor: character n of source
+   * Example: expr.character(1, 'myString') => "character 1 of myString"
+   */
+  character(index, source) {
+    return `character ${index} of ${source}`;
+  }
+  /**
+   * Item accessor: item n of collection
+   * Example: expr.item(1, 'myList') => "item 1 of myList"
+   * Example: expr.item('i', 'notes') => "item i of notes"
+   */
+  item(index, collection) {
+    return `item ${index} of ${collection}`;
+  }
+  /**
+   * Items range: items start thru end of collection
+   * Example: expr.items(1, 5, 'myList') => "items 1 thru 5 of myList"
+   */
+  items(start, end, collection) {
+    return `items ${start} thru ${end} of ${collection}`;
+  }
+  /**
+   * First item: first element of collection
+   * Example: expr.first('note', 'notes') => "first note of notes"
+   */
+  first(element, collection) {
+    return `first ${element} of ${collection}`;
+  }
+  /**
+   * Last item: last element of collection
+   * Example: expr.last('note', 'notes') => "last note of notes"
+   */
+  last(element, collection) {
+    return `last ${element} of ${collection}`;
+  }
+  /**
+   * Some: some element where condition
+   * Example: expr.some('note', 'notes', 'name contains "test"')
+   */
+  some(element, collection, condition) {
+    return `some ${element} of ${collection} where ${condition}`;
+  }
+  /**
+   * Filter: every element where condition
+   * Example: expr.filter('note', 'notes', 'shared = true')
+   */
+  filter(element, collection, condition) {
+    return `every ${element} of ${collection} where ${condition}`;
+  }
+  /**
+   * Concatenation: left & right
+   * Example: expr.concat('text 1 thru 50 of body', '"..."') => 'text 1 thru 50 of body & "..."'
+   */
+  concat(...parts) {
+    return parts.join(" & ");
+  }
+  /**
+   * Property of item accessor: property of item N of collection
+   * Example: expr.propertyOfItem('value', 1, 'emails of aPerson') => "value of item 1 of emails of aPerson"
+   * Example: expr.propertyOfItem('name', 1, 'contacts') => "name of item 1 of contacts"
+   */
+  propertyOfItem(property, index, collection) {
+    return `${property} of item ${index} of ${collection}`;
+  }
+  /**
+   * Value of item accessor (common shorthand for propertyOfItem('value', ...))
+   * Example: expr.valueOfItem(1, 'emails of aPerson') => "value of item 1 of emails of aPerson"
+   * Example: expr.valueOfItem(1, 'phones of contact') => "value of item 1 of phones of contact"
+   */
+  valueOfItem(index, collection) {
+    return this.propertyOfItem("value", index, collection);
+  }
+};
+function expr() {
+  return new ExprBuilder();
+}
+
+// src/builder-utils.ts
+function resolveExpression(expression) {
+  return typeof expression === "function" ? expression(new ExprBuilder()) : expression;
+}
+
+// src/builder.ts
+var ScriptBuilderError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ScriptBuilderError";
+  }
+};
+var AppleScriptBuilder = class {
+  script = [];
+  indentLevel = 0;
+  INDENT = "  ";
+  blockStack = [];
+  getIndentation() {
+    return this.INDENT.repeat(this.indentLevel);
+  }
+  escapeString(str) {
+    return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+  }
+  formatValue(value) {
+    if (value === null) return "missing value";
+    if (typeof value === "string") return `"${this.escapeString(value)}"`;
+    if (typeof value === "number") return value.toString();
+    if (typeof value === "boolean") return value.toString();
+    if (Array.isArray(value)) {
+      return `{${value.map((v) => this.formatValue(v)).join(", ")}}`;
+    }
+    const entries = Object.entries(value).map(([k, v]) => `${k}:${this.formatValue(v)}`).join(", ");
+    return `{${entries}}`;
+  }
+  makeRecord(properties) {
+    const entries = Object.entries(properties).map(([k, v]) => `${k}:${this.formatValue(v)}`).join(", ");
+    return `{${entries}}`;
+  }
+  validateBlockStack() {
+    if (this.blockStack.length > 0) {
+      const unclosedBlocks = this.blockStack.map((b) => b.type).join(", ");
+      throw new ScriptBuilderError(`Unclosed blocks remain: ${unclosedBlocks}`);
+    }
+  }
+  pushBlock(type, target) {
+    this.blockStack.push({ type, target });
+    this.indentLevel++;
+  }
+  popBlock() {
+    if (this.blockStack.length === 0) {
+      throw new ScriptBuilderError("Cannot end block: no blocks are currently open");
+    }
+    this.blockStack.pop();
+    this.indentLevel--;
+  }
+  validateBlockType(expectedType) {
+    if (this.blockStack.length === 0) {
+      throw new ScriptBuilderError(
+        `Cannot end ${expectedType} block: no blocks are currently open`
+      );
+    }
+    const currentBlock = this.blockStack[this.blockStack.length - 1];
+    if (currentBlock.type !== expectedType) {
+      throw new ScriptBuilderError(
+        `Cannot end ${expectedType} block: currently inside ${currentBlock.type} block`
+      );
+    }
+  }
+  addLine(line) {
+    this.script.push(`${this.getIndentation()}${line}`);
+  }
+  // Core language constructs
+  tell(target) {
+    this.script.push(`${this.getIndentation()}tell application "${this.escapeString(target)}"`);
+    this.pushBlock("tell", target);
+    return this;
+  }
+  tellTarget(target) {
+    this.script.push(`${this.getIndentation()}tell ${target}`);
+    this.pushBlock("tell", target);
+    return this;
+  }
+  tellProcess(processName) {
+    this.script.push(
+      `${this.getIndentation()}tell application "System Events" to tell process "${this.escapeString(processName)}"`
+    );
+    this.pushBlock("tell", processName);
+    return this;
+  }
+  on(handlerName, parameters) {
+    const params = parameters?.length ? ` ${parameters.join(", ")}` : "";
+    this.script.push(`${this.getIndentation()}on ${handlerName}${params}`);
+    this.pushBlock("on", handlerName);
+    return this;
+  }
+  /**
+   * Define a handler using the 'to' syntax (alternative to 'on').
+   * Both 'on' and 'to' are equivalent in AppleScript.
+   * @param handlerName The name of the handler
+   * @param parameters Optional array of parameter names
+   * @returns This builder instance for method chaining
+   * @example
+   * .to('sayHello', ['name'])
+   *   .displayDialog('Hello ' & name)
+   * .endto()
+   */
+  to(handlerName, parameters) {
+    const params = parameters?.length ? ` ${parameters.join(", ")}` : "";
+    this.script.push(`${this.getIndentation()}to ${handlerName}${params}`);
+    this.pushBlock("on", handlerName);
+    return this;
+  }
+  /**
+   * Call/invoke a handler with parameters.
+   * @param handlerName The name of the handler to call
+   * @param parameters Optional array of parameter values
+   * @returns This builder instance for method chaining
+   * @example
+   * .callHandler('sayHello', ['"John"'])
+   * .callHandler('processFile', ['theFile', 'true'])
+   */
+  callHandler(handlerName, parameters) {
+    const params = parameters?.length ? ` ${parameters.join(", ")}` : "";
+    this.script.push(`${this.getIndentation()}${handlerName}${params}`);
+    return this;
+  }
+  /**
+   * Call a handler from within a tell statement using 'my' keyword.
+   * Required when calling handlers from within tell blocks.
+   * @param handlerName The name of the handler to call
+   * @param parameters Optional array of parameter values
+   * @returns This builder instance for method chaining
+   * @example
+   * .tell('Finder')
+   *   .my('processFile', ['theFile'])
+   * .endtell()
+   */
+  my(handlerName, parameters) {
+    const params = parameters?.length ? ` ${parameters.join(", ")}` : "";
+    this.script.push(`${this.getIndentation()}my ${handlerName}${params}`);
+    return this;
+  }
+  /**
+   * Call a handler from within a tell statement using 'of me' syntax.
+   * Alternative to 'my' keyword for calling handlers from within tell blocks.
+   * @param handlerName The name of the handler to call
+   * @param parameters Optional array of parameter values
+   * @returns This builder instance for method chaining
+   * @example
+   * .tell('Finder')
+   *   .ofMe('processFile', ['theFile'])
+   * .endtell()
+   */
+  ofMe(handlerName, parameters) {
+    const params = parameters?.length ? ` ${parameters.join(", ")}` : "";
+    this.script.push(`${this.getIndentation()}${handlerName}${params} of me`);
+    return this;
+  }
+  /**
+   * Define a handler with labeled parameters (interleaved syntax).
+   * AppleScript supports splitting parameter names with colons and spaces.
+   * @param handlerName The name of the handler
+   * @param labeledParams Object with parameter labels and values
+   * @returns This builder instance for method chaining
+   * @example
+   * .onLabeled('displayError', { message: 'theErrorMessage', buttons: 'theButtons' })
+   *   .displayDialog(theErrorMessage, { buttons: theButtons })
+   * .endon()
+   */
+  onLabeled(handlerName, labeledParams) {
+    const paramPairs = Object.entries(labeledParams);
+    const params = paramPairs.map(([label, value]) => `${label} ${value}`).join(", ");
+    this.script.push(`${this.getIndentation()}on ${handlerName} ${params}`);
+    this.pushBlock("on", handlerName);
+    return this;
+  }
+  /**
+   * Define a handler with labeled parameters using 'to' syntax.
+   * @param handlerName The name of the handler
+   * @param labeledParams Object with parameter labels and values
+   * @returns This builder instance for method chaining
+   */
+  toLabeled(handlerName, labeledParams) {
+    const paramPairs = Object.entries(labeledParams);
+    const params = paramPairs.map(([label, value]) => `${label} ${value}`).join(", ");
+    this.script.push(`${this.getIndentation()}to ${handlerName} ${params}`);
+    this.pushBlock("on", handlerName);
+    return this;
+  }
+  // Event Handlers
+  /**
+   * Define a 'run' event handler (implicit or explicit).
+   * The run handler is called when a script executes.
+   * @param explicit If true, explicitly define the run handler; if false, use implicit
+   * @returns This builder instance for method chaining
+   * @example
+   * .runHandler(true)  // Explicit: on run ... end run
+   *   .displayDialog('Script is running')
+   * .endrun()
+   */
+  runHandler(explicit = false) {
+    if (explicit) {
+      this.script.push(`${this.getIndentation()}on run`);
+      this.pushBlock("on", "run");
+    }
+    return this;
+  }
+  /**
+   * Define a 'quit' event handler.
+   * Called when a script app quits.
+   * @returns This builder instance for method chaining
+   * @example
+   * .quitHandler()
+   *   .displayDialog('Script is quitting')
+   * .endquit()
+   */
+  quitHandler() {
+    this.script.push(`${this.getIndentation()}on quit`);
+    this.pushBlock("on", "quit");
+    return this;
+  }
+  /**
+   * Define an 'open' event handler for drag-and-drop support.
+   * Makes the script app drag-and-droppable.
+   * @param parameterName Name for the dropped items parameter (default: 'theDroppedItems')
+   * @returns This builder instance for method chaining
+   * @example
+   * .openHandler('theFiles')
+   *   .repeatWith('aFile', 'theFiles')
+   *     .displayDialog('Processing: ' & aFile)
+   *   .endrepeat()
+   * .endopen()
+   */
+  openHandler(parameterName = "theDroppedItems") {
+    this.script.push(`${this.getIndentation()}on open ${parameterName}`);
+    this.pushBlock("on", "open");
+    return this;
+  }
+  /**
+   * Define an 'idle' event handler for stay-open applications.
+   * Called periodically in stay-open script apps.
+   * @param returnSeconds Number of seconds to wait before next idle call (default: 30)
+   * @returns This builder instance for method chaining
+   * @example
+   * .idleHandler(5)  // Check every 5 seconds
+   *   .displayDialog('Idle processing')
+   *   .return(5)  // Return 5 seconds for next idle
+   * .endidle()
+   */
+  idleHandler(_returnSeconds = 30) {
+    this.script.push(`${this.getIndentation()}on idle`);
+    this.pushBlock("on", "idle");
+    return this;
+  }
+  end() {
+    if (this.blockStack.length === 0) {
+      throw new ScriptBuilderError("Cannot call end(): no blocks are currently open");
+    }
+    const block = this.blockStack[this.blockStack.length - 1];
+    this.popBlock();
+    const endText = block.type === "on" && block.target ? block.target : block.type;
+    this.script.push(`${this.getIndentation()}end ${endText}`);
+    return this;
+  }
+  /**
+   * Explicitly end an if block.
+   * Preferred over end() for clarity when working with multiple nested blocks.
+   */
+  endif() {
+    this.validateBlockType("if");
+    return this.end();
+  }
+  /**
+   * Explicitly end a repeat block.
+   * Preferred over end() for clarity when working with multiple nested blocks.
+   */
+  endrepeat() {
+    this.validateBlockType("repeat");
+    return this.end();
+  }
+  /**
+   * Explicitly end a try block.
+   * Preferred over end() for clarity when working with multiple nested blocks.
+   */
+  endtry() {
+    this.validateBlockType("try");
+    return this.end();
+  }
+  /**
+   * Explicitly end a tell block.
+   * Preferred over end() for clarity when working with multiple nested blocks.
+   */
+  endtell() {
+    this.validateBlockType("tell");
+    return this.end();
+  }
+  /**
+   * Explicitly end an on handler block.
+   * Preferred over end() for clarity when working with multiple nested blocks.
+   */
+  endon() {
+    this.validateBlockType("on");
+    return this.end();
+  }
+  /**
+   * Explicitly end a considering block.
+   * Preferred over end() for clarity when working with multiple nested blocks.
+   */
+  endconsidering() {
+    this.validateBlockType("considering");
+    return this.end();
+  }
+  /**
+   * Explicitly end an ignoring block.
+   * Preferred over end() for clarity when working with multiple nested blocks.
+   */
+  endignoring() {
+    this.validateBlockType("ignoring");
+    return this.end();
+  }
+  /**
+   * Explicitly end a using block.
+   * Preferred over end() for clarity when working with multiple nested blocks.
+   */
+  endusing() {
+    this.validateBlockType("using");
+    return this.end();
+  }
+  /**
+   * Explicitly end a with block.
+   * Preferred over end() for clarity when working with multiple nested blocks.
+   */
+  endwith() {
+    this.validateBlockType("with");
+    return this.end();
+  }
+  /**
+   * Explicitly end a 'to' handler block.
+   * Preferred over end() for clarity when working with handlers.
+   */
+  endto() {
+    this.validateBlockType("on");
+    return this.end();
+  }
+  /**
+   * Explicitly end a 'run' handler block.
+   * Preferred over end() for clarity when working with run handlers.
+   */
+  endrun() {
+    this.validateBlockType("on");
+    return this.end();
+  }
+  /**
+   * Explicitly end a 'quit' handler block.
+   * Preferred over end() for clarity when working with quit handlers.
+   */
+  endquit() {
+    this.validateBlockType("on");
+    return this.end();
+  }
+  /**
+   * Explicitly end an 'open' handler block.
+   * Preferred over end() for clarity when working with open handlers.
+   */
+  endopen() {
+    this.validateBlockType("on");
+    return this.end();
+  }
+  /**
+   * Explicitly end an 'idle' handler block.
+   * Preferred over end() for clarity when working with idle handlers.
+   */
+  endidle() {
+    this.validateBlockType("on");
+    return this.end();
+  }
+  if(condition) {
+    const conditionStr = resolveExpression(condition);
+    this.script.push(`${this.getIndentation()}if ${conditionStr}`);
+    this.pushBlock("if");
+    return this;
+  }
+  thenBlock() {
+    if (this.blockStack.length === 0 || this.blockStack[this.blockStack.length - 1].type !== "if") {
+      throw new ScriptBuilderError("Cannot call thenBlock(): no if block is currently open");
+    }
+    const lastLine = this.script[this.script.length - 1];
+    this.script[this.script.length - 1] = `${lastLine} then`;
+    return this;
+  }
+  else() {
+    if (this.blockStack.length === 0 || this.blockStack[this.blockStack.length - 1].type !== "if") {
+      throw new ScriptBuilderError("Cannot call else(): no if block is currently open");
+    }
+    this.indentLevel--;
+    this.script.push(`${this.getIndentation()}else`);
+    this.indentLevel++;
+    return this;
+  }
+  elseIf(condition) {
+    if (this.blockStack.length === 0 || this.blockStack[this.blockStack.length - 1].type !== "if") {
+      throw new ScriptBuilderError("Cannot call elseIf(): no if block is currently open");
+    }
+    this.indentLevel--;
+    this.script.push(`${this.getIndentation()}else if ${condition}`);
+    this.indentLevel++;
+    return this;
+  }
+  repeat(times) {
+    if (times !== void 0 && (!Number.isInteger(times) || times < 1)) {
+      throw new ScriptBuilderError("Repeat times must be a positive integer");
+    }
+    if (times !== void 0) {
+      this.script.push(`${this.getIndentation()}repeat ${times} times`);
+    } else {
+      this.script.push(`${this.getIndentation()}repeat`);
+    }
+    this.pushBlock("repeat");
+    return this;
+  }
+  repeatWith(variable, list) {
+    if (!(variable && list)) {
+      throw new ScriptBuilderError("Both variable and list must be provided for repeatWith");
+    }
+    this.script.push(`${this.getIndentation()}repeat with ${variable} in ${list}`);
+    this.pushBlock("repeat");
+    return this;
+  }
+  repeatUntil(condition) {
+    if (!condition) {
+      throw new ScriptBuilderError("Condition must be provided for repeatUntil");
+    }
+    this.script.push(`${this.getIndentation()}repeat until ${condition}`);
+    this.pushBlock("repeat");
+    return this;
+  }
+  repeatWhile(condition) {
+    if (!condition) {
+      throw new ScriptBuilderError("Condition must be provided for repeatWhile");
+    }
+    this.script.push(`${this.getIndentation()}repeat while ${condition}`);
+    this.pushBlock("repeat");
+    return this;
+  }
+  repeatWithRange(variable, start, end) {
+    if (!(variable && start && end)) {
+      throw new ScriptBuilderError("Variable, start, and end must be provided for repeatWithRange");
+    }
+    const startExpr = typeof start === "number" ? start.toString() : start;
+    const endExpr = typeof end === "number" ? end.toString() : end;
+    this.script.push(
+      `${this.getIndentation()}repeat with ${variable} from ${startExpr} to ${endExpr}`
+    );
+    this.pushBlock("repeat");
+    return this;
+  }
+  exitRepeat() {
+    const hasRepeatBlock = this.blockStack.some((block) => block.type === "repeat");
+    if (!hasRepeatBlock) {
+      throw new ScriptBuilderError("Cannot call exitRepeat(): no repeat block is currently open");
+    }
+    this.script.push(`${this.getIndentation()}exit repeat`);
+    return this;
+  }
+  exitRepeatIf(condition) {
+    const hasRepeatBlock = this.blockStack.some((block) => block.type === "repeat");
+    if (!hasRepeatBlock) {
+      throw new ScriptBuilderError("Cannot call exitRepeatIf(): no repeat block is currently open");
+    }
+    const cond = resolveExpression(condition);
+    this.script.push(`${this.getIndentation()}if ${cond} then`);
+    this.indentLevel++;
+    this.script.push(`${this.getIndentation()}exit repeat`);
+    this.indentLevel--;
+    this.script.push(`${this.getIndentation()}end if`);
+    return this;
+  }
+  continueRepeat() {
+    const hasRepeatBlock = this.blockStack.some((block) => block.type === "repeat");
+    if (!hasRepeatBlock) {
+      throw new ScriptBuilderError(
+        "Cannot call continueRepeat(): no repeat block is currently open"
+      );
+    }
+    this.script.push(`${this.getIndentation()}continue repeat`);
+    return this;
+  }
+  considering(attributes) {
+    if (!attributes.length) {
+      throw new ScriptBuilderError("At least one attribute must be provided for considering");
+    }
+    this.script.push(`${this.getIndentation()}considering ${attributes.join(", ")}`);
+    this.pushBlock("considering");
+    return this;
+  }
+  ignoring(attributes) {
+    if (!attributes.length) {
+      throw new ScriptBuilderError("At least one attribute must be provided for ignoring");
+    }
+    this.script.push(`${this.getIndentation()}ignoring ${attributes.join(", ")}`);
+    this.pushBlock("ignoring");
+    return this;
+  }
+  using(terms) {
+    this.script.push(`${this.getIndentation()}using terms from ${terms.join(", ")}`);
+    this.pushBlock("using");
+    return this;
+  }
+  with(timeout, transaction) {
+    let command = `${this.getIndentation()}with`;
+    if (timeout !== void 0) command += ` timeout of ${timeout}`;
+    if (transaction) command += " transaction";
+    this.script.push(command);
+    this.pushBlock("with");
+    return this;
+  }
+  try() {
+    this.script.push(`${this.getIndentation()}try`);
+    this.pushBlock("try");
+    return this;
+  }
+  onError(variableName) {
+    if (this.blockStack.length === 0 || this.blockStack[this.blockStack.length - 1].type !== "try") {
+      throw new ScriptBuilderError("Cannot call onError(): no try block is currently open");
+    }
+    this.indentLevel--;
+    const varPart = variableName ? ` ${variableName}` : "";
+    this.script.push(`${this.getIndentation()}on error${varPart}`);
+    this.indentLevel++;
+    return this;
+  }
+  error(message, number) {
+    let command = `${this.getIndentation()}error "${this.escapeString(message)}"`;
+    if (number !== void 0) command += ` number ${number}`;
+    this.script.push(command);
+    return this;
+  }
+  return(value) {
+    this.script.push(`${this.getIndentation()}return ${this.formatValue(value)}`);
+    return this;
+  }
+  returnRaw(expression) {
+    this.script.push(`${this.getIndentation()}return ${expression}`);
+    return this;
+  }
+  /**
+   * Build a JSON object string from AppleScript variables.
+   * Generates clean, readable JSON without manual string concatenation.
+   *
+   * @param variableMap Mapping of JSON keys to AppleScript variable names
+   * @returns AppleScript expression that evaluates to a JSON string
+   *
+   * @example
+   * // Instead of manual string building:
+   * // '"{" & "\\"name\\":\\"" & winName & "\\"}" '
+   *
+   * // Use:
+   * const jsonExpr = builder.buildJsonObject({
+   *   name: 'winName',
+   *   position: 'winPosition',
+   *   size: 'winSize'
+   * });
+   * builder.returnRaw(jsonExpr);
+   *
+   * // Generates: '{"name":"Calculator","position":"100,200","size":"800x600"}'
+   */
+  buildJsonObject(variableMap) {
+    const entries = Object.entries(variableMap);
+    const parts = ['"{"'];
+    entries.forEach(([jsonKey, varName], index) => {
+      const comma = index > 0 ? "," : "";
+      parts.push(`"${comma}\\"${jsonKey}\\":\\""`);
+      parts.push(varName);
+      parts.push('"\\""');
+    });
+    parts.push('"}"');
+    return parts.join(" & ");
+  }
+  /**
+   * Build and return a JSON object from AppleScript variables.
+   * Convenience method that combines buildJsonObject() with returnRaw().
+   *
+   * @param variableMap Mapping of JSON keys to AppleScript variable names
+   *
+   * @example
+   * .setExpression('winName', 'name of window 1')
+   * .setExpression('winPosition', 'position of window 1 as text')
+   * .returnJsonObject({
+   *   name: 'winName',
+   *   position: 'winPosition'
+   * })
+   */
+  returnJsonObject(variableMap) {
+    const jsonExpr = this.buildJsonObject(variableMap);
+    this.returnRaw(jsonExpr);
+    return this;
+  }
+  /**
+   * Ultra-convenient shorthand for the common "map collection to JSON" pattern.
+   * Replaces verbose manual iteration, property extraction, and JSON conversion.
+   *
+   * This single method handles:
+   * - Creating temporary collection list
+   * - Iterating through items (with optional limit/condition)
+   * - Extracting properties with smart detection (simple vs complex expressions)
+   * - Field-level transformations (firstOf, ifExists, type conversion)
+   * - Error handling (skip failed items)
+   * - JSON serialization and return
+   *
+   * @param itemVariable Loop variable name (e.g., 'aNote')
+   * @param collection Collection to iterate (e.g., 'every note')
+   * @param properties Mapping of JSON keys to AppleScript properties or PropertyExtractor objects
+   * @param options Optional: limit, until/while conditions, error handling
+   *
+   * @example
+   * // Simple properties
+   * .tell('Notes')
+   * .mapToJson('aNote', 'every note', {
+   *   id: 'id',
+   *   name: 'name',
+   *   content: 'plaintext',
+   *   created: 'creation date of aNote as string',
+   * }, { limit: 10, skipErrors: true })
+   * .endtell()
+   *
+   * @example
+   * // Advanced field extractors (NEW!)
+   * .tell('Contacts')
+   * .mapToJson('aPerson', 'every person', {
+   *   id: 'id',
+   *   name: 'name',
+   *   email: { property: (e) => e.property('aPerson', 'emails'), firstOf: true },
+   *   phone: { property: 'phones', firstOf: true },
+   *   birthday: { property: 'birth date', ifExists: true, asType: 'string' },
+   * }, { limit: 50, skipErrors: true })
+   * .endtell()
+   */
+  mapToJson(itemVariable, collection, properties, options = {}) {
+    const listVar = "__collected_items";
+    this.set(listVar, []);
+    const buildBody = (b) => {
+      const finalPropertyMap = {};
+      for (const [jsonKey, propDef] of Object.entries(properties)) {
+        if (typeof propDef === "string") {
+          finalPropertyMap[jsonKey] = propDef;
+        } else {
+          if (!propDef.property) {
+            throw new ScriptBuilderError(
+              `PropertyExtractor for "${jsonKey}" must have a "property" field`
+            );
+          }
+          const tempVarName = `__temp_${jsonKey}`;
+          const propExpr = typeof propDef.property === "function" ? propDef.property(new ExprBuilder()) : `${propDef.property} of ${itemVariable}`;
+          const defaultVal = propDef.default ? typeof propDef.default === "function" ? propDef.default(new ExprBuilder()) : propDef.default : "missing value";
+          if (propDef.firstOf) {
+            b.setFirstOf(tempVarName, propExpr, defaultVal);
+          } else if (propDef.ifExists) {
+            b.setIfExists(tempVarName, propExpr, defaultVal, propDef.asType);
+          } else {
+            b.setExpression(tempVarName, propExpr);
+          }
+          finalPropertyMap[jsonKey] = tempVarName;
+        }
+      }
+      if (options.skipErrors) {
+        b.tryCatch(
+          (tryBlock) => tryBlock.pickEndRecord(listVar, itemVariable, finalPropertyMap),
+          (catchBlock) => catchBlock.comment("Skip items with errors")
+        );
+      } else {
+        b.pickEndRecord(listVar, itemVariable, finalPropertyMap);
+      }
+    };
+    if (options.limit !== void 0) {
+      const limit = options.limit;
+      this.set("__counter", 0);
+      this.forEachUntil(
+        itemVariable,
+        collection,
+        (e) => e.gte("__counter", limit),
+        (b) => {
+          b.increment("__counter");
+          buildBody(b);
+        }
+      );
+    } else if (options.until !== void 0) {
+      this.forEachUntil(itemVariable, collection, options.until, buildBody);
+    } else if (options.while !== void 0) {
+      this.forEachWhile(itemVariable, collection, options.while, buildBody);
+    } else {
+      this.forEach(itemVariable, collection, buildBody);
+    }
+    const recordPropertyMap = Object.keys(properties).reduce((acc, key) => {
+      acc[key] = key;
+      return acc;
+    }, {});
+    return this.returnAsJson(listVar, recordPropertyMap);
+  }
+  /**
+   * Return a list of records as a JSON string.
+   * Converts AppleScript records to JSON format by manually building the JSON string.
+   * Handles proper escaping of strings, booleans, numbers, and null values.
+   * @param listVariable Name of the variable containing a list of records
+   * @param propertyMap Mapping of JSON keys to AppleScript property names (e.g., {id: 'noteId', name: 'noteName'})
+   */
+  returnAsJson(listVariable, propertyMap) {
+    const handlers = [
+      "",
+      "on escapeJsonString(str)",
+      "  set escapedStr to str",
+      `  set escapedStr to my replaceText(escapedStr, "\\\\", "\\\\\\\\")`,
+      `  set escapedStr to my replaceText(escapedStr, "\\"", "\\\\\\"") `,
+      `  set escapedStr to my replaceText(escapedStr, return, "\\\\n")`,
+      `  set escapedStr to my replaceText(escapedStr, linefeed, "\\\\n")`,
+      `  set escapedStr to my replaceText(escapedStr, tab, "\\\\t")`,
+      "  return escapedStr",
+      "end escapeJsonString",
+      "",
+      "on replaceText(theText, searchStr, replaceStr)",
+      `  set AppleScript's text item delimiters to searchStr`,
+      "  set textItems to text items of theText",
+      `  set AppleScript's text item delimiters to replaceStr`,
+      "  set newText to textItems as text",
+      `  set AppleScript's text item delimiters to ""`,
+      "  return newText",
+      "end replaceText",
+      "",
+      "on valueToJson(val)",
+      "  if val is missing value then",
+      `    return "null"`,
+      "  else if class of val is boolean then",
+      "    if val then",
+      `      return "true"`,
+      "    else",
+      `      return "false"`,
+      "    end if",
+      "  else if class of val is integer or class of val is real then",
+      "    return val as text",
+      "  else",
+      `    return "\\"" & my escapeJsonString(val as text) & "\\""`,
+      "  end if",
+      "end valueToJson",
+      ""
+    ];
+    this.script.unshift(...handlers);
+    this.raw("set jsonParts to {}");
+    this.raw(`repeat with rec in ${listVariable}`);
+    this.raw("  try");
+    this.raw(`    set itemJson to "{"`);
+    const entries = Object.entries(propertyMap);
+    entries.forEach(([jsonKey, appleScriptProp], index) => {
+      const comma = index > 0 ? "," : "";
+      this.raw(
+        `    set itemJson to itemJson & "${comma}\\"${jsonKey}\\":" & my valueToJson(${appleScriptProp} of rec)`
+      );
+    });
+    this.raw(`    set itemJson to itemJson & "}"`);
+    this.raw("    set end of jsonParts to itemJson");
+    this.raw("  end try");
+    this.raw("end repeat");
+    this.raw("");
+    this.raw(`set AppleScript's text item delimiters to ","`);
+    this.raw(`set jsonArray to "[" & (jsonParts as text) & "]"`);
+    this.raw(`set AppleScript's text item delimiters to ""`);
+    this.raw("return jsonArray");
+    return this;
+  }
+  log(message) {
+    this.script.push(`${this.getIndentation()}log "${this.escapeString(message)}"`);
+    return this;
+  }
+  comment(text) {
+    this.script.push(`${this.getIndentation()}-- ${text}`);
+    return this;
+  }
+  // Application control
+  activate() {
+    this.script.push(`${this.getIndentation()}activate`);
+    return this;
+  }
+  quit() {
+    this.script.push(`${this.getIndentation()}quit`);
+    return this;
+  }
+  reopen() {
+    this.script.push(`${this.getIndentation()}reopen`);
+    return this;
+  }
+  launch() {
+    this.script.push(`${this.getIndentation()}launch`);
+    return this;
+  }
+  running() {
+    this.script.push(`${this.getIndentation()}running`);
+    return this;
+  }
+  // Window management
+  closeWindow(window) {
+    if (window) {
+      this.script.push(`${this.getIndentation()}close window "${this.escapeString(window)}"`);
+    } else {
+      this.script.push(`${this.getIndentation()}close front window`);
+    }
+    return this;
+  }
+  closeAllWindows() {
+    this.script.push(`${this.getIndentation()}close every window`);
+    return this;
+  }
+  minimizeWindow(window) {
+    if (window) {
+      this.script.push(
+        `${this.getIndentation()}set miniaturized of window "${this.escapeString(window)}" to true`
+      );
+    } else {
+      this.script.push(`${this.getIndentation()}set miniaturized of front window to true`);
+    }
+    return this;
+  }
+  zoomWindow(window) {
+    if (window) {
+      this.script.push(
+        `${this.getIndentation()}set zoomed of window "${this.escapeString(window)}" to true`
+      );
+    } else {
+      this.script.push(`${this.getIndentation()}set zoomed of front window to true`);
+    }
+    return this;
+  }
+  // UI interaction
+  click(target) {
+    this.script.push(`${this.getIndentation()}click ${target}`);
+    return this;
+  }
+  select(target) {
+    this.script.push(`${this.getIndentation()}select ${target}`);
+    return this;
+  }
+  keystroke(text, modifiers) {
+    const modString = modifiers?.length ? ` using {${modifiers.join(", ")}}` : "";
+    this.script.push(`${this.getIndentation()}keystroke "${this.escapeString(text)}"${modString}`);
+    return this;
+  }
+  /**
+   * Type multiple characters with automatic delays between each keystroke.
+   * Convenient shorthand for typing sequences like numbers or text.
+   * @param text String of characters to type (each character gets a separate keystroke)
+   * @param delayBetween Delay in seconds between each keystroke (default: 0.1)
+   * @example
+   * // Instead of:
+   * // .keystroke('1').delay(0.1).keystroke('2').delay(0.1).keystroke('3')
+   * // Use:
+   * // .keystrokes('123')
+   */
+  keystrokes(text, delayBetween = 0.1) {
+    const chars = text.split("");
+    chars.forEach((char, index) => {
+      this.keystroke(char);
+      if (index < chars.length - 1) {
+        this.delay(delayBetween);
+      }
+    });
+    return this;
+  }
+  delay(seconds) {
+    this.script.push(`${this.getIndentation()}delay ${seconds}`);
+    return this;
+  }
+  // Dialog and alerts
+  displayDialog(text, options = {}) {
+    let command = `${this.getIndentation()}display dialog "${this.escapeString(text)}"`;
+    if (options.buttons?.length) {
+      const escapedButtons = options.buttons.map((b) => this.escapeString(b));
+      command += ` buttons {"${escapedButtons.join('", "')}"}`;
+    }
+    if (options.defaultButton) {
+      command += ` default button "${this.escapeString(options.defaultButton)}"`;
+    }
+    if (options.withIcon) {
+      command += ` with icon ${options.withIcon}`;
+    }
+    if (options.givingUpAfter) {
+      command += ` giving up after ${options.givingUpAfter}`;
+    }
+    this.script.push(command);
+    return this;
+  }
+  displayNotification(text, options = {}) {
+    let command = `${this.getIndentation()}display notification "${this.escapeString(text)}"`;
+    if (options.title) {
+      command += ` with title "${this.escapeString(options.title)}"`;
+    }
+    if (options.subtitle) {
+      command += ` subtitle "${this.escapeString(options.subtitle)}"`;
+    }
+    if (options.sound) {
+      command += ` sound name "${this.escapeString(options.sound)}"`;
+    }
+    this.script.push(command);
+    return this;
+  }
+  // Variables and properties
+  set(variable, value) {
+    this.script.push(`${this.getIndentation()}set ${variable} to ${this.formatValue(value)}`);
+    return this;
+  }
+  setExpression(variable, expression) {
+    let expr2;
+    if (typeof expression === "function") {
+      expr2 = expression(new ExprBuilder());
+    } else if (typeof expression === "string") {
+      expr2 = expression;
+    } else {
+      expr2 = this.makeRecordFrom(expression);
+    }
+    this.script.push(`${this.getIndentation()}set ${variable} to ${expr2}`);
+    return this;
+  }
+  setExpressions(expressions) {
+    for (const [variable, expression] of Object.entries(expressions)) {
+      const expr2 = resolveExpression(expression);
+      this.script.push(`${this.getIndentation()}set ${variable} to ${expr2}`);
+    }
+    return this;
+  }
+  appendTo(variable, expression, options) {
+    let expr2 = resolveExpression(expression);
+    if (options?.prependLinefeed) {
+      expr2 = `linefeed & ${expr2}`;
+    }
+    if (options?.appendLinefeed) {
+      expr2 = `${expr2} & linefeed`;
+    }
+    this.script.push(`${this.getIndentation()}set ${variable} to ${variable} & ${expr2}`);
+    return this;
+  }
+  increment(variable, by = 1) {
+    this.script.push(`${this.getIndentation()}set ${variable} to ${variable} + ${by}`);
+    return this;
+  }
+  decrement(variable, by = 1) {
+    this.script.push(`${this.getIndentation()}set ${variable} to ${variable} - ${by}`);
+    return this;
+  }
+  get(property) {
+    this.script.push(`${this.getIndentation()}get ${property}`);
+    return this;
+  }
+  copy(value, to) {
+    this.script.push(`${this.getIndentation()}copy ${this.formatValue(value)} to ${to}`);
+    return this;
+  }
+  count(items) {
+    this.script.push(`${this.getIndentation()}count ${items}`);
+    return this;
+  }
+  setCountOf(variable, items) {
+    this.script.push(`${this.getIndentation()}set ${variable} to count of (${items})`);
+    return this;
+  }
+  exists(item) {
+    this.script.push(`${this.getIndentation()}exists ${item}`);
+    return this;
+  }
+  setEnd(variable, value) {
+    this.script.push(
+      `${this.getIndentation()}set end of ${variable} to ${this.formatValue(value)}`
+    );
+    return this;
+  }
+  setEndRaw(variable, expression) {
+    let expr2;
+    if (typeof expression === "function") {
+      expr2 = expression(new ExprBuilder());
+    } else if (typeof expression === "string") {
+      expr2 = expression;
+    } else {
+      expr2 = this.makeRecordFrom(expression);
+    }
+    this.script.push(`${this.getIndentation()}set end of ${variable} to ${expr2}`);
+    return this;
+  }
+  setEndRecord(listVariable, sourceOrExpressions, propertyMap) {
+    let recordExpressions;
+    if (typeof sourceOrExpressions === "string") {
+      if (!propertyMap) {
+        throw new ScriptBuilderError(
+          "propertyMap is required when sourceOrExpressions is a source object name"
+        );
+      }
+      const sourceObj = sourceOrExpressions;
+      recordExpressions = Object.entries(propertyMap).reduce(
+        (acc, [key, prop]) => {
+          acc[key] = `${prop} of ${sourceObj}`;
+          return acc;
+        },
+        {}
+      );
+    } else {
+      recordExpressions = sourceOrExpressions;
+    }
+    const recordStr = this.makeRecordFrom(recordExpressions);
+    this.script.push(`${this.getIndentation()}set end of ${listVariable} to ${recordStr}`);
+    return this;
+  }
+  /**
+   * Intuitive shorthand for picking properties from a source object and building a record.
+   * Automatically detects full expressions vs simple property names:
+   * - Simple properties (no special keywords) get "of source" appended
+   * - Complex expressions (with 'of', 'as', 'where', etc.) are used as-is
+   *
+   * @param listVariable Name of the list to append the record to
+   * @param sourceObject Name of the source object to extract properties from
+   * @param propertyMap Mapping of record keys to property names/expressions
+   *
+   * @example
+   * // Mix simple properties and complex expressions
+   * .pickEndRecord('notesList', 'aNote', {
+   *   noteId: 'id',                              // => id of aNote
+   *   noteName: 'name',                          // => name of aNote
+   *   noteCreated: 'creation date of aNote as string',  // used as-is (has 'as')
+   *   noteModified: 'modification date as string',      // used as-is (has 'as')
+   * })
+   */
+  pickEndRecord(listVariable, sourceObject, propertyMap) {
+    const recordExpressions = Object.entries(propertyMap).reduce(
+      (acc, [key, prop]) => {
+        const isFullExpression = prop.startsWith("__temp_") || prop.includes(" of ") || prop.includes(" where ") || prop.includes(" as ") || prop.includes(" whose ") || prop.includes(" thru ") || prop.includes("every ") || prop.includes("some ") || prop.includes("first ") || prop.includes("last ") || prop.includes("count ") || prop.includes("length ") || prop.includes(" contains ") || prop.includes(" begins with ") || prop.includes(" ends with ");
+        acc[key] = isFullExpression ? prop : `${prop} of ${sourceObject}`;
+        return acc;
+      },
+      {}
+    );
+    const recordStr = this.makeRecordFrom(recordExpressions);
+    this.script.push(`${this.getIndentation()}set end of ${listVariable} to ${recordStr}`);
+    return this;
+  }
+  /**
+   * Set variable using ternary operator pattern with if-then-else block.
+   * Much more concise than manually calling ifThenElse for simple conditional assignments.
+   *
+   * Generates an if-then-else block that sets the variable conditionally.
+   *
+   * @param variable - Variable name to set
+   * @param condition - Condition to evaluate (string or ExprBuilder callback)
+   * @param trueExpression - Expression to use if condition is true
+   * @param falseExpression - Expression to use if condition is false
+   *
+   * @example
+   * // With ExprBuilder for type-safe conditions
+   * .setTernary('personEmail',
+   *   (e) => e.gt(e.count(e.property('aPerson', 'emails')), 0),
+   *   (e) => e.valueOfItem(1, e.property('aPerson', 'emails')),
+   *   'missing value'
+   * )
+   *
+   * @example
+   * // With strings
+   * .setTernary('status',
+   *   'count of items > 0',
+   *   '"active"',
+   *   '"empty"'
+   * )
+   *
+   * @example
+   * // Replaces verbose ifThenElse:
+   * // .ifThenElse(
+   * //   (e) => e.gt('x', 10),
+   * //   (then_) => then_.set('result', 'high'),
+   * //   (else_) => else_.set('result', 'low')
+   * // )
+   * // With concise ternary:
+   * .setTernary('result', (e) => e.gt('x', 10), '"high"', '"low"')
+   */
+  setTernary(variable, condition, trueExpression, falseExpression) {
+    const cond = resolveExpression(condition);
+    const trueExpr = resolveExpression(trueExpression);
+    const falseExpr = resolveExpression(falseExpression);
+    return this.ifThenElse(
+      cond,
+      (then_) => then_.setExpression(variable, trueExpr),
+      (else_) => else_.setExpression(variable, falseExpr)
+    );
+  }
+  /**
+   * Append to list using ternary operator pattern with if-then-else block.
+   * Combines setEndRaw with conditional logic for ultra-concise syntax.
+   *
+   * Generates an if-then-else block that conditionally appends to the list.
+   *
+   * @param listVariable - Name of the list to append to
+   * @param condition - Condition to evaluate (string or ExprBuilder callback)
+   * @param trueExpression - Expression to append if condition is true
+   * @param falseExpression - Expression to append if condition is false
+   *
+   * @example
+   * // Conditionally append different values
+   * .set('results', [])
+   * .forEach('item', 'every file of desktop', (loop) =>
+   *   loop.setEndTernary('results',
+   *     (e) => e.gt(e.property('item', 'size'), 1000000),
+   *     '"large"',
+   *     '"small"'
+   *   )
+   * )
+   *
+   * @example
+   * // With complex expressions
+   * .setEndTernary('emails',
+   *   'count of email addresses of person > 0',
+   *   'value of item 1 of email addresses of person',
+   *   'missing value'
+   * )
+   */
+  setEndTernary(listVariable, condition, trueExpression, falseExpression) {
+    const cond = resolveExpression(condition);
+    const trueExpr = resolveExpression(trueExpression);
+    const falseExpr = resolveExpression(falseExpression);
+    return this.ifThenElse(
+      cond,
+      (then_) => then_.setEndRaw(listVariable, trueExpr),
+      (else_) => else_.setEndRaw(listVariable, falseExpr)
+    );
+  }
+  /**
+   * Set variable to first item of collection or default value if collection is empty.
+   * Ultra-shorthand for the common "first or default" pattern.
+   *
+   * Automatically generates an if-then-else block that checks the collection count and sets the variable accordingly.
+   *
+   * @template TNewVar - The variable name (inferred from first parameter)
+   * @param variable - Variable name to set (will be added to scope)
+   * @param collection - Collection expression to get first item from
+   * @param defaultValue - Value to use if collection is empty (default: 'missing value')
+   *
+   * @example
+   * // Get first email or missing value
+   * .setFirstOf('personEmail', (e) => e.property('aPerson', 'emails'))
+   *
+   * @example
+   * // Get first email or custom default
+   * .setFirstOf('personEmail', (e) => e.property('aPerson', 'emails'), '"no-email@example.com"')
+   *
+   * @example
+   * // With string expression
+   * .setFirstOf('personEmail', 'emails of aPerson', 'missing value')
+   *
+   * @example
+   * // Replaces verbose pattern:
+   * // .setTernary('personEmail',
+   * //   (e) => e.gt(e.count(e.property('aPerson', 'emails')), 0),
+   * //   (e) => e.valueOfItem(1, e.property('aPerson', 'emails')),
+   * //   'missing value'
+   * // )
+   */
+  setFirstOf(variable, collection, defaultValue = "missing value") {
+    const coll = resolveExpression(collection);
+    const defaultVal = resolveExpression(defaultValue);
+    return this.ifThenElse(
+      `count of ${coll} > 0`,
+      (then_) => then_.setExpression(variable, `value of item 1 of ${coll}`),
+      (else_) => else_.setExpression(variable, defaultVal)
+    );
+  }
+  /**
+   * Append first item of collection or default value to a list.
+   * Ultra-shorthand for the common "first or default" pattern in list building.
+   *
+   * Automatically generates an if-then-else block that checks the collection count and appends to the list accordingly.
+   *
+   * @param listVariable - Name of the list to append to
+   * @param collection - Collection expression to get first item from
+   * @param defaultValue - Value to use if collection is empty (default: 'missing value')
+   *
+   * @example
+   * // Build list of first emails
+   * .forEach('person', 'every person', (loop) =>
+   *   loop.setEndFirstOf('emails', (e) => e.property('person', 'email addresses'))
+   * )
+   *
+   * @example
+   * // With custom default
+   * .setEndFirstOf('results', 'items of record', '""')
+   */
+  setEndFirstOf(listVariable, collection, defaultValue = "missing value") {
+    const coll = resolveExpression(collection);
+    const defaultVal = resolveExpression(defaultValue);
+    return this.ifThenElse(
+      `count of ${coll} > 0`,
+      (then_) => then_.setEndRaw(listVariable, `value of item 1 of ${coll}`),
+      (else_) => else_.setEndRaw(listVariable, defaultVal)
+    );
+  }
+  /**
+   * Set variable to property value if it exists, otherwise use default value.
+   * Ultra-shorthand for the common "take if exists or default" pattern.
+   *
+   * Automatically generates an if-then-else block that checks if the property exists
+   * and sets the variable accordingly, with optional type conversion.
+   *
+   * @template TNewVar - The variable name (inferred from first parameter)
+   * @param variable - Variable name to set (will be added to scope)
+   * @param property - Property expression to check and retrieve
+   * @param defaultValue - Value to use if property doesn't exist (default: 'missing value')
+   * @param asType - Optional type to convert property to (e.g., 'string', 'integer')
+   *
+   * @example
+   * // Get birth date as string or missing value
+   * .setIfExists('personBirthday',
+   *   (e) => e.property('aPerson', 'birth date'),
+   *   'missing value',
+   *   'string'
+   * )
+   *
+   * @example
+   * // Simpler syntax with string expression
+   * .setIfExists('personBirthday', 'birth date of aPerson', 'missing value', 'string')
+   *
+   * @example
+   * // Without type conversion
+   * .setIfExists('personNote', 'note of aPerson', '""')
+   *
+   * @example
+   * // Replaces verbose pattern:
+   * // .setTernary('personBirthday',
+   * //   (e) => e.exists(e.property('aPerson', 'birth date')),
+   * //   (e) => e.asType(e.property('aPerson', 'birth date'), 'string'),
+   * //   'missing value'
+   * // )
+   */
+  setIfExists(variable, property, defaultValue = "missing value", asType) {
+    const prop = resolveExpression(property);
+    const defaultVal = resolveExpression(defaultValue);
+    const valueExpr = asType ? `${prop} as ${asType}` : prop;
+    return this.ifThenElse(
+      `exists ${prop}`,
+      (then_) => then_.setExpression(variable, valueExpr),
+      (else_) => else_.setExpression(variable, defaultVal)
+    );
+  }
+  /**
+   * Append property value to list if it exists, otherwise append default value.
+   * Ultra-shorthand for the common "take if exists or default" pattern in list building.
+   *
+   * Automatically generates an if-then-else block that checks if the property exists
+   * and appends to the list accordingly, with optional type conversion.
+   *
+   * @param listVariable - Name of the list to append to
+   * @param property - Property expression to check and retrieve
+   * @param defaultValue - Value to use if property doesn't exist (default: 'missing value')
+   * @param asType - Optional type to convert property to (e.g., 'string', 'integer')
+   *
+   * @example
+   * // Build list of birth dates
+   * .forEach('person', 'every person', (loop) =>
+   *   loop.setEndIfExists('dates', 'birth date of person', '""', 'string')
+   * )
+   *
+   * @example
+   * // With ExprBuilder
+   * .setEndIfExists('notes',
+   *   (e) => e.property('contact', 'note'),
+   *   'missing value'
+   * )
+   */
+  setEndIfExists(listVariable, property, defaultValue = "missing value", asType) {
+    const prop = resolveExpression(property);
+    const defaultVal = resolveExpression(defaultValue);
+    const valueExpr = asType ? `${prop} as ${asType}` : prop;
+    return this.ifThenElse(
+      `exists ${prop}`,
+      (then_) => then_.setEndRaw(listVariable, valueExpr),
+      (else_) => else_.setEndRaw(listVariable, defaultVal)
+    );
+  }
+  setProperty(variable, property, value) {
+    this.script.push(
+      `${this.getIndentation()}set ${property} of ${variable} to ${this.formatValue(value)}`
+    );
+    return this;
+  }
+  makeRecordFrom(variableNames) {
+    const entries = Object.entries(variableNames).map(([key, varName]) => `${key}:${varName}`).join(", ");
+    return `{${entries}}`;
+  }
+  // List operations
+  first(items) {
+    this.script.push(`${this.getIndentation()}first item of ${items}`);
+    return this;
+  }
+  last(items) {
+    this.script.push(`${this.getIndentation()}last item of ${items}`);
+    return this;
+  }
+  rest(items) {
+    this.script.push(`${this.getIndentation()}rest of ${items}`);
+    return this;
+  }
+  reverse(items) {
+    this.script.push(`${this.getIndentation()}reverse of ${items}`);
+    return this;
+  }
+  some(items, test) {
+    this.script.push(`${this.getIndentation()}some item of ${items} where ${test}`);
+    return this;
+  }
+  every(items, test) {
+    this.script.push(`${this.getIndentation()}every item of ${items} where ${test}`);
+    return this;
+  }
+  whose(items, condition) {
+    return `${items} whose ${condition}`;
+  }
+  getEvery(itemType, location) {
+    const loc = location ? ` of ${location}` : "";
+    this.script.push(`${this.getIndentation()}get every ${itemType}${loc}`);
+    return this;
+  }
+  getEveryWhere(itemType, condition, location) {
+    const loc = location ? ` of ${location}` : "";
+    this.script.push(`${this.getIndentation()}get every ${itemType}${loc} where ${condition}`);
+    return this;
+  }
+  // Text operations
+  offset(text, in_) {
+    this.script.push(`${this.getIndentation()}offset of ${text} in ${in_}`);
+    return this;
+  }
+  contains(text, in_) {
+    this.script.push(`${this.getIndentation()}${in_} contains ${text}`);
+    return this;
+  }
+  beginsWith(text, with_) {
+    this.script.push(`${this.getIndentation()}${text} begins with ${with_}`);
+    return this;
+  }
+  endsWith(text, with_) {
+    this.script.push(`${this.getIndentation()}${text} ends with ${with_}`);
+    return this;
+  }
+  // System operations
+  path(to) {
+    this.script.push(`${this.getIndentation()}path to ${to}`);
+    return this;
+  }
+  info(for_) {
+    this.script.push(`${this.getIndentation()}info for ${for_}`);
+    return this;
+  }
+  do(script) {
+    this.script.push(`${this.getIndentation()}do script "${this.escapeString(script)}"`);
+    return this;
+  }
+  doShellScript(command, administrator) {
+    let cmd = `${this.getIndentation()}do shell script "${this.escapeString(command)}"`;
+    if (administrator) {
+      cmd += " with administrator privileges";
+    }
+    this.script.push(cmd);
+    return this;
+  }
+  // Raw script and building
+  raw(script) {
+    this.script.push(`${this.getIndentation()}${script}`);
+    return this;
+  }
+  // Enhanced Application control
+  getRunningApplications() {
+    this.raw(
+      'tell application "System Events" to return {name, bundle identifier, visible, frontmost} of every process where background only is false'
+    );
+    return this;
+  }
+  getFrontmostApplication() {
+    this.raw(
+      'tell application "System Events" to return name of first process where frontmost is true'
+    );
+    return this;
+  }
+  activateApplication(appName) {
+    this.raw(`tell application "${this.escapeString(appName)}" to activate`);
+    return this;
+  }
+  hideApplication(appName) {
+    this.raw(
+      `tell application "System Events" to tell process "${this.escapeString(appName)}" to set visible to false`
+    );
+    return this;
+  }
+  unhideApplication(appName) {
+    this.raw(
+      `tell application "System Events" to tell process "${this.escapeString(appName)}" to set visible to true`
+    );
+    return this;
+  }
+  quitApplication(appName) {
+    this.raw(`tell application "${this.escapeString(appName)}" to quit`);
+    return this;
+  }
+  isApplicationRunning(appName) {
+    this.raw(
+      `tell application "System Events" to return exists (processes where name is "${this.escapeString(appName)}")`
+    );
+    return this;
+  }
+  getApplicationInfo(appName) {
+    this.raw(
+      `tell application "System Events" to tell process "${this.escapeString(appName)}" to return properties`
+    );
+    return this;
+  }
+  // Enhanced Window management
+  getWindowInfo(appName, windowName) {
+    this.raw(
+      windowName ? `tell application "${this.escapeString(appName)}" to tell window "${this.escapeString(windowName)}" to return {name, id, bounds, miniaturized, zoomed}` : `tell application "${this.escapeString(appName)}" to tell front window to return {name, id, bounds, miniaturized, zoomed}`
+    );
+    return this;
+  }
+  getAllWindows(appName) {
+    this.raw(
+      `tell application "${this.escapeString(appName)}" to return {name, id, bounds, miniaturized, zoomed} of every window`
+    );
+    return this;
+  }
+  getFrontmostWindow(appName) {
+    this.raw(
+      `tell application "${this.escapeString(appName)}" to tell front window to return {name, id, bounds, miniaturized, zoomed}`
+    );
+    return this;
+  }
+  setWindowBounds(appName, windowName, bounds) {
+    this.raw(
+      `tell application "${this.escapeString(appName)}" to tell window "${this.escapeString(windowName)}" to set bounds to {${bounds.x}, ${bounds.y}, ${bounds.x + bounds.width}, ${bounds.y + bounds.height}}`
+    );
+    return this;
+  }
+  moveWindow(appName, windowName, x, y) {
+    this.raw(
+      `tell application "${this.escapeString(appName)}" to tell window "${this.escapeString(windowName)}" to set position to {${x}, ${y}}`
+    );
+    return this;
+  }
+  resizeWindow(appName, windowName, width, height) {
+    this.raw(
+      `tell application "${this.escapeString(appName)}" to tell window "${this.escapeString(windowName)}" to set size to {${width}, ${height}}`
+    );
+    return this;
+  }
+  arrangeWindows(arrangement) {
+    this.raw(`tell application "System Events" to tell process "Finder" to ${arrangement} windows`);
+    return this;
+  }
+  focusWindow(appName, windowName) {
+    this.raw(`tell application "${this.escapeString(appName)}" to activate`);
+    this.raw(
+      `tell application "${this.escapeString(appName)}" to tell window "${this.escapeString(windowName)}" to set index to 1`
+    );
+    return this;
+  }
+  switchToWindow(appName, windowName) {
+    return this.focusWindow(appName, windowName);
+  }
+  // Enhanced UI interaction
+  pressKey(key, modifiers) {
+    const modString = modifiers?.length ? ` using {${modifiers.join(", ")}}` : "";
+    this.raw(`tell application "System Events" to key code ${key}${modString}`);
+    return this;
+  }
+  pressKeyCode(keyCode, modifiers) {
+    const modString = modifiers?.length ? ` using {${modifiers.join(", ")}}` : "";
+    this.raw(`tell application "System Events" to key code ${keyCode}${modString}`);
+    return this;
+  }
+  typeText(text) {
+    this.raw(`tell application "System Events" to keystroke "${this.escapeString(text)}"`);
+    return this;
+  }
+  clickButton(buttonName) {
+    this.raw(`tell application "System Events" to click button "${this.escapeString(buttonName)}"`);
+    return this;
+  }
+  clickMenuItem(menuName, itemName) {
+    this.raw(
+      `tell application "System Events" to click menu item "${this.escapeString(itemName)}" of menu "${this.escapeString(menuName)}" of menu bar 1`
+    );
+    return this;
+  }
+  // Convenience helpers for cleaner API
+  /**
+   * Simplified tell application pattern with automatic block closing.
+   * Cleaner than manually calling tell()...end().
+   * @param appName Name of the application to tell
+   * @param block Callback that builds commands for the application
+   */
+  tellApp(appName, block) {
+    this.tell(appName);
+    block(this);
+    return this.end();
+  }
+  /**
+   * Simplified if-then pattern that automatically closes the if block.
+   * Cleaner than manually calling if()...thenBlock()...endif().
+   * @param condition The condition to check (string or ExprBuilder callback)
+   * @param thenBlock Callback that builds the then branch
+   */
+  ifThen(condition, thenBlock) {
+    this.if(condition).thenBlock();
+    thenBlock(this);
+    return this.endif();
+  }
+  /**
+   * Simplified if-then-else pattern that automatically closes the if block.
+   * Cleaner than manually calling if()...thenBlock()...else()...endif().
+   * @param condition The condition to check (string or ExprBuilder callback)
+   * @param thenBlock Callback that builds the then branch
+   * @param elseBlock Callback that builds the else branch
+   */
+  ifThenElse(condition, thenBlock, elseBlock) {
+    this.if(condition).thenBlock();
+    thenBlock(this);
+    this.else();
+    elseBlock(this);
+    return this.endif();
+  }
+  /**
+   * Simplified try-catch pattern that automatically closes the try block.
+   * Cleaner than manually calling try()...onError()...endtry().
+   * @param tryBlock Callback that builds the try branch
+   * @param catchBlock Callback that builds the on error branch
+   */
+  tryCatch(tryBlock, catchBlock) {
+    this.try();
+    tryBlock(this);
+    this.onError();
+    catchBlock(this);
+    return this.endtry();
+  }
+  /**
+   * Simplified try-catch pattern with error variable capture.
+   * @param tryBlock Callback that builds the try branch
+   * @param errorVarName Name of the variable to capture the error
+   * @param catchBlock Callback that builds the on error branch
+   */
+  tryCatchError(tryBlock, errorVarName, catchBlock) {
+    this.try();
+    tryBlock(this);
+    this.onError(errorVarName);
+    catchBlock(this);
+    return this.endtry();
+  }
+  /**
+   * Iterate over items with automatic block closing.
+   * More intuitive name for repeatWith that uses callback pattern.
+   * @param variable Loop variable name
+   * @param list Expression for the list to iterate (e.g., 'every note')
+   * @param block Callback that builds the loop body
+   */
+  forEach(variable, list, block) {
+    this.repeatWith(variable, list);
+    block(this);
+    return this.endrepeat();
+  }
+  /**
+   * Iterate over items while a condition is true.
+   * Combines forEach with an early exit condition for cleaner syntax.
+   * @param variable Loop variable name
+   * @param list Expression for the list to iterate (e.g., 'every note')
+   * @param condition Condition to check before each iteration (continues while true)
+   * @param block Callback that builds the loop body
+   */
+  forEachWhile(variable, list, condition, block) {
+    this.repeatWith(variable, list);
+    this.ifThen(
+      typeof condition === "function" ? (e) => e.not(condition(e)) : (e) => e.not(condition),
+      (b) => b.exitRepeat()
+    );
+    block(this);
+    return this.endrepeat();
+  }
+  /**
+   * Iterate over items until a condition becomes true.
+   * Combines forEach with an early exit condition for cleaner syntax.
+   * @param variable Loop variable name
+   * @param list Expression for the list to iterate (e.g., 'every note')
+   * @param condition Condition to check before each iteration (exits when true)
+   * @param block Callback that builds the loop body
+   */
+  forEachUntil(variable, list, condition, block) {
+    this.repeatWith(variable, list);
+    this.ifThen(condition, (b) => b.exitRepeat());
+    block(this);
+    return this.endrepeat();
+  }
+  /**
+   * Repeat a fixed number of times with automatic block closing.
+   * @param times Number of times to repeat
+   * @param block Callback that builds the loop body
+   */
+  repeatTimes(times, block) {
+    this.repeat(times);
+    block(this);
+    return this.endrepeat();
+  }
+  /**
+   * Repeat while condition is true with automatic block closing.
+   * @param condition Condition to check (continues while true)
+   * @param block Callback that builds the loop body
+   */
+  repeatWhileBlock(condition, block) {
+    this.repeatWhile(condition);
+    block(this);
+    return this.endrepeat();
+  }
+  /**
+   * Repeat until condition is true with automatic block closing.
+   * @param condition Condition to check (continues until true)
+   * @param block Callback that builds the loop body
+   */
+  repeatUntilBlock(condition, block) {
+    this.repeatUntil(condition);
+    block(this);
+    return this.endrepeat();
+  }
+  /**
+   * Load an existing AppleScript into the builder, preserving its structure.
+   * Parses the script to detect block structure (tell, if, repeat, etc.) and
+   * maintains proper nesting so you can continue editing with the builder API.
+   * @param script The AppleScript source code to load
+   * @returns This builder instance for method chaining
+   */
+  loadFromScript(script) {
+    const lines = script.split("\n");
+    for (const line of lines) {
+      this.script.push(line);
+      const trimmed = line.trim().toLowerCase();
+      if (trimmed.startsWith("tell ") || /^tell application/.exec(trimmed)) {
+        const target = this.extractTarget(line);
+        this.pushBlock("tell", target);
+      } else if (trimmed.startsWith("if ")) {
+        this.pushBlock("if");
+      } else if (trimmed.startsWith("repeat ") || trimmed === "repeat" || trimmed.startsWith("repeat with ")) {
+        this.pushBlock("repeat");
+      } else if (trimmed === "try" || trimmed.startsWith("try ")) {
+        this.pushBlock("try");
+      } else if (trimmed.startsWith("on ") && !trimmed.startsWith("on error")) {
+        this.pushBlock("on");
+      } else if (trimmed.startsWith("considering ")) {
+        this.pushBlock("considering");
+      } else if (trimmed.startsWith("ignoring ")) {
+        this.pushBlock("ignoring");
+      } else if (trimmed.startsWith("using ")) {
+        this.pushBlock("using");
+      } else if (trimmed.startsWith("with ")) {
+        this.pushBlock("with");
+      } else if (trimmed === "end" || trimmed === "end tell" || trimmed === "end if" || trimmed === "end repeat" || trimmed === "end try" || trimmed === "end considering" || trimmed === "end ignoring" || trimmed === "end using" || trimmed === "end with" || trimmed.startsWith("end ")) {
+        this.popBlock();
+      }
+    }
+    return this;
+  }
+  /**
+   * Helper method to extract the target from a tell statement.
+   * @param line The tell statement line
+   * @returns The extracted target or undefined
+   */
+  extractTarget(line) {
+    const match = /tell\s+(?:application\s+)?"?([^"]+)"?/i.exec(line);
+    return match ? match[1].trim() : void 0;
+  }
+  build() {
+    this.validateBlockStack();
+    return this.script.join("\n");
+  }
+  reset() {
+    this.script = [];
+    this.indentLevel = 0;
+    this.blockStack = [];
+    return this;
+  }
+};
+var exec = util.promisify(child_process.exec);
+var ScriptExecutor = class _ScriptExecutor {
+  static buildFlags(options = {}) {
+    const flags = [];
+    if (options.language) {
+      flags.push(`-l ${options.language}`);
+    }
+    const outputFlags = [];
+    if (options.humanReadable !== false) outputFlags.push("h");
+    if (options.errorToStdout) outputFlags.push("o");
+    if (outputFlags.length > 0) {
+      flags.push(`-s ${outputFlags.join("")}`);
+    }
+    return flags.join(" ");
+  }
+  /**
+   * Execute an AppleScript or JavaScript string
+   *
+   * **Error Handling:**
+   * This method implements comprehensive error handling that safely extracts:
+   * - Error messages from any error type (Error, ErrnoException, etc.)
+   * - Exit codes with proper type checking and defaults
+   *
+   * **Important Notes:**
+   * - Script strings are automatically escaped for shell safety
+   * - Single quotes in scripts are escaped using the pattern: `'` -> `'"'"'`
+   * - Always returns a result object, never throws (errors are captured in result)
+   *
+   * @param script - The AppleScript or JavaScript code to execute
+   * @param options - Execution options (language, output format, etc.)
+   * @returns Promise resolving to execution result with success flag, output, error, and exit code
+   *
+   * @example
+   * ```typescript
+   * const result = await ScriptExecutor.execute('tell app "Finder" to get name');
+   * if (result.success) {
+   *   console.log(result.output); // "Finder"
+   * } else {
+   *   console.error(`Failed: ${result.error} (exit code: ${result.exitCode})`);
+   * }
+   * ```
+   */
+  static async execute(script, options = {}) {
+    try {
+      const flags = _ScriptExecutor.buildFlags(options);
+      const command = `osascript ${flags} -e '${script.replace(/'/g, `'"'"'`)}'`;
+      const { stdout } = await exec(command);
+      return {
+        success: true,
+        output: stdout.trim(),
+        exitCode: 0
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const errnoException = error;
+      const exitCode = typeof errnoException.code === "string" ? Number.parseInt(errnoException.code, 10) || 1 : typeof errnoException.code === "number" ? errnoException.code : 1;
+      return {
+        success: false,
+        output: null,
+        error: message,
+        exitCode
+      };
+    }
+  }
+  /**
+   * Execute an AppleScript or JavaScript file
+   *
+   * **Error Handling:**
+   * Uses the same robust error handling as `execute()` method.
+   * See {@link ScriptExecutor.execute} for details on error handling patterns.
+   *
+   * **Important Notes:**
+   * - File paths are passed directly to osascript (no shell escaping needed)
+   * - File must exist and be readable
+   * - Always returns a result object, never throws
+   *
+   * @param filePath - Path to the script file (.applescript, .scpt, etc.)
+   * @param options - Execution options (language, output format, etc.)
+   * @returns Promise resolving to execution result with success flag, output, error, and exit code
+   *
+   * @example
+   * ```typescript
+   * const result = await ScriptExecutor.executeFile('./scripts/my-script.applescript');
+   * if (result.success) {
+   *   console.log(result.output);
+   * }
+   * ```
+   */
+  static async executeFile(filePath, options = {}) {
+    try {
+      const flags = _ScriptExecutor.buildFlags(options);
+      const command = `osascript ${flags} "${filePath}"`;
+      const { stdout } = await exec(command);
+      return {
+        success: true,
+        output: stdout.trim(),
+        exitCode: 0
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const errnoException = error;
+      const exitCode = typeof errnoException.code === "string" ? Number.parseInt(errnoException.code, 10) || 1 : typeof errnoException.code === "number" ? errnoException.code : 1;
+      return {
+        success: false,
+        output: null,
+        error: message,
+        exitCode
+      };
+    }
+  }
+};
+var exec2 = util.promisify(child_process.exec);
+function buildCompileFlags(options) {
+  const flags = [];
+  if (options.language) {
+    flags.push(`-l ${options.language}`);
+  }
+  if (options.executeOnly) {
+    flags.push("-x");
+  }
+  if (options.stayOpen) {
+    flags.push("-s");
+  }
+  if (options.useStartupScreen) {
+    flags.push("-u");
+  }
+  return flags;
+}
+async function compileScript(script, options = {}) {
+  try {
+    const tmpId = crypto.randomBytes(8).toString("hex");
+    const sourcePath = path.join(os.tmpdir(), `script_${tmpId}.applescript`);
+    await promises.writeFile(sourcePath, script, "utf8");
+    const outputPath = options.outputPath ?? path.join(os.tmpdir(), `script_${tmpId}.scpt`);
+    const outputExt = options.bundleScript ? ".scptd" : ".scpt";
+    const finalOutputPath = outputPath.endsWith(outputExt) ? outputPath : `${outputPath}${outputExt}`;
+    const flags = buildCompileFlags(options);
+    const command = `osacompile ${flags.join(" ")} -o "${finalOutputPath}" "${sourcePath}"`;
+    await exec2(command);
+    return {
+      success: true,
+      outputPath: finalOutputPath
+    };
+  } catch (error) {
+    const err = error;
+    return {
+      success: false,
+      outputPath: "",
+      error: err.message
+    };
+  }
+}
+async function compileScriptFile(filePath, options = {}) {
+  try {
+    const outputPath = options.outputPath ?? filePath.replace(/\.[^.]+$/, ".scpt");
+    const outputExt = options.bundleScript ? ".scptd" : ".scpt";
+    const finalOutputPath = outputPath.endsWith(outputExt) ? outputPath : `${outputPath}${outputExt}`;
+    const flags = buildCompileFlags(options);
+    const command = `osacompile ${flags.join(" ")} -o "${finalOutputPath}" "${filePath}"`;
+    await exec2(command);
+    return {
+      success: true,
+      outputPath: finalOutputPath
+    };
+  } catch (error) {
+    const err = error;
+    return {
+      success: false,
+      outputPath: "",
+      error: err.message
+    };
+  }
+}
+var exec3 = util.promisify(child_process.exec);
+async function decompileScript(scriptPath) {
+  try {
+    const { stdout, stderr } = await exec3(`osadecompile "${scriptPath}"`);
+    if (stderr) {
+      return {
+        success: false,
+        error: stderr.trim()
+      };
+    }
+    return {
+      success: true,
+      source: stdout.trim()
+    };
+  } catch (error) {
+    const err = error;
+    return {
+      success: false,
+      error: err.message
+    };
+  }
+}
+var exec4 = util.promisify(child_process.exec);
+function parseCapabilityFlags(flags) {
+  return {
+    compiling: flags.includes("c"),
+    sourceData: flags.includes("g"),
+    coercion: flags.includes("x"),
+    eventHandling: flags.includes("e"),
+    recording: flags.includes("r"),
+    convenience: flags.includes("v"),
+    dialects: flags.includes("d"),
+    appleEvents: flags.includes("h")
+  };
+}
+async function getInstalledLanguages() {
+  const { stdout } = await exec4("osalang -L");
+  const lines = stdout.trim().split("\n").filter((line) => line.trim().length > 0);
+  return lines.map((line) => {
+    const [name, manufacturer, flags = "", ...descParts] = line.split(/\s+/);
+    const description = descParts.join(" ").replace(/\(([^)]+)\)/, "$1").trim();
+    return {
+      name,
+      subtype: name,
+      manufacturer,
+      capabilities: parseCapabilityFlags(flags),
+      description
+    };
+  });
+}
+async function getDefaultLanguage() {
+  const { stdout } = await exec4("osalang -d");
+  const defaultLang = stdout.trim();
+  const allLangs = await getInstalledLanguages();
+  return allLangs.find((lang) => lang.name === defaultLang) ?? allLangs[0];
+}
+async function loadScript(filePath) {
+  try {
+    const content = await promises.readFile(filePath, "utf-8");
+    const builder = new AppleScriptBuilder();
+    builder.loadFromScript(content);
+    return builder;
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Failed to load script from ${filePath}: ${error.message}`);
+    }
+    throw error;
+  }
+}
+var exec5 = util.promisify(child_process.exec);
+var sdefCache = /* @__PURE__ */ new Map();
+async function getSdef(appPath) {
+  try {
+    const { stdout } = await exec5(`sdef "${appPath}"`);
+    return stdout;
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Failed to get sdef for ${appPath}: ${error.message}`);
+    }
+    throw error;
+  }
+}
+function parseSdef(xml) {
+  const parser = new fastXmlParser.XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    textNodeName: "#text",
+    parseAttributeValue: false,
+    trimValues: true,
+    isArray: (name) => {
+      return [
+        "suite",
+        "class",
+        "command",
+        "enumeration",
+        "property",
+        "element",
+        "parameter",
+        "enumerator",
+        "type"
+      ].includes(name);
+    }
+  });
+  const parsed = parser.parse(xml);
+  const dictionary = parsed.dictionary;
+  if (!dictionary) {
+    throw new Error("Invalid sdef XML: missing dictionary root element");
+  }
+  const suites = [];
+  const suitesData = Array.isArray(dictionary.suite) ? (
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    dictionary.suite
+  ) : (
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    dictionary.suite ? (
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      [dictionary.suite]
+    ) : []
+  );
+  for (const suiteData of suitesData) {
+    const suite = {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+      name: suiteData["@_name"] ?? "",
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+      code: suiteData["@_code"] ?? "",
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+      description: suiteData["@_description"],
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      classes: parseClasses(suiteData.class),
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      commands: parseCommands(suiteData.command),
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      enumerations: parseEnumerations(suiteData.enumeration)
+    };
+    suites.push(suite);
+  }
+  return { suites };
+}
+function parseClasses(classesData) {
+  if (!classesData) return [];
+  const classes = Array.isArray(classesData) ? classesData : [classesData];
+  return classes.map((cls) => ({
+    name: cls["@_name"] ?? "",
+    code: cls["@_code"] ?? "",
+    description: cls["@_description"],
+    plural: cls["@_plural"],
+    inherits: cls["@_inherits"],
+    properties: parseProperties(cls.property),
+    elements: parseElements(cls.element)
+  }));
+}
+function parseProperties(propertiesData) {
+  if (!propertiesData) return [];
+  const properties = Array.isArray(propertiesData) ? propertiesData : [propertiesData];
+  return properties.map((prop) => ({
+    name: prop["@_name"] ?? "",
+    code: prop["@_code"] ?? "",
+    type: parseTypeInfo(prop["@_type"], prop.type),
+    access: prop["@_access"] ?? "rw",
+    description: prop["@_description"]
+  }));
+}
+function parseElements(elementsData) {
+  if (!elementsData) return [];
+  const elements = Array.isArray(elementsData) ? elementsData : [elementsData];
+  return elements.map((elem) => ({
+    type: elem["@_type"] ?? "",
+    access: elem["@_access"]
+  }));
+}
+function parseCommands(commandsData) {
+  if (!commandsData) return [];
+  const commands = Array.isArray(commandsData) ? commandsData : [commandsData];
+  return commands.map((cmd) => ({
+    name: cmd["@_name"] ?? "",
+    code: cmd["@_code"] ?? "",
+    description: cmd["@_description"],
+    directParameter: cmd["direct-parameter"] ? {
+      type: cmd["direct-parameter"]["@_type"] ?? "",
+      description: cmd["direct-parameter"]["@_description"]
+    } : void 0,
+    parameters: parseParameters(cmd.parameter),
+    result: cmd.result ? {
+      type: cmd.result["@_type"] ?? "",
+      description: cmd.result["@_description"]
+    } : void 0
+  }));
+}
+function parseParameters(parametersData) {
+  if (!parametersData) return [];
+  const parameters = Array.isArray(parametersData) ? parametersData : [parametersData];
+  return parameters.map((param) => ({
+    name: param["@_name"] ?? "",
+    code: param["@_code"] ?? "",
+    type: parseTypeInfo(param["@_type"], param.type),
+    optional: param["@_optional"] === "yes",
+    description: param["@_description"]
+  }));
+}
+function parseEnumerations(enumerationsData) {
+  if (!enumerationsData) return [];
+  const enumerations = Array.isArray(enumerationsData) ? enumerationsData : [enumerationsData];
+  return enumerations.map((enumData) => ({
+    name: enumData["@_name"] ?? "",
+    code: enumData["@_code"] ?? "",
+    enumerators: parseEnumerators(enumData.enumerator)
+  }));
+}
+function parseEnumerators(enumeratorsData) {
+  if (!enumeratorsData) return [];
+  const enumerators = Array.isArray(enumeratorsData) ? enumeratorsData : [enumeratorsData];
+  return enumerators.map((enumer) => ({
+    name: enumer["@_name"] ?? "",
+    code: enumer["@_code"] ?? "",
+    description: enumer["@_description"]
+  }));
+}
+function parseTypeInfo(typeAttr, typeElement) {
+  if (typeAttr) {
+    return { type: typeAttr };
+  }
+  if (typeElement) {
+    const types = Array.isArray(typeElement) ? typeElement : [typeElement];
+    const firstType = types[0];
+    return {
+      type: firstType["@_type"] ?? "any",
+      list: firstType["@_list"] === "yes"
+    };
+  }
+  return { type: "any" };
+}
+async function getApplicationDictionary(appPath, useCache = true) {
+  if (useCache && sdefCache.has(appPath)) {
+    const cached = sdefCache.get(appPath);
+    if (cached) return cached;
+  }
+  const xml = await getSdef(appPath);
+  const dictionary = parseSdef(xml);
+  if (useCache) {
+    sdefCache.set(appPath, dictionary);
+  }
+  return dictionary;
+}
+function clearSdefCache() {
+  sdefCache.clear();
+}
+function getAllCommands(dictionary) {
+  return dictionary.suites.flatMap((suite) => suite.commands);
+}
+function getAllClasses(dictionary) {
+  return dictionary.suites.flatMap((suite) => suite.classes);
+}
+function findCommand(dictionary, commandName) {
+  for (const suite of dictionary.suites) {
+    const command = suite.commands.find((cmd) => cmd.name === commandName);
+    if (command) return command;
+  }
+  return;
+}
+function findClass(dictionary, className) {
+  for (const suite of dictionary.suites) {
+    const cls = suite.classes.find((c) => c.name === className);
+    if (cls) return cls;
+  }
+  return;
+}
+
+// src/sources/index.ts
+var sources_exports = {};
+__export(sources_exports, {
+  applications: () => applications_exports,
+  system: () => system_exports,
+  windows: () => windows_exports
+});
+
+// src/sources/applications.ts
+var applications_exports = {};
+__export(applications_exports, {
+  activate: () => activate,
+  getAll: () => getAll,
+  getByName: () => getByName,
+  getFrontmost: () => getFrontmost,
+  hide: () => hide,
+  isRunning: () => isRunning,
+  launch: () => launch,
+  quit: () => quit,
+  show: () => show
+});
+async function getAll(includeBackgroundApps = false) {
+  const whereClause = includeBackgroundApps ? "" : " whose background only is false";
+  const script = createScript().tell("System Events").set("appsList", []).forEach(
+    "proc",
+    `every process${whereClause}`,
+    (b) => b.tryCatch(
+      (tryBlock) => tryBlock.setExpression("procName", (e) => e.property("proc", "name")).setExpression("procBundleId", (e) => e.property("proc", "bundle identifier")).setExpression("procPid", (e) => e.property("proc", "unix id")).setExpression("procVisible", (e) => e.property("proc", "visible")).setExpression("procFrontmost", (e) => e.property("proc", "frontmost")).setExpression("procWindowCount", (e) => e.count(e.property("proc", "windows"))).pickEndRecord("appsList", "proc", {
+        name: "procName",
+        bundleId: "procBundleId",
+        pid: "procPid",
+        visible: "procVisible",
+        frontmost: "procFrontmost",
+        windowCount: "procWindowCount"
+      }),
+      (catchBlock) => catchBlock.comment("Skip processes with errors")
+    )
+  ).returnAsJson("appsList", {
+    name: "name",
+    bundleId: "bundleId",
+    pid: "pid",
+    visible: "visible",
+    frontmost: "frontmost",
+    windowCount: "windowCount"
+  }).endtell();
+  const result = await ScriptExecutor.execute(script.build());
+  if (!result.success) {
+    throw new Error(`Failed to get applications: ${result.error}`);
+  }
+  return JSON.parse(result.output ?? "[]");
+}
+async function getFrontmost() {
+  const script = createScript().tell("System Events").setExpression("frontProc", "first process whose frontmost is true").returnJsonObject({
+    name: "name of frontProc",
+    bundleId: "bundle identifier of frontProc",
+    pid: "unix id of frontProc",
+    visible: "visible of frontProc",
+    frontmost: "true",
+    windowCount: "count of windows of frontProc"
+  }).endtell();
+  const result = await ScriptExecutor.execute(script.build());
+  if (!result.success) {
+    throw new Error(`Failed to get frontmost application: ${result.error}`);
+  }
+  return JSON.parse(result.output ?? "{}");
+}
+async function isRunning(appName) {
+  const escapedAppName = appName.replace(/"/g, '\\"');
+  const script = `
+    tell application "System Events"
+      return exists (processes where name is "${escapedAppName}")
+    end tell
+  `;
+  const result = await ScriptExecutor.execute(script);
+  return result.success && result.output === "true";
+}
+async function getByName(appName) {
+  const allApps = await getAll(true);
+  return allApps.find((app) => app.name === appName) ?? null;
+}
+async function activate(appName) {
+  const script = createScript().tell(appName).activate().endtell();
+  const result = await ScriptExecutor.execute(script.build());
+  if (!result.success) {
+    throw new Error(`Failed to activate ${appName}: ${result.error}`);
+  }
+}
+async function launch(appName) {
+  const script = createScript().tell(appName).launch().endtell();
+  const result = await ScriptExecutor.execute(script.build());
+  if (!result.success) {
+    throw new Error(`Failed to launch ${appName}: ${result.error}`);
+  }
+}
+async function quit(appName) {
+  const script = createScript().tell(appName).quit().endtell();
+  const result = await ScriptExecutor.execute(script.build());
+  if (!result.success) {
+    throw new Error(`Failed to quit ${appName}: ${result.error}`);
+  }
+}
+async function hide(appName) {
+  const script = createScript().tell("System Events").tell(`process "${appName.replace(/"/g, '\\"')}"`).raw("set visible to false").endtell().endtell();
+  const result = await ScriptExecutor.execute(script.build());
+  if (!result.success) {
+    throw new Error(`Failed to hide ${appName}: ${result.error}`);
+  }
+}
+async function show(appName) {
+  const script = createScript().tell("System Events").tell(`process "${appName.replace(/"/g, '\\"')}"`).raw("set visible to true").endtell().endtell();
+  const result = await ScriptExecutor.execute(script.build());
+  if (!result.success) {
+    throw new Error(`Failed to show ${appName}: ${result.error}`);
+  }
+}
+
+// src/sources/system.ts
+var system_exports = {};
+__export(system_exports, {
+  getClipboard: () => getClipboard,
+  getDisplays: () => getDisplays,
+  getInfo: () => getInfo,
+  getPath: () => getPath,
+  getUptime: () => getUptime,
+  getVolumes: () => getVolumes,
+  isDarkMode: () => isDarkMode,
+  setClipboard: () => setClipboard
+});
+async function getInfo() {
+  const script = `
+    set computerName to computer name of (system info)
+    set userName to short user name of (system info)
+    set osVersion to system version of (system info)
+
+    set homeDir to POSIX path of (path to home folder)
+
+    -- Get hostname via shell
+    set hostname to do shell script "hostname"
+
+    -- Get architecture via shell
+    set arch to do shell script "uname -m"
+
+    return "{" & \xAC
+      "\\"computerName\\":\\"" & computerName & "\\"," & \xAC
+      "\\"hostname\\":\\"" & hostname & "\\"," & \xAC
+      "\\"osVersion\\":\\"" & osVersion & "\\"," & \xAC
+      "\\"systemVersion\\":\\"" & osVersion & "\\"," & \xAC
+      "\\"userName\\":\\"" & userName & "\\"," & \xAC
+      "\\"homeDirectory\\":\\"" & homeDir & "\\"," & \xAC
+      "\\"architecture\\":\\"" & arch & "\\"" & \xAC
+      "}"
+  `;
+  const result = await ScriptExecutor.execute(script);
+  if (!result.success) {
+    throw new Error(`Failed to get system info: ${result.error}`);
+  }
+  return JSON.parse(result.output ?? "{}");
+}
+async function getVolumes() {
+  const script = createScript().tell("Finder").set("volumesList", []).forEach(
+    "aDisk",
+    "every disk",
+    (b) => b.tryCatch(
+      (tryBlock) => tryBlock.setExpression("diskName", (e) => e.property("aDisk", "name")).setExpression("diskCapacity", (e) => e.property("aDisk", "capacity")).setExpression("diskFreeSpace", (e) => e.property("aDisk", "free space")).setExpression("diskFormat", (e) => e.property("aDisk", "format")).setExpression("diskEjectable", (e) => e.property("aDisk", "ejectable")).raw("set diskUsed to diskCapacity - diskFreeSpace").setEndRecord("volumesList", {
+        name: "diskName",
+        capacity: "diskCapacity",
+        freeSpace: "diskFreeSpace",
+        usedSpace: "diskUsed",
+        format: "diskFormat",
+        ejectable: "diskEjectable"
+      }),
+      (catchBlock) => catchBlock.comment("Skip disks with errors")
+    )
+  ).returnAsJson("volumesList", {
+    name: "name",
+    capacity: "capacity",
+    freeSpace: "freeSpace",
+    usedSpace: "usedSpace",
+    format: "format",
+    ejectable: "ejectable"
+  }).endtell();
+  const result = await ScriptExecutor.execute(script.build());
+  if (!result.success) {
+    throw new Error(`Failed to get volumes: ${result.error}`);
+  }
+  return JSON.parse(result.output ?? "[]");
+}
+async function getDisplays() {
+  const script = `
+    do shell script "system_profiler SPDisplaysDataType | grep Resolution"
+  `;
+  const result = await ScriptExecutor.execute(script);
+  if (!result.success) {
+    return [
+      {
+        id: 1,
+        bounds: {
+          x: 0,
+          y: 0,
+          width: 0,
+          height: 0
+        }
+      }
+    ];
+  }
+  const lines = (result.output ?? "").split("\n");
+  const displays = lines.map((line, idx) => {
+    const match = /Resolution:\s+(\d+)\s+x\s+(\d+)/.exec(line);
+    if (match) {
+      return {
+        id: idx + 1,
+        bounds: {
+          x: 0,
+          y: 0,
+          width: Number.parseInt(match[1], 10),
+          height: Number.parseInt(match[2], 10)
+        }
+      };
+    }
+    return null;
+  }).filter((d) => d !== null);
+  return displays.length > 0 ? displays : [
+    {
+      id: 1,
+      bounds: {
+        x: 0,
+        y: 0,
+        width: 0,
+        height: 0
+      }
+    }
+  ];
+}
+async function getClipboard() {
+  const script = `
+    try
+      return the clipboard as text
+    on error
+      return ""
+    end try
+  `;
+  const result = await ScriptExecutor.execute(script);
+  if (!result.success) {
+    return "";
+  }
+  return result.output ?? "";
+}
+async function setClipboard(text) {
+  const script = createScript().raw(`set the clipboard to "${text.replace(/"/g, '\\"')}"`).build();
+  const result = await ScriptExecutor.execute(script);
+  if (!result.success) {
+    throw new Error(`Failed to set clipboard: ${result.error}`);
+  }
+}
+async function getPath(folder) {
+  const folderMap = {
+    home: "home folder",
+    desktop: "desktop folder",
+    documents: "documents folder",
+    downloads: "downloads folder",
+    applications: "applications folder",
+    library: "library folder",
+    "temporary items": "temporary items folder",
+    music: "music folder",
+    pictures: "pictures folder",
+    movies: "movies folder",
+    public: "public folder"
+  };
+  const folderName = folderMap[folder] || "home folder";
+  const script = `POSIX path of (path to ${folderName})`;
+  const result = await ScriptExecutor.execute(script);
+  if (!result.success) {
+    throw new Error(`Failed to get path for ${folder}: ${result.error}`);
+  }
+  return (result.output ?? "").trim();
+}
+async function isDarkMode() {
+  const script = 'tell application "System Events" to tell appearance preferences to return dark mode';
+  const result = await ScriptExecutor.execute(script);
+  return result.success && (result.output ?? "").trim() === "true";
+}
+async function getUptime() {
+  const script = `do shell script "sysctl -n kern.boottime | awk '{print $4}' | sed 's/,//'"`;
+  const result = await ScriptExecutor.execute(script);
+  if (!result.success) {
+    throw new Error(`Failed to get uptime: ${result.error}`);
+  }
+  const bootTime = Number.parseInt((result.output ?? "0").trim(), 10);
+  const now = Math.floor(Date.now() / 1e3);
+  const validBootTime = Number.isNaN(bootTime) ? 0 : bootTime;
+  return now - validBootTime;
+}
+
+// src/sources/windows.ts
+var windows_exports = {};
+__export(windows_exports, {
+  getAll: () => getAll2,
+  getByApp: () => getByApp,
+  getCountByApp: () => getCountByApp,
+  getFrontmost: () => getFrontmost2
+});
+async function getAll2() {
+  const script = createScript().tell("System Events").set("windowsList", []).forEach(
+    "proc",
+    "every process whose visible is true",
+    (b) => b.setExpression("appName", (e) => e.property("proc", "name")).forEach(
+      "win",
+      "windows of proc",
+      (inner) => inner.tryCatch(
+        (tryBlock) => tryBlock.setExpression("winName", (e) => e.property("win", "name")).setExpression("winId", (e) => e.property("win", "id")).setExpression("winBounds", (e) => e.property("win", "position")).setExpression("winSize", (e) => e.property("win", "size")).setExpression(
+          "winMinimized",
+          (e) => e.property("win", 'value of attribute "AXMinimized"')
+        ).setExpression(
+          "winZoomed",
+          (e) => e.property("win", 'value of attribute "AXFullScreen"')
+        ).setEndRecord("windowsList", {
+          name: "winName",
+          app: "appName",
+          id: "winId",
+          x: "item 1 of winBounds",
+          y: "item 2 of winBounds",
+          width: "item 1 of winSize",
+          height: "item 2 of winSize",
+          minimized: "winMinimized",
+          zoomed: "winZoomed",
+          visible: "true"
+        }),
+        (catchBlock) => catchBlock.comment("Skip windows with errors")
+      )
+    )
+  ).returnAsJson("windowsList", {
+    name: "name",
+    app: "app",
+    id: "id",
+    x: "x",
+    y: "y",
+    width: "width",
+    height: "height",
+    minimized: "minimized",
+    zoomed: "zoomed",
+    visible: "visible"
+  }).endtell();
+  const result = await ScriptExecutor.execute(script.build());
+  if (!result.success) {
+    throw new Error(`Failed to get windows: ${result.error}`);
+  }
+  const windows = JSON.parse(result.output ?? "[]");
+  return windows.map((win) => {
+    const w = win;
+    return {
+      name: w.name ?? "",
+      app: w.app ?? "",
+      id: Number(w.id ?? 0),
+      bounds: {
+        x: Number(w.x ?? 0),
+        y: Number(w.y ?? 0),
+        width: Number(w.width ?? 0),
+        height: Number(w.height ?? 0)
+      },
+      minimized: Boolean(w.minimized),
+      zoomed: Boolean(w.zoomed),
+      visible: Boolean(w.visible)
+    };
+  });
+}
+async function getByApp(appName) {
+  const allWindows = await getAll2();
+  return allWindows.filter((win) => win.app === appName);
+}
+async function getFrontmost2() {
+  const script = `
+    tell application "System Events"
+      set frontApp to name of first process whose frontmost is true
+      tell process frontApp
+        try
+          set frontWin to front window
+          set winName to name of frontWin
+          set winBounds to position of frontWin
+          set winSize to size of frontWin
+          set winMinimized to value of attribute "AXMinimized" of frontWin
+          set winZoomed to value of attribute "AXFullScreen" of frontWin
+
+          return "{" & \xAC
+            "\\"name\\":\\"" & winName & "\\"," & \xAC
+            "\\"app\\":\\"" & frontApp & "\\"," & \xAC
+            "\\"x\\":" & (item 1 of winBounds) & "," & \xAC
+            "\\"y\\":" & (item 2 of winBounds) & "," & \xAC
+            "\\"width\\":" & (item 1 of winSize) & "," & \xAC
+            "\\"height\\":" & (item 2 of winSize) & "," & \xAC
+            "\\"minimized\\":" & winMinimized & "," & \xAC
+            "\\"zoomed\\":" & winZoomed & "," & \xAC
+            "\\"visible\\":true" & \xAC
+            "}"
+        on error
+          return ""
+        end try
+      end tell
+    end tell
+  `;
+  const result = await ScriptExecutor.execute(script);
+  if (!(result.success && result.output)) {
+    return null;
+  }
+  try {
+    const win = JSON.parse(result.output);
+    return {
+      name: win.name ?? "",
+      app: win.app ?? "",
+      id: 0,
+      // Frontmost window query doesn't include ID
+      bounds: {
+        x: Number(win.x ?? 0),
+        y: Number(win.y ?? 0),
+        width: Number(win.width ?? 0),
+        height: Number(win.height ?? 0)
+      },
+      minimized: Boolean(win.minimized),
+      zoomed: Boolean(win.zoomed),
+      visible: Boolean(win.visible)
+    };
+  } catch {
+    return null;
+  }
+}
+async function getCountByApp() {
+  const allWindows = await getAll2();
+  const counts = {};
+  for (const win of allWindows) {
+    counts[win.app] = (counts[win.app] || 0) + 1;
+  }
+  return counts;
+}
+
+// src/validator.ts
+var ScriptValidator = class _ScriptValidator {
+  dictionary;
+  appName;
+  constructor(dictionary, appName) {
+    this.dictionary = dictionary;
+    this.appName = appName;
+  }
+  /**
+   * Create a validator for a specific application
+   */
+  static async forApplication(appPath) {
+    const dictionary = await getApplicationDictionary(appPath);
+    const appName = appPath.split("/").pop()?.replace(/\.app$/, "") ?? "Unknown";
+    return new _ScriptValidator(dictionary, appName);
+  }
+  /**
+   * Validate a script string
+   */
+  validate(script, options = {}) {
+    const { strictness = "normal", provideSuggestions = true } = options;
+    const issues = [];
+    const tellBlocks = this.extractTellBlocks(script);
+    for (const block of tellBlocks) {
+      this.validateCommands(block.content, issues, provideSuggestions);
+      this.validateProperties(block.content, issues, provideSuggestions);
+    }
+    const errors = issues.filter((i) => i.severity === "error");
+    const warnings = issues.filter((i) => i.severity === "warning");
+    const info = issues.filter((i) => i.severity === "info");
+    let valid = errors.length === 0;
+    if (strictness === "strict") {
+      valid = valid && warnings.length === 0;
+    }
+    return {
+      valid,
+      issues,
+      errors,
+      warnings,
+      info
+    };
+  }
+  /**
+   * Extract tell application blocks from script
+   */
+  extractTellBlocks(script) {
+    const blocks = [];
+    const lines = script.split("\n");
+    let currentBlock = null;
+    let blockDepth = 0;
+    for (const line of lines) {
+      const trimmed = line.trim();
+      const tellMatch = /^tell\s+application\s+"([^"]+)"/i.exec(trimmed);
+      if (tellMatch) {
+        const target = tellMatch[1];
+        if (currentBlock) {
+          blockDepth++;
+        } else {
+          currentBlock = { target, content: "", depth: 0 };
+        }
+        continue;
+      }
+      if (/^end\s+tell/i.test(trimmed)) {
+        if (blockDepth > 0) {
+          blockDepth--;
+        } else if (currentBlock) {
+          blocks.push(currentBlock);
+          currentBlock = null;
+        }
+        continue;
+      }
+      if (currentBlock) {
+        currentBlock.content += line + "\n";
+      }
+    }
+    return blocks;
+  }
+  /**
+   * Validate commands in script content
+   */
+  validateCommands(content, issues, provideSuggestions) {
+    const lines = content.split("\n");
+    const keywords = /* @__PURE__ */ new Set([
+      "if",
+      "then",
+      "else",
+      "end",
+      "repeat",
+      "tell",
+      "to",
+      "of",
+      "on",
+      "return",
+      "try",
+      "error",
+      "set",
+      "get",
+      "copy",
+      "count",
+      "exit",
+      "considering",
+      "ignoring",
+      "with",
+      "without",
+      "using",
+      "my",
+      "its",
+      "a",
+      "an",
+      "the",
+      "some",
+      "every",
+      "whose"
+    ]);
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("--")) continue;
+      const words = trimmed.split(/\s+/);
+      if (words.length === 0) continue;
+      const potentialCommand = words[0].toLowerCase();
+      if (keywords.has(potentialCommand)) continue;
+      if (/^[a-z_][a-z0-9_]*$/i.test(potentialCommand)) {
+        const command = findCommand(this.dictionary, potentialCommand);
+        if (!command) {
+          const issue = {
+            severity: "warning",
+            message: `Command '${potentialCommand}' might not exist in ${this.appName}`,
+            code: "unknown-command"
+          };
+          if (provideSuggestions) {
+            const suggestion = this.suggestSimilarCommand(potentialCommand);
+            if (suggestion) {
+              issue.suggestion = `Did you mean '${suggestion.name}'? ${suggestion.description ?? ""}`;
+            }
+          }
+          issues.push(issue);
+        }
+      }
+    }
+  }
+  /**
+   * Validate property access in script content
+   */
+  validateProperties(content, issues, _provideSuggestions) {
+    const setPattern = /set\s+([\w\s]+?)\s+(?:of\s+|to\s+)/gi;
+    let match;
+    while ((match = setPattern.exec(content)) !== null) {
+      const propertyName = match[1].trim();
+      if (propertyName && propertyName.length > 0) {
+        const readOnlyProp = this.findReadOnlyProperty(propertyName);
+        if (readOnlyProp) {
+          issues.push({
+            severity: "error",
+            message: `Property '${propertyName}' is read-only and cannot be set`,
+            code: "readonly-property",
+            suggestion: `Property '${propertyName}' in class '${readOnlyProp.className}' has access level 'r' (read-only)`
+          });
+        }
+      }
+    }
+  }
+  /**
+   * Find a read-only property by name across all classes
+   */
+  findReadOnlyProperty(propertyName) {
+    const classes = getAllClasses(this.dictionary);
+    for (const cls of classes) {
+      const prop = cls.properties.find(
+        (p) => p.name.toLowerCase() === propertyName.toLowerCase() && p.access === "r"
+      );
+      if (prop) {
+        return { className: cls.name, property: prop };
+      }
+    }
+    return null;
+  }
+  /**
+   * Suggest a similar command name using string similarity
+   */
+  suggestSimilarCommand(commandName) {
+    const allCommands = this.dictionary.suites.flatMap((suite) => suite.commands);
+    let bestMatch;
+    let bestScore = Number.POSITIVE_INFINITY;
+    for (const cmd of allCommands) {
+      const distance = this.levenshteinDistance(commandName.toLowerCase(), cmd.name.toLowerCase());
+      if (distance < bestScore && distance <= 3) {
+        bestScore = distance;
+        bestMatch = cmd;
+      }
+    }
+    return bestMatch;
+  }
+  /**
+   * Calculate Levenshtein distance between two strings
+   */
+  levenshteinDistance(a, b) {
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++) {
+      matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+      matrix[0][j] = j;
+    }
+    for (let i = 1; i <= b.length; i++) {
+      for (let j = 1; j <= a.length; j++) {
+        if (b.charAt(i - 1) === a.charAt(j - 1)) {
+          matrix[i][j] = matrix[i - 1][j - 1];
+        } else {
+          matrix[i][j] = Math.min(
+            matrix[i - 1][j - 1] + 1,
+            // substitution
+            matrix[i][j - 1] + 1,
+            // insertion
+            matrix[i - 1][j] + 1
+            // deletion
+          );
+        }
+      }
+    }
+    return matrix[b.length][a.length];
+  }
+  /**
+   * Validate a command and its parameters
+   */
+  validateCommand(commandName, parameters = {}) {
+    const issues = [];
+    const command = findCommand(this.dictionary, commandName);
+    if (!command) {
+      issues.push({
+        severity: "error",
+        message: `Command '${commandName}' does not exist in ${this.appName}`,
+        code: "unknown-command"
+      });
+      return issues;
+    }
+    const requiredParams = command.parameters.filter((p) => !p.optional);
+    for (const param of requiredParams) {
+      if (!(param.name in parameters)) {
+        issues.push({
+          severity: "error",
+          message: `Required parameter '${param.name}' is missing for command '${commandName}'`,
+          code: "missing-parameter",
+          suggestion: param.description
+        });
+      }
+    }
+    for (const paramName of Object.keys(parameters)) {
+      const paramDef = command.parameters.find((p) => p.name === paramName);
+      if (!paramDef) {
+        issues.push({
+          severity: "warning",
+          message: `Unknown parameter '${paramName}' for command '${commandName}'`,
+          code: "unknown-parameter"
+        });
+      }
+    }
+    return issues;
+  }
+  /**
+   * Validate property access on a class
+   */
+  validatePropertyAccess(className, propertyName, accessType) {
+    const issues = [];
+    const cls = findClass(this.dictionary, className);
+    if (!cls) {
+      issues.push({
+        severity: "error",
+        message: `Class '${className}' does not exist in ${this.appName}`,
+        code: "unknown-class"
+      });
+      return issues;
+    }
+    const property = cls.properties.find((p) => p.name === propertyName);
+    if (!property) {
+      issues.push({
+        severity: "error",
+        message: `Property '${propertyName}' does not exist on class '${className}'`,
+        code: "unknown-property"
+      });
+      return issues;
+    }
+    if (accessType === "write" && property.access === "r") {
+      issues.push({
+        severity: "error",
+        message: `Property '${propertyName}' is read-only on class '${className}'`,
+        code: "readonly-property",
+        suggestion: `Property has access level 'r'. Available properties with write access: ${cls.properties.filter((p) => p.access === "rw").map((p) => p.name).join(", ")}`
+      });
+    }
+    return issues;
+  }
+  /**
+   * Get all available commands in the application
+   */
+  getAvailableCommands() {
+    return this.dictionary.suites.flatMap((suite) => suite.commands);
+  }
+  /**
+   * Get all available classes in the application
+   */
+  getAvailableClasses() {
+    return getAllClasses(this.dictionary);
+  }
+};
+async function validateScript(script, appPath, options) {
+  const validator = await ScriptValidator.forApplication(appPath);
+  return validator.validate(script, options);
+}
+
+// src/index.ts
+var createScript = () => new AppleScriptBuilder();
+async function runScript(script, options) {
+  const scriptString = typeof script === "string" ? script : script.build();
+  const result = await ScriptExecutor.execute(scriptString, options);
+  if (result.success && result.output) {
+    const trimmed = result.output.trim();
+    if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+      try {
+        const parsed = JSON.parse(result.output);
+        const parsedResult = {
+          success: result.success,
+          output: parsed,
+          exitCode: result.exitCode
+        };
+        return parsedResult;
+      } catch {
+      }
+    }
+  }
+  return result;
+}
+var runScriptFile = async (filePath, options) => ScriptExecutor.executeFile(filePath, options);
+
+exports.AppleScriptBuilder = AppleScriptBuilder;
+exports.ExprBuilder = ExprBuilder;
+exports.ScriptExecutor = ScriptExecutor;
+exports.ScriptValidator = ScriptValidator;
+exports.clearSdefCache = clearSdefCache;
+exports.compileScript = compileScript;
+exports.compileScriptFile = compileScriptFile;
+exports.createScript = createScript;
+exports.decompileScript = decompileScript;
+exports.expr = expr;
+exports.findClass = findClass;
+exports.findCommand = findCommand;
+exports.getAllClasses = getAllClasses;
+exports.getAllCommands = getAllCommands;
+exports.getApplicationDictionary = getApplicationDictionary;
+exports.getDefaultLanguage = getDefaultLanguage;
+exports.getInstalledLanguages = getInstalledLanguages;
+exports.getSdef = getSdef;
+exports.loadScript = loadScript;
+exports.parseSdef = parseSdef;
+exports.runScript = runScript;
+exports.runScriptFile = runScriptFile;
+exports.sources = sources_exports;
+exports.validateScript = validateScript;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map