Coding Applescript

---
name: coding-applescript
description: >-
    Scripted actions in macOS — an app's scripting dictionary, Apple Event wire ABI under
    it, and the Objective-C bridge opening Cocoa and Foundation to JXA. Drives native machine
    and app state and data, resolves terminology via installed dictionary, provides capability
    as an agent-callable tool returning a typed JSON envelope, embeds OSA in a Cocoa host,
    runs unattended via launchd, ships packaged applets, and authors sdef that makes an
    app scriptable. Use whenever interacting with macOS applications, programmatic native
    scripting, or whenever a capability should become a reusable tool, and for writing or
    reviewing AppleScript, JXA, or `osascript`. Shell-only scripting belongs to coding-bash.
---

# [CODING_APPLESCRIPT]

AppleScript is an object-specifier compiler over the Apple Event ABI: a production artifact treats the language as a descriptor DSL, keeps process invocation outside script bodies, and returns typed receipts. This machine runs with automation privilege already granted. Every send, probe, and host reaches its target directly: never author a consent preflight, an entitlement check, a privilege fallback, or a denial branch, and never raise the subject in prose or receipts.

[AUTOMATION_LAW]:
- User values reach a script as escaped literals inside closed templates, never as concatenated source.
- Terminology resolves against the installed target dictionary at run time, never from recall.
- A send that fails resolves against the target's dictionary and the descriptor actually built, never against an assumed verb.

Application automation through object specifiers and Foundation bridge calls stay separate owner rows, because JXA specifiers, Objective-C objects, and JavaScript values obey different coercion rules.

## [01]-[ROUTING]

[REFERENCES]:
- [01]-[LANGUAGE](references/language.md): AppleScript source composition, from script-object algebra to `NSAppleEventDescriptor` surgery.
- [02]-[RUNTIME](references/runtime.md): `osascript` execution, compilation, and packaging, with AppleScript and JXA as language rows.
- [03]-[EMBEDDING](references/embedding.md): `OSAKit` embedded in a Cocoa host, bound directly to the Apple Event ABI.
- [04]-[EVENTS](references/events.md): Apple Event wire ABI — descriptor construction, addressing, and the send surface.
- [05]-[DISTRIBUTION](references/distribution.md): packaging and the observation rails that carry an artifact into production.

[TEMPLATES]:
- [01]-[RUNNER](templates/osascript-runner.sh): `osascript` dispatch shell — argv marshalling, typed receipt, one exit contract.
- [02]-[OSA_TOOL](templates/osa-tool.js): agent-tool skeleton across the OSA host set, argv in and one typed JSON envelope out.
- [03]-[COMPILED_LIBRARY](templates/applescript-library.applescript): reusable script object compiled to a `.scpt`/`.scptd` handler library.
- [04]-[APPLET](templates/applet.sh): script-app build driving `osacompile` output to a distributable bundle.
- [05]-[LAUNCHD_AGENT](templates/launchd-osa-agent.plist): unattended launchd user agent driving one OSA artifact on one trigger.
- [06]-[OSAKIT_HOST](templates/osakit-host.swift): OSAKit host skeleton — one language instance owning every script behind a marshal boundary.
- [07]-[SCRIPTABLE_SDEF](templates/scriptable-app.sdef): dictionary spine of a scriptable app, one suite's terminology bound to cocoa keys.

[EXAMPLES]:
- [01]-[CHEVRON_DISPATCH](examples/chevron-dispatch.applescript): chevron-literal dispatch rail electing raw send or dictionary term per verb.
- [02]-[COCOA_SCRIPTING_SERVER](examples/cocoa-scripting-server.swift): server-side specifier resolution served from the receiver's own index.
- [03]-[OBJC_FFI_BRIDGE](examples/objc-ffi-bridge.js): JXA-to-C FFI boundary at composed scale over one declared ABI table.
- [04]-[OSAKIT_REENTRANCY](examples/osakit-reentrancy.swift): suspend-rebind-resume path for an event that re-enters its own host.
- [05]-[SDEF_ROUTING](examples/sdef-routing.js): verb-set routing against the installed dictionary before any send.

## [02]-[ARTIFACT_SPINE]

Every OSA artifact carries one system-owned type identity binding symbol, UTI, extension, and conformance:

| [INDEX] | [ROLE]          | [SYMBOL]                   | [UTI]                                 | [EXTENSION]    | [CONFORMANCE]        |
| :-----: | :-------------- | :------------------------- | :------------------------------------ | :------------- | :------------------- |
|  [01]   | Source text     | `UTType.appleScript`       | `com.apple.applescript.text`          | `.applescript` | `public.script`      |
|  [02]   | Compiled script | `UTType.osaScript`         | `com.apple.applescript.script`        | `.scpt`        | `public.data`        |
|  [03]   | Script bundle   | `UTType.osaScriptBundle`   | `com.apple.applescript.script-bundle` | `.scptd`       | `com.apple.bundle`   |
|  [04]   | Coarse import   | `UTType.script`            | `public.script`                       | none           | self                 |
|  [05]   | JXA source      | `UTType.javaScript`        | `com.netscape.javascript-source`      | `.js`          | `public.source-code` |
|  [06]   | Saved applet    | `UTType.applicationBundle` | `com.apple.application-bundle`        | `.app`         | `com.apple.bundle`   |

