[fredsimard]

Closes #5.

What this adds

A .wildCard return type, for the properties that answer with a different type depending on state. The value of a cell in Numbers is documented as "number, date, text, boolean, or missing value" — declare .int there and an empty cell is indistinguishable from a cell holding zero. NSAppleScript already hands back an NSAppleEventDescriptor carrying the real type; the bridge discarded it and coerced to whatever the caller declared.

.wildCard switches on the descriptor's own type instead and returns an AppleScriptValue:

switch try AppleScriptBridge.executeAppleScript(cellValue) as? AppleScriptBridge.AppleScriptValue {
    case .double(let number): …
    case .string(let text):   …
    case .missingValue:       …   // the cell is empty
    default:                  break
}

Numbers, text, booleans, dates, files, missing value, application-defined constants, and lists and records, the last two decoded recursively. Anything else arrives as .unknown carrying the descriptor untouched, so nothing is lost.

Decisions worth reviewing

• .wildCard, not .descriptor. @olofhellman's suggestion in Expose the raw AppleEvent descriptor, so callers can switch on the actual result type #5, after the AppleEvents typeWildCard tradition. The escape hatch inside the value enum stays .unknown, so the two names don't collide.
• missing value gets its own case, rather than arriving as .constant('msng'). It is the common answer, and making every caller compare four-character codes for it would be the wrong default. Other constants do carry their raw FourCharCode — what 'autp' means is defined by the application's dictionary, not by AppleScript, so there is no general mapping to hand the caller.
• No osascript parity. executeAppleScriptViaCommandLine throws the new AppleScriptError.unsupportedReturnType before launching the process, so a .wildCard script never runs and never touches the target application. Returning the printed text as a .string would fake the very type information the feature exists to preserve.
• Record keys are as written, or as compiled. A key AppleScript claims as terminology is compiled to a four-character code before the script runs, so {name:"Roger", age:42} decodes as ["pnam": .string("Roger"), "age": .int(42)]. Documented everywhere it can surprise.
• Integers are read at their declared width. int32Value answers 0 for anything wider, which would have turned a typeSInt64 into a silent zero. A value too large for an Int falls back to .unknown rather than reporting a wrong number.

Testing

46 tests, all passing locally. 17 are new, in two layers — both permission-free:

• Descriptors built directly, for what AppleScript source cannot produce: a 64-bit integer, an unsigned value too large for an Int, an empty list, and a record carrying both a coded key and user fields, including the collision where a user field is named after a code.
• Self-contained scripts through NSAppleScript, which drive no application and so need no Automation permission. These are the only check against what AppleScript actually emits — that {name:"Roger", age:42} really does arrive with name compiled to 'pnam', and that 3000000000 really does arrive as a real.

Every code snippet in the README and in Documentation/API.md was compiled against the package before being written down, and Examples/AppleScripts.swift builds as a consumer package the way CI builds it.

Version

Cut as 1.2.0: new public API, all of it opt-in, with the default path unchanged. AppleScriptReturnType and AppleScriptError each gained a case, so code switching over either exhaustively without a default stops compiling — the release notes open with that caveat.

Two things I could not verify

• SwiftLint did not run locally (not installed on this machine). I checked the configured rules by hand — no force unwraps, no trailing whitespace, switch columns aligned — but CI is the real check.
• The four NSAppleScript execution tests are unproven on a GitHub runner. They pass locally; if the runner disagrees, they are easy to drop without losing the descriptor-level coverage.

Follow-up

#7 tracks @olofhellman's second suggestion, an .osType return type for scripts whose result is known to be a constant. Left out deliberately: it carries its own unsettled question — raw codes versus dictionary terms — that deserves its own discussion.

🤖 Generated with Claude Code

[olofhellman]

Looks great! You even included UserRecordFields coercion!