Extension Declaration and Manifest · Docs

Extension behavior and metadata are declared in Swift. Info.plist contains only ordinary framework metadata plus the principal class Tuna needs before it can load Swift code.

These declaration examples target Tuna 0.80 and TunaKit 1.14.0.

@objc(ProjectsExtension)
public final class ProjectsExtension: Extension {
  public override var declaration: ExtensionDeclaration? {
    ExtensionDeclaration(
      metadata: ExtensionMetadata(
        displayName: "Projects",
        author: "Your Name",
        description: "Jump to project folders.",
        iconName: "folder.badge.gearshape"
      ),
      compatibility: ExtensionDeclarationCompatibility(
        minTuna: "0.80",
        minTunaKit: "1.14.0"
      ),
      catalogs: [
        CatalogDeclaration(
          id: "projects",
          type: ProjectsCatalog.self,
          name: "Projects",
          enabledByDefault: true
        )
      ],
      actionCatalogs: [
        ActionCatalogDeclaration(
          id: "projects.actions",
          type: ProjectsActionsCatalog.self,
          name: "Projects Actions"
        )
      ]
    )
  }
}

`ExtensionDeclaration`

Field	Type	Default	Meaning
`metadata`	`ExtensionMetadata`	required	User-visible extension information
`compatibility`	`ExtensionDeclarationCompatibility?`	`nil`	Minimum host/package versions
`settings`	`[CatalogSettingDefinition]`	`[]`	Extension-wide settings
`catalogs`	`[CatalogDeclaration]`	`[]`	Searchable source catalogs provided by the extension
`actionCatalogs`	`[ActionCatalogDeclaration]`	`[]`	Action catalogs provided by the extension
`typeRegistrations`	`[TypeRegistrationDefinition]`	`[]`	Custom type graph entries
`defaultActionRankings`	`[DefaultActionRankingDefinition]`	`[]`	Default actions per type
`appBrowseEnrichments`	`[AppBrowseEnrichmentDefinition]`	`[]`	Browse entries attached to apps
`appActionEnrichments`	`[AppActionEnrichmentDefinition]`	`[]`	Action catalogs added and ordered for matching apps

Metadata and compatibility

Type	Field	Required	Meaning
`ExtensionMetadata`	`displayName`	yes	Name shown in Tuna
	`author`	yes	Author or organization
	`description`	yes	Short user-facing description
	`iconName`	yes	SF Symbol name; invalid names fall back to a generic icon
`ExtensionDeclarationCompatibility`	`minTuna`	no	Minimum Tuna version for packaging/store gating
	`minTunaKit`	no	Minimum TunaKit version for packaging/store gating

`CatalogDeclaration`

Field	Type	Default	Meaning
`id`	`String`	required	Permanent canonical catalog identity
`type`	`Catalog.Type`	required	Concrete catalog metatype
`name`	`String`	required	User-visible source name
`enabledByDefault`	`Bool`	required	Initial enablement for new installs
`isAdvanced`	`Bool`	`false`	Places the catalog in the advanced source section
`settings`	`[CatalogSettingDefinition]`	`[]`	Settings rendered for this catalog

Catalog IDs must be valid and unique. Browse enrichments may only reference source catalogs declared by the same extension. IDs appear in settings, scopes, hotkeys, rankings, and item references; do not rename them as presentation changes.

`ActionCatalogDeclaration`

Field	Type	Default	Meaning
`id`	`String`	required	Permanent canonical action-catalog identity
`type`	`ActionCatalog.Type`	required	Concrete action-catalog metatype
`name`	`String`	required	User-visible action-catalog name

Action catalogs vend actions, not objects, and have no enablement, advanced flag, settings, or scan lifecycle. Source and action catalogs share one ID namespace. Default rankings and app action enrichments must reference action catalogs declared by the same extension.

`CatalogSettingDefinition`

Field	Type	Required/default	Meaning
`key`	`String`	required	Stable storage key
`type`	`.string`, `.bool`, `.secret`	required	Editor and storage behavior
`label`	`String`	required	Settings label
`defaultValue`	`String`	required	Serialized default value
`description`	`String?`	required, may be `nil`	Supporting text
`options`	`[Option]`	`[]`	Fixed choices; valid only for `.string`

Each Option has a stored value and user-visible label. Secret settings are stored in Keychain.

Types, rankings, and enrichments

Type	Fields
`TypeRegistrationDefinition`	`typeID`, optional `displayName`, `inheritsFrom` parent types
`DefaultActionRankingDefinition`	`typeID`, ordered `actions` references
`ActionReference`	`catalogIdentifier`, `actionID`
`AppBrowseEnrichmentDefinition`	matching `bundleIdentifiers`, ordered `entries`
`AppBrowseEnrichmentEntryDefinition`	`catalogIdentifier`, optional `title`
`AppActionEnrichmentDefinition`	matching `bundleIdentifiers`, `catalogIdentifiers`, optional ordered `preferredActions`

Connection declarations

Override connectionDefinitions on the Extension subclass when the extension connects to a service.

Field	Type/default	Meaning
`providerIdentifier`	required `String`	Stable provider identity
`providerName`	required `String`	User-visible provider name
`kind`	`.secret` or `.oauth`	Connection flow
`supportsBaseURL`	`false`	Whether self-hosted/base URLs are accepted
`defaultBaseURL`	`""`	Initial base URL
`baseURLLabel`	`"Server URL"`	Base URL field label
`secretLabel`	`"Access Token"`	Secret field label
`description`	`nil`	Supporting text
`connectButtonLabel`	`"Add Connection"`	Primary action label
`oauthPKCE`	`nil`	Optional direct PKCE configuration; when absent, OAuth uses Tuna’s web broker

Direct PKCE connections declare an OAuthPKCEConfiguration with the public OAuth client identifier, authorization URL, token URL, scopes, and optional additional authorization parameters. Tuna generates and validates state and PKCE values, receives the callback, exchanges the code, and stores returned tokens in Keychain. OAuthAuthorizationCodeClient is also available to exchange refresh tokens, and configuration can supply additional token parameters. Never put a client secret in an extension.

`Info.plist`

Key	Value
`CFBundleIdentifier`	Unique reverse-DNS bundle ID, normally `$(PRODUCT_BUNDLE_IDENTIFIER)`
`CFBundleName`	Framework/module name, normally `$(PRODUCT_NAME)`
`CFBundlePackageType`	`FMWK`
`CFBundleShortVersionString`	Public extension version
`CFBundleVersion`	Build number
`LSMinimumSystemVersion`	`$(MACOSX_DEPLOYMENT_TARGET)`
`NSPrincipalClass`	Objective-C-visible `Extension` subclass, usually `$(PRODUCT_MODULE_NAME).ClassName`

The principal class must inherit Extension, be visible to Objective-C, and match NSPrincipalClass. Catalog metatypes are checked by Swift at compile time.