chore(pkg): add schema versioning and iOS xcassetsPath handling

Author: alexey1312

.github/workflows/release.yml

@@ -135,6 +135,7 @@ jobs:
           VERSION="${GITHUB_REF#refs/tags/}"
           FILE="Sources/ExFigCLI/ExFigCommand.swift"
           sed -i "s/static let version = \".*\"/static let version = \"$VERSION\"/" "$FILE"
+          sed -i "s/version = \".*\"/version = \"${VERSION#v}\"/" "Sources/ExFigCLI/Resources/Schemas/PklProject"
 
       - name: Update CHANGELOG.md
         uses: orhun/git-cliff-action@v4
@@ -148,7 +149,7 @@ jobs:
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add Sources/ExFigCLI/ExFigCommand.swift CHANGELOG.md
+          git add Sources/ExFigCLI/ExFigCommand.swift Sources/ExFigCLI/Resources/Schemas/PklProject CHANGELOG.md
           git diff --staged --quiet || git commit -m "chore(release): bump version to ${GITHUB_REF#refs/tags/v}"
           git push origin main
 
@@ -175,12 +176,21 @@ jobs:
         env:
           GITHUB_REPO: ${{ github.repository }}
 
-      - name: Create schemas archive
+      - name: Install Pkl CLI
+        run: |
+          curl -sL https://github.com/apple/pkl/releases/download/0.30.2/pkl-linux-amd64 -o /usr/local/bin/pkl
+          chmod +x /usr/local/bin/pkl
+
+      - name: Update PklProject version
         run: |
           VERSION="${GITHUB_REF#refs/tags/v}"
-          cd Sources/ExFigCLI/Resources/Schemas
-          zip -r "../../../../exfig-schemas@${VERSION}.zip" \
-            ExFig.pkl Figma.pkl Common.pkl iOS.pkl Android.pkl Flutter.pkl Web.pkl PklProject
+          sed -i "s/version = \".*\"/version = \"$VERSION\"/" Sources/ExFigCLI/Resources/Schemas/PklProject
+
+      - name: Package PKL schemas
+        run: |
+          pkl project package \
+            --output-path ".pkl-out/%{name}@%{version}/" \
+            Sources/ExFigCLI/Resources/Schemas
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
@@ -190,7 +200,7 @@ jobs:
           files: |
             artifacts/exfig-macos/exfig-macos.zip
             artifacts/exfig-linux-x64/exfig-linux-x64.tar.gz
