App Intents: Siri, Shortcuts and the Action Button Without Opening the App

import AppIntents
import Foundation

/// The work lives in a plain type the unit suite can call. perform() is resolution plus one call,
/// because an intent runs in whatever process the system chooses, where no test can reach it.
struct CaptureFiler: Sendable {
    let box: @Sendable (_ text: String, _ origin: String) throws -> String

    func file(_ text: String) throws -> String {
        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !trimmed.isEmpty else { throw CaptureError.empty }
        return try box(trimmed, "intent")
    }
}

enum CaptureError: Error, CustomLocalizedStringResourceConvertible {
    case empty
    var localizedStringResource: LocalizedStringResource { "There is nothing to save." }
}

struct CaptureNoteIntent: AppIntent {
    static let title: LocalizedStringResource = "Capture a Note"
    // A literal on one line: "a" + "b" is a plain String and fails with "no exact matches".
    static let description = IntentDescription("Saves a note to Spark straight away, with or without a network.")
    static let openAppWhenRun = false   // may run out of process: write to the App Group drop box only

    /// Optional on purpose. A required parameter cannot be prompted when the shortcut runs from
    /// Spotlight or the Shortcuts library, and the run fails with "Unable to run App Shortcut".
    @Parameter(title: "Note") var text: String?

    func perform() async throws -> some IntentResult & ProvidesDialog {
        guard let text, !text.isEmpty else {
            throw $text.needsValueError("What should Spark save?")
        }
        let filer = CaptureFiler { text, origin in "cap-\(UUID().uuidString.prefix(8))" }   // app: SharedDropBox
        _ = try filer.file(text)
        return .result(dialog: "Saved.")
    }
}

struct SparkShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: CaptureNoteIntent(),
            phrases: [
                "Capture a note in \(.applicationName)",   // every phrase names the app, or the build halts
                "\(.applicationName) note",
            ],
            shortTitle: "Capture Note",
            systemImageName: "square.and.pencil"
        )
    }
}

# Registration is visible in the built bundle, even where execution is not.
app=build/SparkMobile-42.xcarchive/Products/Applications/SparkMobile.app
python3 -c "
import json, sys
data = json.load(open(sys.argv[1]))
print('actions:', sorted(data['actions']))
print('app shortcuts:', len(data.get('autoShortcuts', [])))
" "$app/Metadata.appintents/extract.actionsdata"
#   actions: ['CaptureNoteIntent']

# Execution is proven on a device. To tell a Simulator that cannot run App Shortcuts from a
# bug of your own, add a trivial intent (no parameters, openAppWhenRun = true, returns .result())
# and run it first: if even that fails, stop rebuilding against the Simulator.