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: AppleScript source composition, from script-object algebra to NSAppleEventDescriptor surgery.
• [02]-RUNTIME: osascript execution, compilation, and packaging, with AppleScript and JXA as language rows.
• [03]-EMBEDDING: OSAKit embedded in a Cocoa host, bound directly to the Apple Event ABI.
• [04]-EVENTS: Apple Event wire ABI — descriptor construction, addressing, and the send surface.
• [05]-DISTRIBUTION: packaging and the observation rails that carry an artifact into production.

[TEMPLATES]:

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

[EXAMPLES]:

• [01]-CHEVRON_DISPATCH: chevron-literal dispatch rail electing raw send or dictionary term per verb.
• [02]-COCOA_SCRIPTING_SERVER: server-side specifier resolution served from the receiver's own index.
• [03]-OBJC_FFI_BRIDGE: JXA-to-C FFI boundary at composed scale over one declared ABI table.
• [04]-OSAKIT_REENTRANCY: suspend-rebind-resume path for an event that re-enters its own host.
• [05]-SDEF_ROUTING: 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.

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.

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.

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.

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

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.

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.

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.

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