@payloadcms/figma 0.1.0-alpha.2 → 0.1.0-alpha.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (219) hide show
  1. package/dist/api/check-project-subdomain-availability.d.ts +12 -0
  2. package/dist/api/check-project-subdomain-availability.js +32 -0
  3. package/dist/api/control-plane-error.d.ts +6 -0
  4. package/dist/api/control-plane-error.js +8 -0
  5. package/dist/api/control-plane-fetch.d.ts +7 -0
  6. package/dist/api/control-plane-fetch.js +37 -0
  7. package/dist/api/control-plane.d.ts +1 -9
  8. package/dist/api/control-plane.js +2 -48
  9. package/dist/api/create-project.d.ts +18 -0
  10. package/dist/api/create-project.js +37 -0
  11. package/dist/api/list-project-workspaces.d.ts +8 -0
  12. package/dist/api/list-project-workspaces.js +28 -0
  13. package/dist/api/project-resource-type.d.ts +1 -0
  14. package/dist/api/project-resource-type.js +1 -0
  15. package/dist/auth/headless-oauth-flow.d.ts +23 -0
  16. package/dist/auth/headless-oauth-flow.js +69 -0
  17. package/dist/auth/oauth-flow.d.ts +2 -0
  18. package/dist/auth/oauth-flow.js +13 -8
  19. package/dist/auth/token-store.d.ts +4 -1
  20. package/dist/auth/token-store.js +14 -0
  21. package/dist/auth/types.d.ts +12 -0
  22. package/dist/cli.d.ts +39 -0
  23. package/dist/cli.js +71 -36
  24. package/dist/commands/bootstrap.js +2 -1
  25. package/dist/commands/deploy.d.ts +12 -0
  26. package/dist/commands/deploy.js +61 -23
  27. package/dist/commands/detect-project-resource-type.d.ts +3 -0
  28. package/dist/commands/detect-project-resource-type.js +28 -0
  29. package/dist/commands/init.d.ts +2 -2
  30. package/dist/commands/init.js +163 -78
  31. package/dist/commands/login.d.ts +11 -1
  32. package/dist/commands/login.js +66 -4
  33. package/dist/commands/prompt-to-create-project/format-project-subdomain.d.ts +1 -0
  34. package/dist/commands/prompt-to-create-project/format-project-subdomain.js +3 -0
  35. package/dist/commands/prompt-to-create-project/format-unavailable-subdomain-reason.d.ts +1 -0
  36. package/dist/commands/prompt-to-create-project/format-unavailable-subdomain-reason.js +7 -0
  37. package/dist/commands/prompt-to-create-project/get-default-project-name.d.ts +1 -0
  38. package/dist/commands/prompt-to-create-project/get-default-project-name.js +13 -0
  39. package/dist/commands/prompt-to-create-project/prompt-for-available-subdomain.d.ts +7 -0
  40. package/dist/commands/prompt-to-create-project/prompt-for-available-subdomain.js +32 -0
  41. package/dist/commands/prompt-to-create-project/resolve-project-region.d.ts +8 -0
  42. package/dist/commands/prompt-to-create-project/resolve-project-region.js +27 -0
  43. package/dist/commands/prompt-to-create-project/resolve-project-subdomain.d.ts +9 -0
  44. package/dist/commands/prompt-to-create-project/resolve-project-subdomain.js +54 -0
  45. package/dist/commands/prompt-to-create-project/resolve-text-input.d.ts +9 -0
  46. package/dist/commands/prompt-to-create-project/resolve-text-input.js +23 -0
  47. package/dist/commands/prompt-to-create-project/resolve-workspace-plan-key.d.ts +12 -0
  48. package/dist/commands/prompt-to-create-project/resolve-workspace-plan-key.js +36 -0
  49. package/dist/commands/prompt-to-create-project/validate-subdomain.d.ts +1 -0
  50. package/dist/commands/prompt-to-create-project/validate-subdomain.js +9 -0
  51. package/dist/commands/prompt-to-create-project.d.ts +24 -0
  52. package/dist/commands/prompt-to-create-project.js +69 -0
  53. package/dist/commands/setup-agent.d.ts +12 -0
  54. package/dist/commands/setup-agent.js +123 -0
  55. package/dist/commands/write-project-configuration.d.ts +12 -0
  56. package/dist/commands/write-project-configuration.js +16 -0
  57. package/dist/db-content-api/index.d.ts +1 -1
  58. package/dist/db-content-api/index.js +90 -55
  59. package/dist/db-content-api/utilities/data/injectGlobalType.d.ts +6 -0
  60. package/dist/db-content-api/utilities/data/injectGlobalType.js +11 -0
  61. package/dist/db-content-api/utilities/data/stringifyNumericIds.d.ts +1 -0
  62. package/dist/db-content-api/utilities/data/stringifyNumericIds.js +19 -0
  63. package/dist/db-content-api/utilities/isRecord.d.ts +9 -0
  64. package/dist/db-content-api/utilities/isRecord.js +19 -0
  65. package/dist/db-content-api/utilities/schema/getDocumentSchema.d.ts +3 -0
  66. package/dist/db-content-api/utilities/schema/getDocumentSchema.js +24 -0
  67. package/dist/db-content-api/utilities/where.js +6 -4
  68. package/dist/exports/client.d.ts +2 -0
  69. package/dist/exports/client.js +2 -0
  70. package/dist/lib/write-agent-config.d.ts +12 -0
  71. package/dist/lib/write-agent-config.js +52 -0
  72. package/dist/plugin/build-config.js +32 -3
  73. package/dist/plugin/cloud-limits/CloudLimitModal/index.d.ts +9 -0
  74. package/dist/plugin/cloud-limits/CloudLimitModal/index.js +78 -0
  75. package/dist/plugin/cloud-limits/CloudLimitModal/index.scss +51 -0
  76. package/dist/plugin/cloud-limits/CloudLimitProvider/index.d.ts +7 -0
  77. package/dist/plugin/cloud-limits/CloudLimitProvider/index.js +169 -0
  78. package/dist/plugin/cloud-limits/SlugRegistryContext/index.d.ts +2 -0
  79. package/dist/plugin/cloud-limits/SlugRegistryContext/index.js +3 -0
  80. package/dist/plugin/cloud-limits/SlugTracker/index.d.ts +9 -0
  81. package/dist/plugin/cloud-limits/SlugTracker/index.js +23 -0
  82. package/dist/plugin/cloud-limits/icons/ExternalLinkIcon.d.ts +2 -0
  83. package/dist/plugin/cloud-limits/icons/ExternalLinkIcon.js +30 -0
  84. package/dist/plugin/cloud-limits/shared.d.ts +10 -0
  85. package/dist/plugin/cloud-limits/shared.js +27 -0
  86. package/dist/skills/deploy-to-figma/SKILL.md +234 -0
  87. package/dist/skills/deploy-to-figma/references/cli-reference.md +146 -0
  88. package/dist/translations/ar.d.ts +12 -0
  89. package/dist/translations/ar.js +12 -0
  90. package/dist/translations/az.d.ts +12 -0
  91. package/dist/translations/az.js +12 -0
  92. package/dist/translations/bg.d.ts +12 -0
  93. package/dist/translations/bg.js +12 -0
  94. package/dist/translations/bnBd.d.ts +12 -0
  95. package/dist/translations/bnBd.js +12 -0
  96. package/dist/translations/bnIn.d.ts +12 -0
  97. package/dist/translations/bnIn.js +12 -0
  98. package/dist/translations/ca.d.ts +12 -0
  99. package/dist/translations/ca.js +12 -0
  100. package/dist/translations/cs.d.ts +12 -0
  101. package/dist/translations/cs.js +12 -0
  102. package/dist/translations/da.d.ts +12 -0
  103. package/dist/translations/da.js +12 -0
  104. package/dist/translations/de.d.ts +12 -0
  105. package/dist/translations/de.js +12 -0
  106. package/dist/translations/en.d.ts +12 -0
  107. package/dist/translations/en.js +12 -0
  108. package/dist/translations/es.d.ts +12 -0
  109. package/dist/translations/es.js +12 -0
  110. package/dist/translations/et.d.ts +12 -0
  111. package/dist/translations/et.js +12 -0
  112. package/dist/translations/fa.d.ts +12 -0
  113. package/dist/translations/fa.js +12 -0
  114. package/dist/translations/fr.d.ts +12 -0
  115. package/dist/translations/fr.js +12 -0
  116. package/dist/translations/he.d.ts +12 -0
  117. package/dist/translations/he.js +12 -0
  118. package/dist/translations/hr.d.ts +12 -0
  119. package/dist/translations/hr.js +12 -0
  120. package/dist/translations/hu.d.ts +12 -0
  121. package/dist/translations/hu.js +12 -0
  122. package/dist/translations/hy.d.ts +12 -0
  123. package/dist/translations/hy.js +12 -0
  124. package/dist/translations/id.d.ts +12 -0
  125. package/dist/translations/id.js +12 -0
  126. package/dist/translations/index.d.ts +533 -0
  127. package/dist/translations/index.js +90 -0
  128. package/dist/translations/is.d.ts +12 -0
  129. package/dist/translations/is.js +12 -0
  130. package/dist/translations/it.d.ts +12 -0
  131. package/dist/translations/it.js +12 -0
  132. package/dist/translations/ja.d.ts +12 -0
  133. package/dist/translations/ja.js +12 -0
  134. package/dist/translations/ko.d.ts +12 -0
  135. package/dist/translations/ko.js +12 -0
  136. package/dist/translations/lt.d.ts +12 -0
  137. package/dist/translations/lt.js +12 -0
  138. package/dist/translations/lv.d.ts +12 -0
  139. package/dist/translations/lv.js +12 -0
  140. package/dist/translations/my.d.ts +12 -0
  141. package/dist/translations/my.js +12 -0
  142. package/dist/translations/nb.d.ts +12 -0
  143. package/dist/translations/nb.js +12 -0
  144. package/dist/translations/nl.d.ts +12 -0
  145. package/dist/translations/nl.js +12 -0
  146. package/dist/translations/pl.d.ts +12 -0
  147. package/dist/translations/pl.js +12 -0
  148. package/dist/translations/pt.d.ts +12 -0
  149. package/dist/translations/pt.js +12 -0
  150. package/dist/translations/ro.d.ts +12 -0
  151. package/dist/translations/ro.js +12 -0
  152. package/dist/translations/rs.d.ts +12 -0
  153. package/dist/translations/rs.js +12 -0
  154. package/dist/translations/rsLatin.d.ts +12 -0
  155. package/dist/translations/rsLatin.js +12 -0
  156. package/dist/translations/ru.d.ts +12 -0
  157. package/dist/translations/ru.js +12 -0
  158. package/dist/translations/sk.d.ts +12 -0
  159. package/dist/translations/sk.js +12 -0
  160. package/dist/translations/sl.d.ts +12 -0
  161. package/dist/translations/sl.js +12 -0
  162. package/dist/translations/sv.d.ts +12 -0
  163. package/dist/translations/sv.js +12 -0
  164. package/dist/translations/ta.d.ts +12 -0
  165. package/dist/translations/ta.js +12 -0
  166. package/dist/translations/th.d.ts +12 -0
  167. package/dist/translations/th.js +12 -0
  168. package/dist/translations/tr.d.ts +12 -0
  169. package/dist/translations/tr.js +12 -0
  170. package/dist/translations/uk.d.ts +12 -0
  171. package/dist/translations/uk.js +12 -0
  172. package/dist/translations/vi.d.ts +12 -0
  173. package/dist/translations/vi.js +12 -0
  174. package/dist/translations/zh.d.ts +12 -0
  175. package/dist/translations/zh.js +12 -0
  176. package/dist/translations/zhTw.d.ts +12 -0
  177. package/dist/translations/zhTw.js +12 -0
  178. package/dist/types.d.ts +11 -0
  179. package/dist/utils/adapters/nextjs.d.ts +3 -3
  180. package/dist/utils/adapters/nextjs.js +9 -7
  181. package/dist/utils/adapters/nitro.d.ts +3 -3
  182. package/dist/utils/adapters/nitro.js +73 -77
  183. package/dist/utils/adapters/vite.d.ts +1 -1
  184. package/dist/utils/adapters/vite.js +8 -7
  185. package/dist/utils/assert-never.d.ts +1 -0
  186. package/dist/utils/assert-never.js +3 -0
  187. package/dist/utils/asset-collection.d.ts +2 -2
  188. package/dist/utils/asset-collection.js +10 -15
  189. package/dist/utils/build-detection.d.ts +6 -1
  190. package/dist/utils/build-detection.js +68 -89
  191. package/dist/utils/build-lambda-zip.d.ts +5 -6
  192. package/dist/utils/build-lambda-zip.js +31 -48
  193. package/dist/utils/deploy-adapter.d.ts +4 -4
  194. package/dist/utils/deploy-adapter.js +12 -8
  195. package/dist/utils/deploy-output/inspectNextjsOutput/getNextRelativeAppDir.d.ts +1 -0
  196. package/dist/utils/deploy-output/inspectNextjsOutput/getNextRelativeAppDir.js +15 -0
  197. package/dist/utils/deploy-output/inspectNextjsOutput.d.ts +12 -0
  198. package/dist/utils/deploy-output/inspectNextjsOutput.js +28 -0
  199. package/dist/utils/deploy-output/inspectNitroOutput.d.ts +9 -0
  200. package/dist/utils/deploy-output/inspectNitroOutput.js +13 -0
  201. package/dist/utils/deploy-output/isFile.d.ts +1 -0
  202. package/dist/utils/deploy-output/isFile.js +4 -0
  203. package/dist/utils/deploy-output/readJson.d.ts +1 -0
  204. package/dist/utils/deploy-output/readJson.js +9 -0
  205. package/dist/utils/deploy-output/resolveNitroOutputLayout.d.ts +8 -0
  206. package/dist/utils/deploy-output/resolveNitroOutputLayout.js +16 -0
  207. package/dist/utils/deploy-output/resolveOutputPath.d.ts +2 -0
  208. package/dist/utils/deploy-output/resolveOutputPath.js +9 -0
  209. package/dist/utils/deploy-output/resolveWithin.d.ts +1 -0
  210. package/dist/utils/deploy-output/resolveWithin.js +12 -0
  211. package/dist/utils/lambda-config.js +4 -14
  212. package/dist/utils/messages.js +24 -3
  213. package/dist/utils/payload-generate.d.ts +10 -0
  214. package/dist/utils/payload-generate.js +59 -0
  215. package/dist/utils/pnpm-builds.d.ts +14 -0
  216. package/dist/utils/pnpm-builds.js +125 -0
  217. package/package.json +6 -5
  218. package/dist/lib/download-skill.d.ts +0 -12
  219. package/dist/lib/download-skill.js +0 -77
