feat(penpot): add Penpot as alternative design source (#76)

* feat(core): add Penpot API client and design source integration

Implement Penpot as a second design data source alongside Figma:

- New PenpotAPI module: HTTP client for Penpot RPC API with endpoint
  protocol, retry logic, and response models (colors, components,
  typographies) supporting dual String/Double decoding
- PenpotColorsSource, PenpotComponentsSource, PenpotTypographySource
  wired into SourceFactory for seamless dispatch via sourceKind
- PenpotColorsConfig added to ColorsSourceConfig protocol family
- PenpotSource class in Common.pkl with auto-detection (penpotSource
  set → sourceKind "penpot") and codegen
- Entry bridge methods updated to use resolvedSourceKind across all
  four platform plugins
- 21 unit tests for model decoding, endpoint construction, and error
  recovery suggestions

* docs: update CLAUDE.md with PenpotAPI module and source kind patterns

* docs: update module docs for PenpotAPI (15 modules, source dispatch)

* docs: add Penpot support to README, DocC articles, and llms-full.txt

* fix(penpot): resolve URL construction, base URL, error handling, and type safety issues

- Fix operator precedence bug in PenpotComponentsSource URL construction
- Use configurable base URL from penpotSource instead of hardcoded design.penpot.app
- Add resolvedFileId/resolvedPenpotBaseURL computed properties to Common_FrameSource
- Add penpotBaseURL field to IconsSourceInput, ImagesSourceInput, TypographySourceInput
- Replace JSONSerialization with Codable+CodingKeys+YYJSONEncoder in thumbnails endpoint
- Validate fileId before API calls instead of falling back to empty string
- Add ColorsConfigError.missingPenpotSource for correct error messaging
- Return nil from hexToRGBA on invalid hex with warning instead of silent black
- Handle CancellationError in retry loop to respect cooperative cancellation
- Include response body in download error messages for diagnostics
- Add preconditions for maxRetries and accessToken in BasePenpotClient
- Change PenpotTypography numeric fields from var to let (immutable)

* test(penpot): add tests for resolvedSourceKind, hexToRGBA, SourceFactory dispatch, and fileId validation

- Add FrameSourceResolvedSourceKindTests: auto-detect penpot, explicit override,
  resolvedFileId priority, resolvedPenpotBaseURL
- Add PenpotColorsSourceInputTests: auto-detected penpot config, missingPenpotSource error
- Add HexToRGBATests: valid/invalid hex, opacity, whitespace, lowercase
- Add SourceFactoryPenpotTests: .penpot dispatch for all 3 source types + unsupported throws
- Add PenpotComponentsSourceValidationTests: nil/empty fileId throws descriptive error
- Extract Penpot tests from DesignSourceTests.swift to stay under file_length limit

* fix(penpot): fix GetProfile empty body and duplicate --timeout in fetch command

- GetProfileEndpoint now sends `{}` body instead of nil (Penpot returns
  400 "malformed-json" for empty body)
- Resolve duplicate --timeout flag conflict in `exfig fetch` by inlining
  HeavyFaultToleranceOptions fields and constructing via computed property
- Document API path difference (/api/main/methods/ vs /api/rpc/command/)
  and Cloudflare behavior in PenpotAPI CLAUDE.md
- Add E2E test data documentation (README.md) for Penpot test file
- Exclude README.md from PenpotAPITests SPM resources

* docs(penpot): add Penpot file structure guide, MCP resources, and prompt enhancements

- Expand DesignRequirements.md with Penpot section: library colors,
  components, typography, file organization, limitations, troubleshooting
- Add MCP guide resource (exfig://guides/DesignRequirements.md) served
  from Resources/Guides/ since DocC articles aren't in Bundle.module
- Add `source` argument to setup-config MCP prompt (figma/penpot branches)
- Update troubleshoot-export prompt to check both auth tokens
- Add Penpot typography config example to Configuration.md
- Regenerate llms-full.txt with updated DocC content
- Update CLAUDE.md with timeout, DocC bundle, and Penpot API gotchas

* feat(cli): add Penpot support to init and fetch wizards

- Add WizardDesignSource enum — first wizard question is now "Figma or Penpot?"
- InitWizard Penpot flow: file UUID, base URL, path filters (no dark mode/variables)
- FetchWizard Penpot flow: file UUID, path filter, output directory
- Add extractPenpotFileId() for Penpot workspace URL parsing (file-id= query param)
- Add applyPenpotResult() in InitWizardTransform — removes figma section, inserts
  penpotSource blocks into platform entries
- Add runPenpotFetch() in DownloadImages — downloads component thumbnails via PenpotAPI
- Update GenerateConfigFile to show PENPOT_ACCESS_TOKEN in next-steps for Penpot source
- Update test helpers with new InitWizardResult fields (designSource, penpotBaseURL)

* fix(penpot): fix API client bugs, improve error handling, and add missing tests

- Fix download() URL mangling by detecting absolute URLs
- Fix retry loop returning error response on final attempt (now throws)
- Fix asset download auth conflict with S3 presigned URLs (no Authorization header)
- Fix asset path: assets/by-id/ instead of assets/by-file-media-id/
- Extract PenpotClientFactory from PenpotColorsSource for shared usage
- Sort dictionary iteration for deterministic export order
- Replace force-unwrap wizardResult! with safe binding
- Wire iOS PluginIconsExport through SourceFactory for Penpot dispatch
- Add recovery suggestions for 500-level and network errors
- Wrap decoding errors with HTTP context (endpoint, status code)
- Add baseURL validation precondition in BasePenpotClient.init
- Add precondition(!fileId.isEmpty) to GetFileEndpoint
- Add warnings for empty API responses, unknown text transforms
- Remove unused mainInstanceId/mainInstancePage from PenpotComponent
- Fix doc comments (PenpotEndpoint, GetProfileEndpoint, PenpotTypography)
- Fix DesignTokens.md false Penpot claim, CLAUDE.md module count
- Add tests: applyPenpotResult, extractPenpotFileId, VariablesSource.resolvedSourceKind

* feat(cli): make FIGMA_PERSONAL_TOKEN optional and add --source penpot to fetch

ExFigOptions.validate() no longer throws when FIGMA_PERSONAL_TOKEN is missing.
Token is read lazily and only required when a Figma source is actually used.
SourceFactory guards the .figma branch and throws accessTokenNotFound there.

Added --source penpot/figma flag and --penpot-base-url to exfig fetch for
non-interactive Penpot usage without the wizard.

* feat(penpot): add SVG reconstruction from shape tree for icon/image export

Replace thumbnail-based component export with SVG reconstruction from
Penpot's shape tree data. This enables vector export (SVG/PNG/PDF) at
any scale without headless Chrome or CDN — shapes are parsed directly
from the get-file API response.

- Add PenpotShape model for shape tree decoding (path, rect, circle, bool, group, frame)
- Add PenpotShapeRenderer — pure function that converts shape tree → SVG string
- Add PenpotPage/SVGAttributes models, extend PenpotFileData with pagesIndex
- Rewrite PenpotComponentsSource to use SVG reconstruction instead of thumbnails
- Update runPenpotFetch to support --format svg/png with SVG→PNG via resvg
- Wire SourceFactory through all remaining platform exports (Android/Flutter/Web icons + all images)
- Restore mainInstanceId/mainInstancePage on PenpotComponent for shape tree lookup
- Handle mixed-type svgAttrs (strings + nested style dicts) via SVGAttributes wrapper

* docs(penpot): update docs for SVG reconstruction — remove raster-only limitation

- Remove "v1 limitation: raster thumbnails only" from DesignRequirements, Configuration, MCP prompts
- Add Penpot icons PKL config example to Configuration.md
- Add "Penpot Fetch" section to Usage.md with --source penpot examples
- Add "Quick Penpot Icons Export" to GettingStarted.md
- Update MCP prompt: "SVG reconstructed from shape tree" replaces raster limitation
- Update Known Limitations: add SVG reconstruction scope (no blur/shadow/gradients)
- Regenerate llms-full.txt

* fix(penpot): allow file:// URLs in FileDownloader for local SVG assets

Penpot SVG reconstruction writes SVGs to temp files and passes file://
URLs through the download pipeline. FileDownloader now skips HTTP
download for file:// URLs and returns the local path directly.

* fix(penpot): handle file:// URLs before download phase instead of weakening validation

Move file:// URL handling from validateDownloadURL (security gate) to
fetch() method — file:// URLs are filtered as local files before the
download loop, keeping validateDownloadURL strictly HTTPS-only.

* docs: add FileDownloader file:// pattern and iOS PKL xcassetsPath gotcha

* fix(penpot): improve type safety, error handling, and diagnostics across Penpot support

Replace placeholder FigmaClient("no-token") with NoTokenFigmaClient that
throws accessTokenNotFound on any call — prevents silent HTTP requests with
invalid credentials. Add ShapeType enum replacing stringly-typed shape
dispatch, MainInstance struct enforcing paired id+page invariant, and
structured RenderResult/RenderFailure for SVG reconstruction diagnostics.

Fix SVG arc command normalization to correctly offset only endpoint
coordinates (params 5-6 of 7-param groups). Add warnings for skipped
gradient colors, empty path filter results, and unknown shape types.
Remove force unwrap in FileDownloader, fix inverted letterSpacing warning
condition, and throw error for unsupported Penpot export formats instead
of silently saving SVG.

Includes 9 new tests covering nested groups, rotation transforms, arc
normalization, relative path commands, ShapeType decoding, and
RenderFailure diagnostics.

* ci: trigger DocC deploy on tag push instead of release event

Aligns deploy-docc.yml trigger with release.yml so both workflows
run in parallel when a version tag is pushed.

* chore(hk): disable stash in pre-commit hook

Switch from patch-file to none to avoid stash overhead during commits.

* refactor(penpot): extract PenpotAPI into external package swift-penpot-api

Move the standalone PenpotAPI module to DesignPipe/swift-penpot-api (v0.1.0),
mirroring the swift-figma-api extraction pattern. No code changes in consumer
files — `import PenpotAPI` continues to work via the external SPM dependency.

Also fix pre-existing test failure in ExFigErrorFormatterTests where the
assertion text didn't match the updated accessTokenNotFound error message.

* docs: update module structure, org name, and external package references

- Development.md: ExFig/ → ExFigCLI/, expand module list from 7 to 12,
  add Source/, MCP/, JinjaSupport, WebExport, update test targets,
  replace inline FigmaAPI guide with link to external package
- ARCHITECTURE.md: ExFig (CLI) → ExFigCLI, add External Packages section
  (FigmaAPI, PenpotAPI, SVGKit), Stencil → Jinja2, update file structure
- PKL.md, MIGRATION.md: niceplaces → DesignPipe, fix Schemas path
  Sources/ExFig/ → Sources/ExFigCLI/

* docs: consolidate docs/ into ExFig.docc, remove duplicate directory

Move ARCHITECTURE.md, PKL.md, MIGRATION.md from docs/ (which conflicts
with DocC output directory) into Sources/ExFigCLI/ExFig.docc/. Move
app-release-secrets.md to .github/. Update cross-references to use
DocC links and hosted documentation URLs.

* docs: clarify that docs/ is DocC output, source docs live in ExFig.docc

* docs: document nil-token behavior in resolveClient and list all source families

Update doc-comment for the HeavyFaultToleranceOptions resolveClient overload
to describe NoTokenFigmaClient fallback when accessToken is nil, matching the
existing FaultToleranceOptions overload. Update Source/ directory description
in CLAUDE.md to list all three source families (Figma, Penpot, TokensFile).

* fix(penpot): improve error handling, validation, and DI across Penpot support

- Validate Penpot format (svg/png) before API call instead of inside component loop
- Make resolvedFileId source-kind-aware to prevent passing Figma keys to Penpot API
- Replace silent .figma fallback on empty entries with explicit guard + error
- Add URL validation in PenpotClientFactory before client creation
- Remove synthetic FetchWizardResult with empty strings, pass penpotBaseURL directly
- Replace default branch with explicit cases in VariablesSourceValidation
- Add ColorsConfigError.unsupportedSourceKind for proper error at config layer
- Inject TerminalUI explicitly into SourceFactory instead of global static access
- Remove unused sourceKind parameter from PenpotComponentsSource.loadComponents
- Fix leaked swiftlint:disable cyclomatic_complexity in DownloadImages

* chore: update cover

Author: alexey1312

.github/app-release-secrets.md

@@ -0,0 +1,122 @@
+# ExFig Studio Release Secrets Configuration
+
+This document describes the GitHub secrets required for automated ExFig Studio releases.
+
+## Required Secrets
+
+| Secret                        | Description                                         | Required For         |
+| ----------------------------- | --------------------------------------------------- | -------------------- |
+| `APPLE_TEAM_ID`               | Apple Developer Team ID (10-character alphanumeric) | Code signing         |
+| `APPLE_IDENTITY_NAME`         | Code signing identity name (e.g., "Your Name")      | Code signing         |
+| `APPLE_CERTIFICATE_BASE64`    | Developer ID certificate (.p12) as base64           | Code signing         |
+| `APPLE_CERTIFICATE_PASSWORD`  | Password for the .p12 certificate                   | Code signing         |
+| `APPLE_ID`                    | Apple ID email for notarization                     | Notarization         |
+| `APPLE_NOTARIZATION_PASSWORD` | App-specific password for notarization              | Notarization         |
+| `HOMEBREW_TAP_TOKEN`          | GitHub PAT with repo access to homebrew-exfig       | Homebrew Cask update |
+
+## Setup Instructions
+
+### 1. Export Developer ID Certificate
+
+```bash
+# Open Keychain Access, find "Developer ID Application" certificate
+# Right-click → Export → Save as .p12 with password
+
+# Encode to base64
+base64 -i DeveloperID.p12 | pbcopy
+# Paste into APPLE_CERTIFICATE_BASE64 secret
+```
+
+### 2. Create App-Specific Password
+
+1. Go to [appleid.apple.com](https://appleid.apple.com)
+2. Sign in and navigate to Security → App-Specific Passwords
+3. Generate a new password for "ExFig Studio Notarization"
+4. Save as `APPLE_NOTARIZATION_PASSWORD` secret
+
+### 3. Create Homebrew Tap Token
+
+1. Go to [github.com/settings/tokens](https://github.com/settings/tokens)
+2. Create a new PAT (classic) with `repo` scope
+3. Save as `HOMEBREW_TAP_TOKEN` secret
+
+### 4. Find Your Team ID
+
+```bash
+# If you have Xcode installed
+security find-identity -v -p codesigning | grep "Developer ID Application"
+# Team ID is in parentheses: "Developer ID Application: Name (TEAM_ID)"
+```
+
+## Release Process
+
+### Create a Release
+
+```bash
+# Tag format: studio-v<major>.<minor>.<patch>
+git tag studio-v1.0.0
+git push origin studio-v1.0.0
+```
+
+### Manual Build (for testing)
+
+```bash
+# Local build without signing
+./Scripts/build-app-release.sh
+
+# Local build with signing
+APPLE_TEAM_ID=YOUR_TEAM_ID ./Scripts/build-app-release.sh
+```
+
+### Workflow Dispatch
+
+You can also trigger a release manually from the GitHub Actions tab:
+
+1. Go to Actions → Release App
+2. Click "Run workflow"
+3. Enter the version number
+4. Optionally skip notarization for testing
+
+## Homebrew Cask
+
+After a successful release, the workflow automatically updates the Homebrew Cask formula at:
+`alexey1312/homebrew-exfig/Casks/exfig-studio.rb`
+
+Users can install with:
+
+```bash
+brew tap alexey1312/exfig
+brew install --cask exfig-studio
+```
+
+## Troubleshooting
+
+### Certificate Issues
+
+```bash
+# Verify certificate is in keychain
+security find-identity -v -p codesigning
+
+# Verify certificate chain
+codesign -vvv --deep "dist/ExFig Studio.app"
+```
+
+### Notarization Failures
+
+```bash
+# Check notarization status
+xcrun notarytool history --apple-id YOUR_APPLE_ID --team-id YOUR_TEAM_ID
+
+# Get detailed log for a submission
+xcrun notarytool log SUBMISSION_ID --apple-id YOUR_APPLE_ID --team-id YOUR_TEAM_ID
+```
+
+### Gatekeeper Issues
+
+```bash
+# Verify app is properly signed and notarized
+spctl --assess --verbose "dist/ExFig Studio.app"
+
+# Check stapling
+xcrun stapler validate "dist/ExFig Studio.app"
+```

.github/workflows/deploy-docc.yml

@@ -1,8 +1,10 @@
 name: Deploy DocC
 
 on:
-  release:
-    types: [published]
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+      - 'v[0-9]+.[0-9]+.[0-9]+-*'
   workflow_dispatch:
 
 permissions:

CLAUDE.md

@@ -260,6 +260,6 @@ exfig icons --concurrent-downloads 50  # Increase CDN parallelism
 ## Getting Help
 
 - Configuration reference: [CONFIG.md](CONFIG.md)
-- PKL guide: [docs/PKL.md](docs/PKL.md)
-- Migration guide (YAML to PKL): [MIGRATION.md](MIGRATION.md)
+- PKL guide: [PKLGuide](https://DesignPipe.github.io/exfig/documentation/exfigcli/pklguide)
+- Migration guide (YAML to PKL): [Migration](https://DesignPipe.github.io/exfig/documentation/exfigcli/migration)
 - Issues: [GitHub Issues](https://github.com/DesignPipe/exfig/issues)

MIGRATION_FROM_FIGMA_EXPORT.md

@@ -28,6 +28,7 @@ let package = Package(
         .package(url: "https://github.com/apple/pkl-swift", from: "0.8.0"),
         .package(url: "https://github.com/DesignPipe/swift-svgkit.git", from: "0.1.0"),
         .package(url: "https://github.com/DesignPipe/swift-figma-api.git", from: "0.2.0"),
+        .package(url: "https://github.com/DesignPipe/swift-penpot-api.git", from: "0.1.0"),
         .package(url: "https://github.com/modelcontextprotocol/swift-sdk.git", from: "0.9.0"),
     ],
     targets: [
@@ -36,6 +37,7 @@ let package = Package(
             name: "ExFigCLI",
             dependencies: [
                 .product(name: "FigmaAPI", package: "swift-figma-api"),
+                .product(name: "PenpotAPI", package: "swift-penpot-api"),
                 "ExFigCore",
                 "ExFigConfig",
                 "XcodeExport",
@@ -60,6 +62,7 @@ let package = Package(
             exclude: ["CLAUDE.md", "AGENTS.md"],
             resources: [
                 .copy("Resources/Schemas/"),
+                .copy("Resources/Guides/"),
             ]
         ),
 

Package.resolved

@@ -3,14 +3,15 @@
 [![CI](https://github.com/DesignPipe/exfig/actions/workflows/ci.yml/badge.svg)](https://github.com/DesignPipe/exfig/actions/workflows/ci.yml)
 [![Release](https://github.com/DesignPipe/exfig/actions/workflows/release.yml/badge.svg)](https://github.com/DesignPipe/exfig/actions/workflows/release.yml)
 [![Docs](https://github.com/DesignPipe/exfig/actions/workflows/deploy-docc.yml/badge.svg)](https://DesignPipe.github.io/exfig/documentation/exfigcli)
-![Coverage](https://img.shields.io/badge/coverage-50.65%25-yellow)
+![Coverage](https://img.shields.io/badge/coverage-43.65%25-yellow)
 [![License](https://img.shields.io/github/license/DesignPipe/exfig.svg)](LICENSE)
 
-Export colors, typography, icons, and images from Figma to Xcode, Android Studio, Flutter, and Web projects — automatically.
+Export colors, typography, icons, and images from Figma and Penpot to Xcode, Android Studio, Flutter, and Web projects — automatically.
 
 ## The Problem
 
 - Figma has no "Export to Xcode" button. You copy hex codes by hand, one by one.
+- Switching from Figma to Penpot? Your export pipeline shouldn't break.
 - Every color change means updating files across 3 platforms manually.
 - Dark mode variant? An afternoon spent on light/dark pairs and @1x/@2x/@3x PNGs.
 - Android gets XML. iOS gets xcassets. Flutter gets Dart. Someone maintains all three.
@@ -24,7 +25,7 @@ Export colors, typography, icons, and images from Figma to Xcode, Android Studio
 
 **Flutter developer** — You need dark mode icon variants and `@2x`/`@3x` image scales. ExFig exports SVG icons with dark suffixes, raster images with scale directories, and Dart constants.
 
-**Design Systems lead** — One Figma file feeds four platforms. ExFig's unified PKL config exports everything from a single `exfig batch` run. One CI pipeline, one source of truth.
+**Design Systems lead** — One Figma or Penpot file feeds four platforms. ExFig's unified PKL config exports everything from a single `exfig batch` run. One CI pipeline, one source of truth.
 
 **CI/CD engineer** — Quiet mode, JSON reports, exit codes, version tracking, and checkpoint/resume. The [GitHub Action](https://github.com/DesignPipe/exfig-action) handles installation and caching.
 
@@ -34,7 +35,7 @@ Export colors, typography, icons, and images from Figma to Xcode, Android Studio
 # 1. Install
 brew install designpipe/tap/exfig
 
-# 2. Set Figma token
+# 2. Set Figma token (or PENPOT_ACCESS_TOKEN for Penpot)
 export FIGMA_PERSONAL_TOKEN=your_token_here
 
 # 3a. Quick one-off export (interactive wizard)

Package.swift

@@ -14,8 +14,8 @@ public extension Android.IconsEntry {
     /// Returns an IconsSourceInput for use with IconsExportContext.
     func iconsSourceInput(darkFileId: String? = nil) -> IconsSourceInput {
         IconsSourceInput(
-            sourceKind: sourceKind?.coreSourceKind ?? .figma,
-            figmaFileId: figmaFileId,
+            sourceKind: resolvedSourceKind,
+            figmaFileId: resolvedFileId,
             darkFileId: darkFileId,
             frameName: figmaFrameName ?? "Icons",
             pageName: figmaPageName,
@@ -24,7 +24,8 @@ public extension Android.IconsEntry {
             darkModeSuffix: "_dark",
             rtlProperty: rtlProperty,
             nameValidateRegexp: nameValidateRegexp,
-            nameReplaceRegexp: nameReplaceRegexp
+            nameReplaceRegexp: nameReplaceRegexp,
+            penpotBaseURL: resolvedPenpotBaseURL
         )
     }
 

README.md

@@ -31,8 +31,8 @@ public extension Android.ImagesEntry {
     /// Returns an ImagesSourceInput for use with ImagesExportContext.
     func imagesSourceInput(darkFileId: String? = nil) -> ImagesSourceInput {
         ImagesSourceInput(
-            sourceKind: sourceKind?.coreSourceKind ?? .figma,
-            figmaFileId: figmaFileId,
+            sourceKind: resolvedSourceKind,
+            figmaFileId: resolvedFileId,
             darkFileId: darkFileId,
             frameName: figmaFrameName ?? "Images",
             pageName: figmaPageName,
@@ -42,7 +42,8 @@ public extension Android.ImagesEntry {
             darkModeSuffix: "_dark",
             rtlProperty: rtlProperty,
             nameValidateRegexp: nameValidateRegexp,
-            nameReplaceRegexp: nameReplaceRegexp
+            nameReplaceRegexp: nameReplaceRegexp,
+            penpotBaseURL: resolvedPenpotBaseURL
         )
     }
 

Sources/ExFig-Android/Config/AndroidIconsEntry.swift

@@ -11,16 +11,17 @@ public extension Flutter.IconsEntry {
     /// Returns an IconsSourceInput for use with IconsExportContext.
     func iconsSourceInput(darkFileId: String? = nil) -> IconsSourceInput {
         IconsSourceInput(
-            sourceKind: sourceKind?.coreSourceKind ?? .figma,
-            figmaFileId: figmaFileId,
+            sourceKind: resolvedSourceKind,
+            figmaFileId: resolvedFileId,
             darkFileId: darkFileId,
             frameName: figmaFrameName ?? "Icons",
             pageName: figmaPageName,
             useSingleFile: darkFileId == nil,
             darkModeSuffix: "_dark",
             rtlProperty: rtlProperty,
             nameValidateRegexp: nameValidateRegexp,
-            nameReplaceRegexp: nameReplaceRegexp
+            nameReplaceRegexp: nameReplaceRegexp,
+            penpotBaseURL: resolvedPenpotBaseURL
         )
     }