-            exfig-schemas@*.zip
+            .pkl-out/exfig@*/*
 
   update-homebrew:
     name: Update Homebrew Tap

CONFIG.md

@@ -16,6 +16,19 @@ This creates a `.exfig/schemas/` directory with all schema files (`ExFig.pkl`, `
 `Android.pkl`, `Flutter.pkl`, `Web.pkl`). Your config file references these schemas via `amends` and `import`
 statements.
 
+Alternatively, you can reference schemas directly via the published PKL package URI (no local extraction needed):
+
+```pkl
+amends "package://github.com/alexey1312/ExFig/releases/download/v2.0.0/exfig@2.0.0#/ExFig.pkl"
+
+import "package://github.com/alexey1312/ExFig/releases/download/v2.0.0/exfig@2.0.0#/iOS.pkl"
+import "package://github.com/alexey1312/ExFig/releases/download/v2.0.0/exfig@2.0.0#/Figma.pkl"
+import "package://github.com/alexey1312/ExFig/releases/download/v2.0.0/exfig@2.0.0#/Common.pkl"
+```
+
+Replace `2.0.0` with your ExFig version. Using local schemas (`exfig schemas`) is recommended for faster evaluation
+and offline support.
+
 ## Quick Start
 
 Generate a working configuration file for your platform:
@@ -309,13 +322,16 @@ ios = new iOS.iOSConfig {
 | ------------------------ | ------------------ | -------- | ------------------------------------------------------ |
 | `xcodeprojPath`          | `String`           | Yes      | Path to `.xcodeproj` file                              |
 | `target`                 | `String`           | Yes      | Xcode target for resources and Swift code              |
-| `xcassetsPath`           | `String`           | Yes      | Path to `Assets.xcassets` directory                    |
+| `xcassetsPath`           | `String?`          | No*      | Path to `Assets.xcassets` directory                    |
 | `xcassetsInMainBundle`   | `Boolean`          | Yes      | Whether assets are in the main bundle                  |
 | `xcassetsInSwiftPackage` | `Boolean?`         | No       | Whether assets are in a Swift package (default: false) |
 | `resourceBundleNames`    | `Listing<String>?` | No       | Resource bundle names for SPM packages                 |
 | `addObjcAttribute`       | `Boolean?`         | No       | Add `@objc` to generated properties (default: false)   |
 | `templatesPath`          | `String?`          | No       | Path to custom Stencil templates                       |
 
+*Required when exporting colors (with `useColorAssets`), icons, or images. Can be omitted in base configs used only
+for inheritance.
+
 ### iOS Colors
 
 ```pkl
@@ -1002,6 +1018,52 @@ configuration.
 
 ---
 
+## Common PKL Patterns
+
+### Union Types: Single vs. Multiple Entries
+
+ExFig schema fields like `colors`, `icons`, and `images` accept either a single entry or a `Listing` (array). PKL
+cannot infer the type from `new { ... }` for union types, so you must use the typed constructor when writing multiple
+entries.
+
+**Single entry** — type is inferred, no explicit type needed:
+
+```pkl
+colors = new iOS.ColorsEntry {
+  figmaFrameName = "Colors"
+  useColorAssets = true
+  assetsFolder = "Colors"
+  nameStyle = "camelCase"
+}
+```
+
+**Multiple entries** — MUST use typed constructor (`new Type { ... }`):
+
+```pkl
+colors = new Listing {
+  new iOS.ColorsEntry {
+    figmaFrameName = "Light Colors"
+    useColorAssets = true
+    assetsFolder = "Colors/Light"
+    nameStyle = "camelCase"
+  }
+  new iOS.ColorsEntry {
+    figmaFrameName = "Dark Colors"
+    useColorAssets = true
+    assetsFolder = "Colors/Dark"
+    nameStyle = "camelCase"
+  }
+}
+```
+
+Without the typed constructor (e.g., `new { ... }` inside a Listing), PKL will report:
+`Expected type iOS.ColorsEntry, but got Dynamic`.
+
+This pattern applies to all platforms: `iOS.ColorsEntry`, `iOS.IconsEntry`, `iOS.ImagesEntry`,
+`Android.ColorsEntry`, `Android.IconsEntry`, `Android.ImagesEntry`, `Flutter.ColorsEntry`, etc.
+
+---
+
 ## Validation
 
 Validate your config file before running exports:

Sources/ExFig-iOS/Config/iOSPlatformConfig.swift

@@ -16,7 +16,9 @@ public struct iOSPlatformConfig: Sendable {
     public let target: String
 
     /// Path to the .xcassets directory.
-    public let xcassetsPath: URL
+    /// Required for colors (with useColorAssets), icons, and images export.
+    /// Can be nil in base configs that don't directly export assets.
+    public let xcassetsPath: URL?
 
     /// Whether assets are in the main bundle.
     public let xcassetsInMainBundle: Bool
@@ -42,7 +44,7 @@ public struct iOSPlatformConfig: Sendable {
     public init(
         xcodeprojPath: String,
         target: String,
-        xcassetsPath: URL,
+        xcassetsPath: URL? = nil,
         xcassetsInMainBundle: Bool = true,
         xcassetsInSwiftPackage: Bool? = nil,
         resourceBundleNames: [String]? = nil,

Sources/ExFig-iOS/Export/iOSColorsExporter.swift

@@ -112,7 +112,10 @@ public struct iOSColorsExporter: ColorsExporter {
             guard let folder = entry.assetsFolder else {
                 throw iOSColorsExportError.assetsFolderNotSpecified
             }
-            colorsURL = platformConfig.xcassetsPath.appendingPathComponent(folder)
+            guard let xcassetsPath = platformConfig.xcassetsPath else {
+                throw iOSColorsExportError.xcassetsPathNotSpecified
+            }
+            colorsURL = xcassetsPath.appendingPathComponent(folder)
         }
 
         // Create output configuration
@@ -148,18 +151,24 @@ public struct iOSColorsExporter: ColorsExporter {
 public enum iOSColorsExportError: LocalizedError {
     /// Assets folder not specified when useColorAssets is true.
     case assetsFolderNotSpecified
+    /// xcassetsPath not specified when exporting color assets.
+    case xcassetsPathNotSpecified
 
     public var errorDescription: String? {
         switch self {
         case .assetsFolderNotSpecified:
             "assetsFolder is required when useColorAssets is true"
+        case .xcassetsPathNotSpecified:
+            "xcassetsPath is required for iOS colors export with useColorAssets"
         }
     }
 
     public var recoverySuggestion: String? {
         switch self {
         case .assetsFolderNotSpecified:
             "Add 'assetsFolder' to your iOS colors configuration"
+        case .xcassetsPathNotSpecified:
+            "Add 'xcassetsPath' to your iOS configuration"
         }
     }
 }

Sources/ExFig-iOS/Export/iOSIconsExporter.swift

@@ -132,7 +132,10 @@ public struct iOSIconsExporter: IconsExporter {
         let iconPairs = processResult.iconPairs
 
         // 3. Generate files
-        let assetsURL = platformConfig.xcassetsPath.appendingPathComponent(entry.assetsFolder)
+        guard let xcassetsPath = platformConfig.xcassetsPath else {
+            throw iOSIconsExportError.xcassetsPathNotSpecified
+        }
+        let assetsURL = xcassetsPath.appendingPathComponent(entry.assetsFolder)
 
         let output = XcodeImagesOutput(
             assetsFolderURL: assetsURL,
@@ -213,4 +216,26 @@ public struct iOSIconsExporter: IconsExporter {
     }
 }
 
+// MARK: - Errors
+
+/// Errors that can occur during iOS icons export.
+public enum iOSIconsExportError: LocalizedError {
+    /// xcassetsPath not specified when exporting icons.
+    case xcassetsPathNotSpecified
+
+    public var errorDescription: String? {
+        switch self {
+        case .xcassetsPathNotSpecified:
+            "xcassetsPath is required for iOS icons export"
+        }
+    }
+
+    public var recoverySuggestion: String? {
+        switch self {
+        case .xcassetsPathNotSpecified:
+            "Add 'xcassetsPath' to your iOS configuration"
+        }
+    }
+}
+
 // swiftlint:enable type_name file_length

Sources/ExFig-iOS/Export/iOSImagesExporter.swift

@@ -372,7 +372,10 @@ public struct iOSImagesExporter: ImagesExporter {
 
         if let warning = processResult.warning { context.warning(warning) }
 
-        let assetsURL = platformConfig.xcassetsPath.appendingPathComponent(entry.assetsFolder)
+        guard let xcassetsPath = platformConfig.xcassetsPath else {
+            throw iOSImagesExportError.xcassetsPathNotSpecified
+        }
+        let assetsURL = xcassetsPath.appendingPathComponent(entry.assetsFolder)
         return (processResult.imagePairs, assetsURL, loadResult)
     }
 
@@ -409,11 +412,36 @@ public struct iOSImagesExporter: ImagesExporter {
 
         if let warning = processResult.warning { context.warning(warning) }
 
-        let assetsURL = platformConfig.xcassetsPath.appendingPathComponent(entry.assetsFolder)
+        guard let xcassetsPath = platformConfig.xcassetsPath else {
+            throw iOSImagesExportError.xcassetsPathNotSpecified
+        }
+        let assetsURL = xcassetsPath.appendingPathComponent(entry.assetsFolder)
         return (processResult.imagePairs, assetsURL, loadResult)
     }
 }
 
+// MARK: - Errors
+
+/// Errors that can occur during iOS images export.
+public enum iOSImagesExportError: LocalizedError {
+    /// xcassetsPath not specified when exporting images.
+    case xcassetsPathNotSpecified
+
+    public var errorDescription: String? {
+        switch self {
+        case .xcassetsPathNotSpecified:
+            "xcassetsPath is required for iOS images export"
+        }
+    }
+
+    public var recoverySuggestion: String? {
+        switch self {
+        case .xcassetsPathNotSpecified:
+            "Add 'xcassetsPath' to your iOS configuration"
+        }
+    }
+}
+
 // MARK: - Entry Helpers
 
 private extension iOSImagesEntry {

Sources/ExFigCLI/ExFigCommand.swift

@@ -100,4 +100,25 @@ extension ExFigCommand {
         terminalUI = TerminalUI(outputMode: outputMode)
         terminalUI.installSignalHandlers()
     }
+
+    /// Checks if extracted schemas match the current CLI version and warns if not.
+    static func checkSchemaVersionIfNeeded() {
+        guard let ui = terminalUI else { return }
+
+        switch SchemaExtractor.checkVersion() {
+        case .matched, .noSchemasDirectory:
+            break
+        case let .mismatch(schemasVersion, cliVersion):
+            ui.warning(
+                "Extracted schemas (\(schemasVersion)) don't match ExFig version (\(cliVersion)). "
+                    + "Run `exfig schemas --force` to update."
+            )
+        case .noVersionFile:
+            // Schemas exist but no version file — extracted by an older version
+            ui.warning(
+                "Schema version unknown (extracted by an older ExFig version). "
+                    + "Run `exfig schemas --force` to update."
+            )
+        }
+    }
 }

Sources/ExFigCLI/Input/PKLConfig.swift

@@ -233,7 +233,7 @@ struct PKLConfig: Decodable {
 
         let xcodeprojPath: String
         let target: String
-        let xcassetsPath: URL
+        let xcassetsPath: URL?
         let xcassetsInMainBundle: Bool
         let xcassetsInSwiftPackage: Bool?
         let resourceBundleNames: [String]?

Sources/ExFigCLI/Resources/Schemas/ExFig.pkl

@@ -5,7 +5,7 @@
 ///
 /// Usage:
 /// ```pkl
-/// amends "package://github.com/alexey1312/ExFig@2.0.0#/ExFig.pkl"
+/// amends "package://github.com/alexey1312/ExFig/releases/download/v2.0.0/exfig@2.0.0#/ExFig.pkl"
 ///
 /// figma {
 ///   lightFileId = "xxx"

Sources/ExFigCLI/Resources/Schemas/PklProject

@@ -2,12 +2,14 @@ amends "pkl:Project"
 
 package {
   name = "exfig"
-  baseUri = "package://github.com/alexey1312/ExFig"
+  baseUri = "package://github.com/alexey1312/ExFig/releases/download/v\(version)/exfig"
   version = "2.0.0"
-  packageZipUrl = "https://github.com/alexey1312/ExFig/releases/download/v\(version)/exfig-schemas@\(version).zip"
+  packageZipUrl = "https://github.com/alexey1312/ExFig/releases/download/v\(version)/\(name)@\(version).zip"
   description = "ExFig configuration schemas for exporting Figma assets to iOS, Android, Flutter, and Web"
   authors {
-    "Alexey"
+    "Alexey <alexey1312@users.noreply.github.com>"
   }
+  sourceCode = "https://github.com/alexey1312/ExFig"
+  sourceCodeUrlScheme = "https://github.com/alexey1312/ExFig/blob/v\(version)/Sources/ExFigCLI/Resources/Schemas%{path}#L%{line}-L%{endLine}"
   license = "MIT"
 }