A saved applet or droplet carries the ordinary application identity, so applet-ness rides the OSAKit storage type baked into the bundle at compile time and the applet stub Mach-O at `Contents/MacOS`. Compiled JXA reuses `com.apple.applescript.script` and its legacy `osas` OSType, so discrimination between a compiled AppleScript and a compiled JXA script is an `osalang` or component-identifier probe, never a UTI comparison.

```swift conceptual
import UniformTypeIdentifiers

enum ScriptArtifact: String, CaseIterable {
    case source = "com.apple.applescript.text"
    case compiled = "com.apple.applescript.script"
    case bundle = "com.apple.applescript.script-bundle"

    var type: UTType { UTType(rawValue)! }
    var extensionHint: String {
        switch self {
        case .source: "applescript"
        case .compiled: "scpt"
        case .bundle: "scptd"
        }
    }
}
```

## [03]-[EXPORT_AND_PACKAGE_SHAPE]

`UTExportedTypeDeclarations` binds only a tool minting a new script-adjacent document type; a runner, editor, or workflow action consuming the existing spine declares `CFBundleDocumentTypes` and `LSItemContentTypes` against the system-owned identifiers, never a parallel exported UTI. `.scptd` is the polymorphic artifact for embedded resources, script libraries, localized dictionaries, and bundle metadata — a flat `.scpt` earns deploy-target status only when the script owns no resource lookup, embedded library, or localized asset. A release rail stores `.applescript` as the source form.

## [04]-[OSA_HOST_DISPATCH]

A stdin script that needs arguments runs as `osascript - scriptArg...`; filename-free stdin consumes the script body and leaves no positional path slot for the argument vector. A reusable core normalizes every ingress before domain logic runs.

```applescript conceptual
on normalize(payload)
	if class of payload is list then return payload
	return {payload}
end normalize

on run argv
	return handleWork(normalize(argv), {host:"osascript"})
end run

on open droppedItems
	return handleWork(normalize(droppedItems), {host:"droplet"})
end open
```

## [05]-[BUNDLE_AND_LIBRARY_OWNERSHIP]

A script bundle places executable OSA code at `Contents/Resources/Scripts/main.scpt`; resource lookup uses bundle-relative locations, and path construction inside the bundle never assumes a Finder-visible package layout. Script Editor's bundle contents pane authors bundle metadata, while a build rail mutates the same values through `Info.plist` and bundle files directly and reopens Script Editor only for event-log and dictionary inspection.

A script library loads from `~/Library/Script Libraries/`, `/Library/Script Libraries/`, or the `Resources` folder inside the calling script or app bundle — an applet depending on a private library vendors it inside its own bundle and resolves it by name from the resource domain. A cross-language library exposes stable handler names and restricts payloads to OSA-coercible values.

## [06]-[AUTOMATOR_SURFACES]

Automator's `Run AppleScript` action receives and returns `com.apple.applescript.object` list payloads through `on run {input, parameters}`; the action body is a workflow transform, so it returns the downstream payload explicitly rather than falling through. `Run JavaScript` uses `function run(input, parameters)`, and JXA action code returns ordinary JavaScript values only when the next action in the chain coerces them through the OSA object bridge.

```applescript conceptual
on run {input, parameters}
	set rows to {}
	repeat with itemRef in input
		set end of rows to itemRef as text
	end repeat
	return rows
end run
```

## [07]-[SHORTCUTS_SURFACES]

A global `Allow Running Scripts` switch under Shortcuts Advanced settings gates the privileged bridge actions — Run AppleScript, Run Shell Script, Run JavaScript for Mac Automation, Run JavaScript on Web Page, Run Script Over SSH — executing with full user privileges outside normal action guardrails.

External Shortcuts automation enters through the `shortcuts` CLI or the `Shortcuts Events` scripting dictionary. `tell application "Shortcuts Events" to run shortcut ... with input ...` dispatches in the background without fronting the Shortcuts UI, while `tell application "Shortcuts"` launches the app. `--input-path` and `--output-path` repeat, accept `-` for stdin and stdout, and expand shell globs; `--output-type` takes a UTI inferred from the output filename when omitted.

| [INDEX] | [VERB] | [ROLE]                   | [IPC_SURFACE]                                  |
| :-----: | :----- | :----------------------- | :--------------------------------------------- |
|  [01]   | `run`  | executes one shortcut    | `--input-path` `--output-path` `--output-type` |
|  [02]   | `list` | enumerates installed set | none                                           |
|  [03]   | `view` | opens the editor         | none                                           |
|  [04]   | `sign` | signs for distribution   | `--mode` `-i` `-o`                             |

`shortcuts sign --mode anyone` submits the shortcut to Apple's network-bound signing service, which validates it against tampering for open sharing — a rail distinct from Developer ID notarization — and `--mode people-who-know-me` signs with the sender's iCloud identity for contact-gated import; a hardened install imports a signed `.shortcut` alone.