@@ -0,0 +1,234 @@
1
+ ---
2
+ name: deploy-to-figma
3
+ description: This skill should be used when the user asks to "deploy to Figma", "publish to Figma", "ship to Figma", "deploy my app to Figma Cloud", "put this Payload site on Figma", or otherwise wants to deploy the current project to Figma Cloud. You (the agent) inspect, classify, and build the target project; the @payloadcms/figma CLI only authenticates and deploys the verified artifact you hand it.
4
+ version: 0.2.0
5
+ allowed-tools: Read, Bash, AskUserQuestion
6
+ ---
7
+
8
+ # Deploy to Figma Cloud
9
+
10
+ Deploy a project to Figma Cloud with the `@payloadcms/figma` CLI. **You** (the
11
+ agent) determine the deploy shape — you inspect the project, run the build, and
12
+ verify the real build artifacts, then hand the CLI an explicit adapter and
13
+ output root you have confirmed on disk. The CLI no longer inspects the project;
14
+ it only authenticates and ships the artifact you point it at.
15
+
16
+ **Golden rule:** detection is your job. Read files and inspect real artifacts —
17
+ do not ask `@payloadcms/figma` what framework this is, and do not guess. When the
18
+ evidence conflicts or the shape isn't one Figma Cloud supports, **stop** before
19
+ touching auth or deploy.
20
+
21
+ Run the CLI with `npx @payloadcms/figma@alpha <...>` **from the target folder**.
22
+ If a different invocation is already established in the repo (e.g.
23
+ `pnpm start --`), use that instead — but `npx @payloadcms/figma@alpha` is the
24
+ default.
25
+
26
+ If the user's request contains **“Figma staging”** (case-insensitive), append
27
+ `--infra-env staging` to every CLI invocation in this flow, including login,
28
+ login completion, deploy, and deploy retries. Otherwise omit the flag.
29
+
30
+ ## Flow overview
31
+
32
+ 1. **Resolve** the target project directory.
33
+ 2. **Inspect & classify** the deploy shape from evidence — or stop if unsupported/ambiguous.
34
+ 3. **Build & verify** the real artifact (buildable projects); static folders skip the build.
35
+ 4. **Detect initialization** from `target/.env`; gather creation inputs if uninitialized.
36
+ 5. **Preflight auth** with the resumable headless flow.
37
+ 6. **Deploy** the verified artifact with an explicit `--adapter` and `--output`.
38
+ 7. **Report** the deployed URL.
39
+
40
+ Exact CLI contracts (flags, JSON shapes, artifact signatures) live in
41
+ `references/cli-reference.md` — consult it when a flag or field is unclear.
42
+
43
+ ## Step 1 — Resolve the target directory
44
+
45
+ - If the prompt names a directory, that is the target.
46
+ - Otherwise use the current folder.
47
+ - In a **monorepo**, operate from the target **package** folder — not the repo
48
+ root. If several plausible apps exist and none is clearly the target, **ask**
49
+ via `AskUserQuestion` rather than guessing.
50
+
51
+ Every command and the build run **from the target folder**.
52
+
53
+ ## Step 2 — Inspect and classify the deploy shape
54
+
55
+ Gather evidence yourself with `Read`/`Bash`. Do **not** rely on
56
+ `@payloadcms/figma` for detection. Look at:
57
+
58
+ - `package.json` — `dependencies`/`devDependencies`, `scripts.build`, and
59
+ `packageManager`.
60
+ - Lockfiles — `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`.
61
+ - Framework config — `next.config.*`, `vite.config.*`, `nitro.config.*`,
62
+ `nuxt.config.*`, `app.config.*`.
63
+ - Source layout and any build artifacts already on disk.
64
+
65
+ Map the evidence to one **supported deploy shape**:
66
+
67
+ | Evidence | Shape | `--adapter` |
68
+ | --- | --- | --- |
69
+ | `next` dependency / `next.config.*` / a `next build` script | Next.js | `nextjs` |
70
+ | Nitro, Nuxt, TanStack Start, or any other evidenced Nitro output | Nitro | `nitro` |
71
+ | A built (or buildable) Vite single-page app | Vite | `vite` |
72
+ | A simple static folder — `index.html` plus CSS/JS/assets, no build needed (even with **no** `package.json`) | Static | `vite`, output = that folder |
73
+
74
+ If the evidence fits **none** of these, or points at **more than one** framework
75
+ with no clear winner, or you otherwise can't land confidently on one supported
76
+ shape → **go to Step 8 and stop**. Do not build, authenticate, or deploy.
77
+
78
+ ## Step 3 — Build and verify the artifact
79
+
80
+ **Buildable projects** (Next.js / Nitro / Vite): run the build **from the target
81
+ folder, before** any auth or project creation, with `FIGMA_EXTRACT_SCHEDULES=true`.
82
+
83
+ Pick the package manager by searching the **target folder and its ancestors**
84
+ (up to the repo/monorepo root) — in a monorepo the `packageManager` field and
85
+ the lockfile usually live at the workspace root, not in the target package.
86
+ Precedence: nearest `packageManager` field → nearest lockfile
87
+ (`pnpm-lock.yaml`→pnpm, `package-lock.json`→npm, `yarn.lock`→yarn,
88
+ `bun.lockb`→bun) → available tooling. Run the build itself **from the target
89
+ package folder** with whichever manager you resolved, e.g.:
90
+
91
+ ```bash
92
+ FIGMA_EXTRACT_SCHEDULES=true npm run build
93
+ ```
94
+
95
+ Then **inspect the actual artifacts** to confirm the adapter and the output
96
+ **root**:
97
+
98
+ - **Next.js** — the root contains `BUILD_ID` and standalone server output. Pass
99
+ the root (e.g. `.next`) — **never** `.next/standalone`.
100
+ - **Nitro** — the root contains `server/index.mjs` (typically `.output`).
101
+ - **Vite** — the root contains `index.html` (typically `dist`).
102
+
103
+ **Static folders** skip the build entirely. The output is the exact folder that
104
+ contains `index.html` (often `.`).
105
+
106
+ If the build fails, or the artifacts don't match the shape you classified (the
107
+ evidence now conflicts), **stop** — go to Step 8. Never pass an `--output` root
108
+ you have not confirmed exists on disk.
109
+
110
+ ## Step 4 — Detect initialization; gather creation inputs
111
+
112
+ Detect initialization **only** by testing whether `target/.env` contains a
113
+ nonempty `FIGMA_PROJECT_ID`, e.g.:
114
+
115
+ ```bash
116
+ test -f .env && grep -Eq '^FIGMA_PROJECT_ID=.+' .env && echo initialized || echo uninitialized
117
+ ```
118
+
119
+ Do **not** print the value or dump `.env`.
120
+
121
+ **Initialized** (`FIGMA_PROJECT_ID` present) → skip this step; pass no creation flags.
122
+
123
+ **Uninitialized** → gather the five project-creation fields across **two** grouped
124
+ `AskUserQuestion` interactions (a single call accepts at most four questions),
125
+ each field offering the CLI default so the user can accept as-is:
126
+
127
+ **Interaction 1 — naming** (three questions):
128
+
129
+ | Field | CLI default | Deploy flag |
130
+ | --- | --- | --- |
131
+ | Project name | derived from the directory name | `--name` |
132
+ | Description | `"<name> project"` | `--description` |
133
+ | Subdomain | slugified from the project name | `--subdomain` |
134
+
135
+ **Interaction 2 — placement** (two questions):
136
+
137
+ | Field | CLI default | Deploy flag |
138
+ | --- | --- | --- |
139
+ | Workspace | the account's default Figma workspace | `--workspace` |
140
+ | Region | `us-east-1` | `--region` |
141
+
142
+ Present the defaults as the recommended option. For any field left at its
143
+ default, **omit** the corresponding flag and let the CLI apply the default — only
144
+ pass a flag when the user supplied a non-default value.
145
+
146
+ ## Step 5 — Preflight authentication
147
+
148
+ The deploy command needs a valid credential and cannot open a browser in a
149
+ headless/agent context, so authenticate first with the resumable headless flow.
150
+
151
+ ```bash
152
+ npx @payloadcms/figma@alpha login --headless --json
153
+ ```
154
+
155
+ Parse `status`:
156
+
157
+ - `authenticated` — already logged in. Proceed to deploy.
158
+ - `authorization_required` — the JSON includes `authorizationUrl` and
159
+ `sessionId`. Give the user the `authorizationUrl`, ask them to open it,
160
+ approve, and paste back **the full redirected URL** (the
161
+ `http://localhost:.../callback?...` address the browser lands on). Then:
162
+
163
+ ```bash
164
+ npx @payloadcms/figma@alpha login --complete <sessionId> --callback-url '<redirect-url>' --json
165
+ ```
166
+
167
+ Quote the callback URL in single quotes. Expect `{"status":"authenticated",...}`.
168
+
169
+ **Handle the callback URL as a one-time secret:** pass it directly to the
170
+ `--complete` command and nothing else. Do not echo it back, summarize it, store
171
+ it in a file, or repeat it in later messages.
172
+
173
+ If completion fails, report the CLI's error and let the user retry the login
174
+ step; do not loop silently.
175
+
176
+ ## Step 6 — Deploy
177
+
178
+ Run **from the target folder**, non-interactively with `-y`. Always pass
179
+ `--skip-build` (you already built, or a static folder needs no build) and the
180
+ explicit `--adapter` / `--output` you verified in Steps 2–3:
181
+
182
+ ```bash
183
+ npx @payloadcms/figma@alpha deploy -y --skip-build --adapter <nextjs|nitro|vite> --output <verified-root>
184
+ ```
185
+
186
+ Add the project-creation flags from Step 4 only for an uninitialized project.
187
+
188
+ Examples:
189
+
190
+ ```bash
191
+ # Next.js app in a monorepo package (already initialized), built to .next
192
+ npx @payloadcms/figma@alpha deploy -y --skip-build --adapter nextjs --output .next
193
+
194
+ # Vite single-page app, built to dist
195
+ npx @payloadcms/figma@alpha deploy -y --skip-build --adapter vite --output dist
196
+
197
+ # Simple static folder (index.html at the folder root), no build
198
+ npx @payloadcms/figma@alpha deploy -y --skip-build --adapter vite --output .
199
+ ```
200
+
201
+ ### Deterministic retry — workspace selection
202
+
203
+ If deploy fails with a message like:
204
+
205
+ > Multiple eligible Figma workspaces. Pass --workspace `<plan-key>`. Available: Acme (plan_abc), Beta (plan_xyz)
206
+
207
+ re-run the exact same command with `--workspace <plan-key>` added, choosing the
208
+ plan key the user selected (ask via `AskUserQuestion` if not already known,
209
+ listing the workspaces from the error's `Available:` list). This is the only
210
+ retry to perform automatically. For other errors, surface the CLI message and stop.
211
+
212
+ ## Step 7 — Report the result
213
+
214
+ On success the CLI prints a line like `URL: https://<subdomain>.<domain>`.
215
+ Extract that URL and report it to the user as the deployed address, noting the
216
+ CLI's own message that a deploy usually takes 2–3 minutes to finish.
217
+
218
+ ## Step 8 — Unsupported or ambiguous → stop
219
+
220
+ If Steps 2–3 can't land confidently on one supported shape, **stop before auth
221
+ or deploy**. Tell the user what you found and quote the supported set:
222
+
223
+ > Figma Cloud supports Next.js, Vite single-page apps, and any Nitro-based app
224
+ > (including Nuxt and TanStack Start).
225
+
226
+ Never run `login` or `deploy` for an unsupported or ambiguous project. Decide
227
+ this **before** asking an uninitialized project's creation questions — never make
228
+ the user answer prompts only to fail on an unsupported framework.
229
+
230
+ ## Additional resources
231
+
232
+ - **`references/cli-reference.md`** — the deploy/login flags this skill uses, the
233
+ `login ... --json` JSON shapes, and the on-disk artifact signatures that
234
+ confirm each adapter and output root.
@@ -0,0 +1,146 @@
1
+ # @payloadcms/figma CLI reference (deploy-to-figma)
2
+
3
+ Exact contracts the orchestration depends on. Source of truth is the CLI itself
4
+ (`payload/payload-plugin` in figma/figma); this file mirrors the flags and shapes
5
+ the skill reads. If something is unclear, run the command and inspect the raw
6
+ output rather than guessing.
7
+
8
+ The CLI does **not** inspect the project — there is no `deploy --inspect` and no
9
+ project-inspection JSON API. The agent classifies the deploy shape from evidence
10
+ (see `SKILL.md` Steps 2–3) and hands the CLI an explicit `--adapter` and
11
+ `--output`.
12
+
13
+ ## Classifying the deploy shape (agent-driven)
14
+
15
+ Detect the shape yourself from files on disk. Do **not** call `@payloadcms/figma`
16
+ to detect it.
17
+
18
+ | Evidence | adapter | typical output root |
19
+ | --- | --- | --- |
20
+ | Next.js — `next` dep, `next.config.*`, or a `next build` script | `nextjs` | `.next` |
21
+ | Nitro / Nuxt / TanStack Start / other evidenced Nitro output | `nitro` | `.output` |
22
+ | Built Vite single-page app | `vite` | `dist` |
23
+ | Simple static folder — `index.html` + CSS/JS/assets, no build (no `package.json` OK) | `vite` | the folder itself (often `.`) |
24
+
25
+ Framework config hints: Next.js `distDir` (`next.config.*`), Vite `build.outDir`
26
+ (`vite.config.*`), Nitro/Nuxt `output.dir` (`nitro.config.*` / `nuxt.config.*`).
27
+ Custom output dirs mean you must confirm the real root against artifacts below.
28
+
29
+ ### On-disk artifact signatures (confirm before deploy)
30
+
31
+ After building (or for a static folder, as-is), confirm the output **root** by
32
+ what it contains:
33
+
34
+ - **Next.js** — root contains `BUILD_ID` **and** standalone server output. Pass
35
+ the root such as `.next`; **never** `.next/standalone`.
36
+ - **Nitro** — root contains `server/index.mjs` (typically `.output`).
37
+ - **Vite / static** — root contains `index.html` (typically `dist`; a static
38
+ folder may be `.`).
39
+
40
+ If the build fails or the artifacts don't match the classified shape, **stop** —
41
+ do not pass an unverified `--output`.
42
+
43
+ ## Building
44
+
45
+ Run the target package's build **from the target folder**, before auth, with
46
+ `FIGMA_EXTRACT_SCHEDULES=true`. Choose the package manager by searching the
47
+ target folder **and its ancestors** (up to the repo/monorepo root) — the
48
+ `packageManager` field and the lockfile often live at the workspace root, not
49
+ the target package. Precedence: nearest `packageManager` field → nearest
50
+ lockfile (`pnpm-lock.yaml`→pnpm, `package-lock.json`→npm, `yarn.lock`→yarn,
51
+ `bun.lockb`→bun) → available tooling. Even so, run the build itself from the
52
+ target package folder. Static folders skip the build.
53
+
54
+ ```bash
55
+ FIGMA_EXTRACT_SCHEDULES=true npm run build
56
+ ```
57
+
58
+ ## `login --headless --json`
59
+
60
+ Starts (or short-circuits) a resumable login without a live terminal.
61
+
62
+ Already authenticated:
63
+
64
+ ```json
65
+ { "status": "authenticated", "userId": "..." }
66
+ ```
67
+
68
+ Authorization required:
69
+
70
+ ```json
71
+ {
72
+ "status": "authorization_required",
73
+ "authorizationUrl": "https://www.figma.com/oauth?...",
74
+ "sessionId": "sess_...",
75
+ "expiresAt": 1730000000000
76
+ }
77
+ ```
78
+
79
+ ## `login --complete <sessionId> --callback-url '<url>' --json`
80
+
81
+ Completes a pending headless login using the full redirect URL the browser
82
+ landed on (`http://localhost:<port>/callback?code=...&state=...`). Returns:
83
+
84
+ ```json
85
+ { "status": "authenticated", "userId": "..." }
86
+ ```
87
+
88
+ Treat the callback URL as a one-time secret: pass it once, never echo or persist it.
89
+
90
+ ## Infrastructure environment
91
+
92
+ When the user's request contains “Figma staging” (case-insensitive), append
93
+ `--infra-env staging` to every CLI command, including login, login completion,
94
+ deploy, and deploy retries. Otherwise omit the flag.
95
+
96
+ ## `deploy` flags used by this skill
97
+
98
+ The deploy command is always explicit — the agent supplies the verified adapter
99
+ and output root and skips the build (it already ran, or the folder is static):
100
+
101
+ ```bash
102
+ npx @payloadcms/figma@alpha deploy -y --skip-build --adapter <nextjs|nitro|vite> --output <root>
103
+ ```
104
+
105
+ | Flag | Purpose |
106
+ | --- | --- |
107
+ | `-y`, `--yes` | Non-interactive; safe project-creation defaults |
108
+ | `--infra-env staging` | Target Figma staging when explicitly requested |
109
+ | `--skip-build` | Always passed — deploy the artifact as-is, never rebuild |
110
+ | `--adapter <name>` | `nextjs` \| `vite` \| `nitro` — the shape you classified |
111
+ | `--output <path>` | The exact, verified build output root |
112
+ | `--name <name>` | Project name (uninitialized project creation) |
113
+ | `--description <text>` | Project description (uninitialized) |
114
+ | `--subdomain <sub>` | Requested subdomain (uninitialized) |
115
+ | `--workspace <planKey>` | Workspace plan key (uninitialized; also the retry flag) |
116
+ | `--region <region>` | Region, e.g. `us-east-1` (uninitialized) |
117
+
118
+ Initialization is detected only by a nonempty `FIGMA_PROJECT_ID` in `target/.env`
119
+ (never printed). Initialized projects pass no creation flags.
120
+
121
+ ## Deterministic deploy retry
122
+
123
+ When multiple eligible workspaces exist and none is a default, non-interactive
124
+ deploy fails with:
125
+
126
+ ```text
127
+ Multiple eligible Figma workspaces. Pass --workspace <plan-key>. Available: <Name> (<plan-key>), ...
128
+ ```
129
+
130
+ Re-run the identical command with `--workspace <plan-key>` for the chosen
131
+ workspace. An invalid `--workspace` value fails with:
132
+
133
+ ```text
134
+ Workspace plan key "<key>" is not eligible. Available: <Name> (<plan-key>), ...
135
+ ```
136
+
137
+ ## Success output
138
+
139
+ On success the CLI prints:
140
+
141
+ ```text
142
+ URL: https://<subdomain>.<domain>
143
+ This usually takes 2-3 minutes to complete.
144
+ ```
145
+
146
+ Extract the `URL:` line as the deployed address.
@@ -0,0 +1,12 @@
1
+ export declare const arTranslations: {
2
+ figma: {
3
+ cloudLimitAssetStorageError: string;
4
+ cloudLimitDocumentCountError: string;
5
+ cloudLimitDocumentDataSizeError: string;
6
+ cloudLimitModalBody: string;
7
+ cloudLimitModalConfirm: string;
8
+ cloudLimitModalHeading: string;
9
+ cloudLimitModalRetry: string;
10
+ cloudLimitModalReviewCollection: string;
11
+ };
12
+ };
@@ -0,0 +1,12 @@
1
+ export const arTranslations = {
2
+ figma: {
3
+ cloudLimitAssetStorageError: 'يتعذر التحميل. يرجى تحرير بعض المساحة للمتابعة.',
4
+ cloudLimitDocumentCountError: 'غير قادر على إنشاء وثيقة. تم الوصول إلى الحد الأقصى لسعة التخزين.',
5
+ cloudLimitDocumentDataSizeError: 'تعذر حفظ المستند، النص كبير جدًا.',
6
+ cloudLimitModalBody: 'لقد وصلت إلى الحد الأقصى لعدد الوثائق. يرجى حذف بعض الوثائق الحالية لمواصلة الإنشاء.',
7
+ cloudLimitModalConfirm: 'تم فهم ذلك',
8
+ cloudLimitModalHeading: 'تعذر حفظ المستند',
9
+ cloudLimitModalRetry: 'إعادة المحاولة',
10
+ cloudLimitModalReviewCollection: 'مراجعة {{collection}}'
11
+ }
12
+ };
@@ -0,0 +1,12 @@
1
+ export declare const azTranslations: {
2
+ figma: {
3
+ cloudLimitAssetStorageError: string;
4
+ cloudLimitDocumentCountError: string;
5
+ cloudLimitDocumentDataSizeError: string;
6
+ cloudLimitModalBody: string;
7
+ cloudLimitModalConfirm: string;
8
+ cloudLimitModalHeading: string;
9
+ cloudLimitModalRetry: string;
10
+ cloudLimitModalReviewCollection: string;
11
+ };
12
+ };
@@ -0,0 +1,12 @@
1
+ export const azTranslations = {
2
+ figma: {
3
+ cloudLimitAssetStorageError: 'Yükləmək mümkün deyil. Davam etmək üçün yer boşaldın.',
4
+ cloudLimitDocumentCountError: 'Sənəd yaratmaq mümkün deyil. Saxlama limiti aşılmışdır.',
5
+ cloudLimitDocumentDataSizeError: 'Sənədi saxlamaq mümkün deyil, mətn çox böyükdür.',
6
+ cloudLimitModalBody: 'Sənəd limitinizə çatdınız. Yenilərini yaratmaq üçün mövcud sənədlərdən bəzilərini silin.',
7
+ cloudLimitModalConfirm: 'Başa düşdüm',
8
+ cloudLimitModalHeading: 'Sənədi yadda saxlamaq mümkün olmadı',
9
+ cloudLimitModalRetry: 'Təkrar cəhd edin',
10
+ cloudLimitModalReviewCollection: '{{collection}}-ə baxış'
11
+ }
12
+ };
@@ -0,0 +1,12 @@
1
+ export declare const bgTranslations: {
2
+ figma: {
3
+ cloudLimitAssetStorageError: string;
4
+ cloudLimitDocumentCountError: string;
5
+ cloudLimitDocumentDataSizeError: string;
6
+ cloudLimitModalBody: string;
7
+ cloudLimitModalConfirm: string;
8
+ cloudLimitModalHeading: string;
9
+ cloudLimitModalRetry: string;
10
+ cloudLimitModalReviewCollection: string;
11
+ };
12
+ };
@@ -0,0 +1,12 @@
1
+ export const bgTranslations = {
2
+ figma: {
3
+ cloudLimitAssetStorageError: 'Не може да се качи. Освободете пространство, за да продължите.',
4
+ cloudLimitDocumentCountError: 'Неуспешно създаване на документ. Достигнат е лимитът за съхранение.',
5
+ cloudLimitDocumentDataSizeError: 'Неуспешно записване на документа, текстът е твърде голям.',
6
+ cloudLimitModalBody: 'Достигнали сте лимита на вашите документи. Изтрийте някои съществуващи документи, за да продължите да създавате нови.',
7
+ cloudLimitModalConfirm: 'Разбрах',
8
+ cloudLimitModalHeading: 'Неуспешно запазване на документа',
9
+ cloudLimitModalRetry: 'Опитайте отново.',
10
+ cloudLimitModalReviewCollection: 'Преглед на {{collection}}'
11
+ }
12
+ };
@@ -0,0 +1,12 @@
1
+ export declare const bnBdTranslations: {
2
+ figma: {
3
+ cloudLimitAssetStorageError: string;
4
+ cloudLimitDocumentCountError: string;
5
+ cloudLimitDocumentDataSizeError: string;
6
+ cloudLimitModalBody: string;
7
+ cloudLimitModalConfirm: string;
8
+ cloudLimitModalHeading: string;
9
+ cloudLimitModalRetry: string;
10
+ cloudLimitModalReviewCollection: string;
11
+ };
12
+ };
@@ -0,0 +1,12 @@
1
+ export const bnBdTranslations = {
2
+ figma: {
3
+ cloudLimitAssetStorageError: 'আপলোড করা সম্ভব হচ্ছে না। চালিয়ে যেতে হলে স্থান খালি করুন।',
4
+ cloudLimitDocumentCountError: 'দস্তাবেজ তৈরি করা সম্ভব নয়। সংরক্ষণ সীমা অতিক্রম করা হয়েছে।',
5
+ cloudLimitDocumentDataSizeError: 'ডকুমেন্ট সংরক্ষণ করা সম্ভব নয়, কারণ পাঠ্যটি খুব বড়।',
6
+ cloudLimitModalBody: 'আপনি আপনার document সীমা অতিক্রম করেছেন। নতুনভাবে তৈরি করতে হলে কিছু বিদ্যমান document মুছে ফেলুন।',
7
+ cloudLimitModalConfirm: 'বুঝেছি',
8
+ cloudLimitModalHeading: 'ডকুমেন্ট সংরক্ষণ করা যায়নি',
9
+ cloudLimitModalRetry: 'পুনঃচেষ্টা করুন',
10
+ cloudLimitModalReviewCollection: '{{collection}} পর্যালোচনা করুন'
11
+ }
12
+ };
@@ -0,0 +1,12 @@
1
+ export declare const bnInTranslations: {
2
+ figma: {
3
+ cloudLimitAssetStorageError: string;
4
+ cloudLimitDocumentCountError: string;
5
+ cloudLimitDocumentDataSizeError: string;
6
+ cloudLimitModalBody: string;
7
+ cloudLimitModalConfirm: string;
8
+ cloudLimitModalHeading: string;
9
+ cloudLimitModalRetry: string;
10
+ cloudLimitModalReviewCollection: string;
11
+ };
12
+ };
@@ -0,0 +1,12 @@
1
+ export const bnInTranslations = {
2
+ figma: {
3
+ cloudLimitAssetStorageError: 'আপলোড করা সম্ভব হচ্ছে না। চালিয়ে যেতে হলে স্থান খালি করুন।',
4
+ cloudLimitDocumentCountError: 'ডকুমেন্ট তৈরি করা সম্ভব হয়নি। সংরক্ষণ সীমা অতিক্রম করা হয়েছে।',
5
+ cloudLimitDocumentDataSizeError: 'নথিটি সংরক্ষণ করা সম্ভব নয়, কারণ টেক্সটের আকার অত্যন্ত বড়।',
6
+ cloudLimitModalBody: 'আপনি আপনার document সীমায় পৌঁছেছেন। নতুন তৈরি করতে থাকলে কিছু বিদ্যমান document মুছে ফেলুন।',
7
+ cloudLimitModalConfirm: 'বুঝেছি',
8
+ cloudLimitModalHeading: 'ডকুমেন্ট সংরক্ষণ করা যায়নি',
9
+ cloudLimitModalRetry: 'পুনরায় চেষ্টা করুন',
10
+ cloudLimitModalReviewCollection: '{{collection}} পর্যালোচনা করুন'
11
+ }
12
+ };
@@ -0,0 +1,12 @@
1
+ export declare const caTranslations: {
2
+ figma: {
3
+ cloudLimitAssetStorageError: string;
4
+ cloudLimitDocumentCountError: string;
5
+ cloudLimitDocumentDataSizeError: string;
6
+ cloudLimitModalBody: string;
7
+ cloudLimitModalConfirm: string;
8
+ cloudLimitModalHeading: string;
9
+ cloudLimitModalRetry: string;
10
+ cloudLimitModalReviewCollection: string;
11
+ };
12
+ };
@@ -0,0 +1,12 @@
1
+ export const caTranslations = {
2
+ figma: {
3
+ cloudLimitAssetStorageError: 'No es pot carregar. Allibereu espai per continuar.',
4
+ cloudLimitDocumentCountError: "No es pot crear el document. S'ha assolit el límit d'emmagatzematge.",
5
+ cloudLimitDocumentDataSizeError: 'No es pot desar el document, el text és massa extens.',
6
+ cloudLimitModalBody: 'Heu arribat al límit de documents. Suprimiu alguns documents existents per tal de poder continuar creant.',
7
+ cloudLimitModalConfirm: 'Entès',
8
+ cloudLimitModalHeading: "No s'ha pogut desar el document",
9
+ cloudLimitModalRetry: 'Torna-ho a intentar',
10
+ cloudLimitModalReviewCollection: 'Revisió de la {{collection}}'
11
+ }
12
+ };
@@ -0,0 +1,12 @@
1
+ export declare const csTranslations: {
2
+ figma: {
3
+ cloudLimitAssetStorageError: string;
4
+ cloudLimitDocumentCountError: string;
5
+ cloudLimitDocumentDataSizeError: string;
6
+ cloudLimitModalBody: string;
7
+ cloudLimitModalConfirm: string;
8
+ cloudLimitModalHeading: string;
9
+ cloudLimitModalRetry: string;
10
+ cloudLimitModalReviewCollection: string;
11
+ };
12
+ };
@@ -0,0 +1,12 @@
1
+ export const csTranslations = {
2
+ figma: {
3
+ cloudLimitAssetStorageError: 'Nelze nahrát. Uvolněte místo pro pokračování.',
4
+ cloudLimitDocumentCountError: 'Nelze vytvořit dokument. Byla dosažena kapacita úložiště.',
5
+ cloudLimitDocumentDataSizeError: 'Nelze uložit dokument, text je příliš rozsáhlý.',
6
+ cloudLimitModalBody: 'Dosáhli jste limitu dokumentů. Odstraňte některé stávající dokumenty, abyste mohli pokračovat ve vytváření.',
7
+ cloudLimitModalConfirm: 'Rozumím',
8
+ cloudLimitModalHeading: 'Dokument nebylo možné uložit',
9
+ cloudLimitModalRetry: 'Opakovat',
10
+ cloudLimitModalReviewCollection: 'Zkontrolujte {{collection}}'
11
+ }
12
+ };
@@ -0,0 +1,12 @@
1
+ export declare const daTranslations: {
2
+ figma: {
3
+ cloudLimitAssetStorageError: string;
4
+ cloudLimitDocumentCountError: string;
5
+ cloudLimitDocumentDataSizeError: string;
6
+ cloudLimitModalBody: string;
7
+ cloudLimitModalConfirm: string;
8
+ cloudLimitModalHeading: string;
9
+ cloudLimitModalRetry: string;
10
+ cloudLimitModalReviewCollection: string;
11
+ };
12
+ };
@@ -0,0 +1,12 @@
1
+ export const daTranslations = {
2
+ figma: {
3
+ cloudLimitAssetStorageError: 'Kan ikke uploade. Frigør plads for at fortsætte.',
4
+ cloudLimitDocumentCountError: 'Kan ikke oprette dokument. Lagringsgrænsen er nået.',
5
+ cloudLimitDocumentDataSizeError: 'Kan ikke gemme dokument, teksten er for stor.',
6
+ cloudLimitModalBody: 'Du har nået din dokumentgrænse. Slet nogle eksisterende dokumenter for at kunne fortsætte med at oprette.',
7
+ cloudLimitModalConfirm: 'Forstået',
8
+ cloudLimitModalHeading: 'Kunne ikke gemme dokument',
9
+ cloudLimitModalRetry: 'Prøv igen',
10
+ cloudLimitModalReviewCollection: 'Gennemgå {{collection}}'
11
+ }
12
+ };
@@ -0,0 +1,12 @@
1
+ export declare const deTranslations: {
2
+ figma: {
3
+ cloudLimitAssetStorageError: string;
4
+ cloudLimitDocumentCountError: string;
5
+ cloudLimitDocumentDataSizeError: string;
6
+ cloudLimitModalBody: string;
7
+ cloudLimitModalConfirm: string;
8
+ cloudLimitModalHeading: string;
9
+ cloudLimitModalRetry: string;
10
+ cloudLimitModalReviewCollection: string;
11
+ };
12
+ };
@@ -0,0 +1,12 @@
1
+ export const deTranslations = {
2
+ figma: {
3
+ cloudLimitAssetStorageError: 'Hochladen nicht möglich. Bitte schaffen Sie Speicherplatz, um fortzufahren.',
4
+ cloudLimitDocumentCountError: 'Dokument kann nicht erstellt werden. Speicherlimit erreicht.',
5
+ cloudLimitDocumentDataSizeError: 'Dokument kann nicht gespeichert werden, der Text ist zu umfangreich.',
6
+ cloudLimitModalBody: 'Sie haben Ihr Dokumentenlimit erreicht. Löschen Sie einige bestehende Dokumente, um weitere erstellen zu können.',
7
+ cloudLimitModalConfirm: 'Verstanden',
8
+ cloudLimitModalHeading: 'Dokument konnte nicht gespeichert werden',
9
+ cloudLimitModalRetry: 'Wiederholen',
10
+ cloudLimitModalReviewCollection: 'Überprüfung der {{collection}}'
11
+ }
12
+ };
@@ -0,0 +1,12 @@
1
+ export declare const en: {
2
+ figma: {
3
+ cloudLimitAssetStorageError: string;
4
+ cloudLimitDocumentCountError: string;
5
+ cloudLimitDocumentDataSizeError: string;
6
+ cloudLimitModalBody: string;
7
+ cloudLimitModalConfirm: string;
8
+ cloudLimitModalHeading: string;
9
+ cloudLimitModalRetry: string;
10
+ cloudLimitModalReviewCollection: string;
11
+ };
12
+ };
@@ -0,0 +1,12 @@
1
+ export const en = {
2
+ figma: {
3
+ cloudLimitAssetStorageError: 'Unable to upload. Free up space to continue.',
4
+ cloudLimitDocumentCountError: 'Unable to create document. Storage limit reached.',
5
+ cloudLimitDocumentDataSizeError: 'Unable to save document, text is too large.',
6
+ cloudLimitModalBody: 'You have reached your document limit. Delete some existing documents in order to keep creating.',
7
+ cloudLimitModalConfirm: 'Got it',
8
+ cloudLimitModalHeading: "Couldn't save document",
9
+ cloudLimitModalRetry: 'Retry',
10
+ cloudLimitModalReviewCollection: 'Review {{collection}}'
11
+ }
12
+ };