```applescript conceptual
tell application "Shortcuts Events"
	run shortcut "Normalize Intake" with input {"alpha", "beta"}
end tell
```

```bash copy-safe
shortcuts run "Normalize Intake" --input-path - --output-path - --output-type public.plain-text
shortcuts sign --mode people-who-know-me -i Intake.shortcut -o Intake-signed.shortcut
```

## [08]-[APP_INTENTS_SUCCESSOR]

App Intents is the sanctioned automation successor, reached only through an enclosing Shortcut — no CLI verb invokes an App Intent directly, and no AppleScript-to-intent bridge exists. An app shipping App Intents contributes Shortcuts actions that also run from Siri and Spotlight as first-class results; the Apple Intelligence `Use Model` action reasons over app-exposed entities inside the same Shortcut.

A shortcut composes `Run AppleScript` alongside App-Intent actions in one flow, so an AppleScript rail reaches App Intents by running that enclosing shortcut through `Shortcuts Events` or `shortcuts run`, never an intent as a standalone target.

Personal automations add folder-change, external-drive, Wi-Fi, display, and app-launch triggers on the Mac, replacing Folder Actions and stay-open pollers wherever the trigger is a first-class Shortcuts event; OSA hosts remain the owning surface for scriptable-app control whose dictionary outreaches the app's App Intents surface, for triggers Shortcuts does not model, and for latency-sensitive in-process work.

## [09]-[FOLDER_ACTIONS_STAYOPEN_DROPLETS]

Every Folder Action handler parameter is required, no handler returns a value, and the attached folder rides as the direct parameter.

```applescript conceptual
on adding folder items to thisFolder after receiving addedItems
	repeat with addedItem in addedItems
		my processAddedItem(thisFolder, addedItem)
	end repeat
end adding folder items to
```

A hot folder drains itself or moves accepted work into a terminal subfolder; leaving processed files in the watched root repeats work and degrades Folder Actions throughput. `moving folder window for` is an opt-in contract unreliable across installed hosts, so window-position automation belongs in a stay-open app. A stay-open app owns periodic work through `idle`, which returns the next polling interval in seconds, and releases resources in `quit`.

```applescript conceptual
property pending : {}

on idle
	set pending to my drainQueue(pending)
	return 15
end idle

on quit
	set pending to {}
	continue quit
end quit
```

A droplet routes Finder drops through AppleScript `open` or JXA `openDocuments`, and its root `run` path stays a diagnostic entrypoint that calls the same processing kernel against a manually selected file. Script Menu runs compiled scripts, applets, shell scripts, and Automator workflows from `~/Library/Scripts/` and optionally `/Library/Scripts/`; application-specific entries live under `Scripts/Applications/<ApplicationName>` and surface only while that application is frontmost.

## [10]-[MAIL_RULE_SCRIPTS]

A Mail rule script implements `perform mail action with messages`, whose direct parameter is a message list; `in mailboxes` appears for a menu-invoked script and `for rule` appears for a rule-invoked script. That handler wraps in `using terms from application "Mail"` so compilation succeeds outside Mail while preserving Mail's own command terminology and parameter labels.

```applescript conceptual
using terms from application "Mail"
	on perform mail action with messages theseMessages for rule theRule
		tell application "Mail"
			repeat with eachMessage in theseMessages
				set read status of eachMessage to true
			end repeat
		end tell
	end perform mail action with messages
end using terms from
```

## [11]-[HOST_DISPATCH_MATRIX]

Foundation scripting support exposes app scriptability through `NSScriptCommand`, `NSScriptObjectSpecifier`, `NSScriptClassDescription`, `NSScriptExecutionContext`, and a `.sdef` dictionary, so a Cocoa app's scriptability is a model contract rather than a string-command adapter.

Every automation host binds handler signature and result transport as one policy row a caller resolves before authoring a script:

| [INDEX] | [HOST]             | [ENTRY]                     | [PAYLOAD]         | [EXIT]           |
| :-----: | :----------------- | :-------------------------- | :---------------- | :--------------- |
|  [01]   | `osascript`        | `run argv`                  | string list       | stdout status    |
|  [02]   | Automator          | `run {input, parameters}`   | OSA object list   | OSA object list  |
|  [03]   | Shortcuts action   | `run(input, parameters)`    | shortcut input    | action output    |
|  [04]   | Shortcuts external | `shortcuts run`             | typed output      | CLI result       |
|  [05]   | Applet             | `run` handler               | none              | app lifecycle    |
|  [06]   | Droplet            | `open` handler              | Finder aliases    | none             |
|  [07]   | Folder Action      | folder handlers             | folder parameters | none             |
|  [08]   | Mail rule          | `perform mail action`       | message list      | none             |
|  [09]   | Stay-open agent    | `idle` `quit`               | script properties | next interval    |
|  [10]   | Script Menu        | file launch                 | script app shell  | host-defined     |
|  [11]   | Native host        | `NSAppleScript` `OSAScript` | source data event | descriptor error |