primitive-admin 1.2.0-alpha.14 → 1.2.0-alpha.16

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 (400) hide show
  1. package/README.md +181 -73
  2. package/assets/skill/skills/primitive-platform/SKILL.md +87 -23
  3. package/dist/bin/primitive.js +11 -82
  4. package/dist/bin/primitive.js.map +1 -1
  5. package/dist/src/commands/admins.js +80 -17
  6. package/dist/src/commands/admins.js.map +1 -1
  7. package/dist/src/commands/agent-sessions.js +2 -0
  8. package/dist/src/commands/agent-sessions.js.map +1 -1
  9. package/dist/src/commands/analytics.js +181 -12
  10. package/dist/src/commands/analytics.js.map +1 -1
  11. package/dist/src/commands/apps-children.js +2 -0
  12. package/dist/src/commands/apps-children.js.map +1 -1
  13. package/dist/src/commands/apps-transitions.d.ts +39 -0
  14. package/dist/src/commands/apps-transitions.js +198 -0
  15. package/dist/src/commands/apps-transitions.js.map +1 -0
  16. package/dist/src/commands/apps.d.ts +11 -0
  17. package/dist/src/commands/apps.js +65 -3
  18. package/dist/src/commands/apps.js.map +1 -1
  19. package/dist/src/commands/auth-sessions.js +2 -0
  20. package/dist/src/commands/auth-sessions.js.map +1 -1
  21. package/dist/src/commands/auth.js +16 -1
  22. package/dist/src/commands/auth.js.map +1 -1
  23. package/dist/src/commands/blob-buckets.js +2 -0
  24. package/dist/src/commands/blob-buckets.js.map +1 -1
  25. package/dist/src/commands/collections.js +2 -0
  26. package/dist/src/commands/collections.js.map +1 -1
  27. package/dist/src/commands/comparisons.js +2 -0
  28. package/dist/src/commands/comparisons.js.map +1 -1
  29. package/dist/src/commands/config.d.ts +1 -1
  30. package/dist/src/commands/config.js +42 -9
  31. package/dist/src/commands/config.js.map +1 -1
  32. package/dist/src/commands/connections.js +2 -0
  33. package/dist/src/commands/connections.js.map +1 -1
  34. package/dist/src/commands/database-type-configs.js +5 -3
  35. package/dist/src/commands/database-type-configs.js.map +1 -1
  36. package/dist/src/commands/databases.js +6 -4
  37. package/dist/src/commands/databases.js.map +1 -1
  38. package/dist/src/commands/db3-types.js +2 -0
  39. package/dist/src/commands/db3-types.js.map +1 -1
  40. package/dist/src/commands/db3.d.ts +12 -0
  41. package/dist/src/commands/db3.js +408 -31
  42. package/dist/src/commands/db3.js.map +1 -1
  43. package/dist/src/commands/documents.d.ts +52 -12
  44. package/dist/src/commands/documents.js +120 -29
  45. package/dist/src/commands/documents.js.map +1 -1
  46. package/dist/src/commands/email-templates.js +74 -0
  47. package/dist/src/commands/email-templates.js.map +1 -1
  48. package/dist/src/commands/env.js +2 -0
  49. package/dist/src/commands/env.js.map +1 -1
  50. package/dist/src/commands/functions.js +90 -11
  51. package/dist/src/commands/functions.js.map +1 -1
  52. package/dist/src/commands/groups.js +20 -3
  53. package/dist/src/commands/groups.js.map +1 -1
  54. package/dist/src/commands/guides.js +2 -0
  55. package/dist/src/commands/guides.js.map +1 -1
  56. package/dist/src/commands/hosting.d.ts +8 -0
  57. package/dist/src/commands/hosting.js +346 -0
  58. package/dist/src/commands/hosting.js.map +1 -0
  59. package/dist/src/commands/init.js +9 -1
  60. package/dist/src/commands/init.js.map +1 -1
  61. package/dist/src/commands/integrations.js +82 -47
  62. package/dist/src/commands/integrations.js.map +1 -1
  63. package/dist/src/commands/locks.js +2 -0
  64. package/dist/src/commands/locks.js.map +1 -1
  65. package/dist/src/commands/metadata-category-configs.js +2 -0
  66. package/dist/src/commands/metadata-category-configs.js.map +1 -1
  67. package/dist/src/commands/metadata.js +41 -0
  68. package/dist/src/commands/metadata.js.map +1 -1
  69. package/dist/src/commands/prompts.js +75 -47
  70. package/dist/src/commands/prompts.js.map +1 -1
  71. package/dist/src/commands/rate-counters.d.ts +19 -0
  72. package/dist/src/commands/rate-counters.js +104 -0
  73. package/dist/src/commands/rate-counters.js.map +1 -0
  74. package/dist/src/commands/rule-sets.js +2 -0
  75. package/dist/src/commands/rule-sets.js.map +1 -1
  76. package/dist/src/commands/schemas.d.ts +15 -0
  77. package/dist/src/commands/schemas.js +122 -0
  78. package/dist/src/commands/schemas.js.map +1 -0
  79. package/dist/src/commands/secrets.js +47 -3
  80. package/dist/src/commands/secrets.js.map +1 -1
  81. package/dist/src/commands/sessions.js +2 -0
  82. package/dist/src/commands/sessions.js.map +1 -1
  83. package/dist/src/commands/skill.js +2 -0
  84. package/dist/src/commands/skill.js.map +1 -1
  85. package/dist/src/commands/sync-schemas.d.ts +202 -0
  86. package/dist/src/commands/sync-schemas.js +629 -0
  87. package/dist/src/commands/sync-schemas.js.map +1 -0
  88. package/dist/src/commands/sync-user-properties.d.ts +118 -0
  89. package/dist/src/commands/sync-user-properties.js +276 -0
  90. package/dist/src/commands/sync-user-properties.js.map +1 -0
  91. package/dist/src/commands/sync.d.ts +344 -14
  92. package/dist/src/commands/sync.js +1834 -345
  93. package/dist/src/commands/sync.js.map +1 -1
  94. package/dist/src/commands/tokens.js +2 -0
  95. package/dist/src/commands/tokens.js.map +1 -1
  96. package/dist/src/commands/transitions.d.ts +54 -0
  97. package/dist/src/commands/transitions.js +418 -0
  98. package/dist/src/commands/transitions.js.map +1 -0
  99. package/dist/src/commands/usage.d.ts +18 -0
  100. package/dist/src/commands/usage.js +343 -0
  101. package/dist/src/commands/usage.js.map +1 -0
  102. package/dist/src/commands/user-properties.d.ts +14 -0
  103. package/dist/src/commands/user-properties.js +79 -0
  104. package/dist/src/commands/user-properties.js.map +1 -0
  105. package/dist/src/commands/users.js +878 -16
  106. package/dist/src/commands/users.js.map +1 -1
  107. package/dist/src/commands/vars.js +2 -0
  108. package/dist/src/commands/vars.js.map +1 -1
  109. package/dist/src/commands/waitlist.js +39 -4
  110. package/dist/src/commands/waitlist.js.map +1 -1
  111. package/dist/src/lib/analytics-query.d.ts +58 -0
  112. package/dist/src/lib/analytics-query.js +134 -0
  113. package/dist/src/lib/analytics-query.js.map +1 -0
  114. package/dist/src/lib/api-client.d.ts +1354 -97
  115. package/dist/src/lib/api-client.js +513 -164
  116. package/dist/src/lib/api-client.js.map +1 -1
  117. package/dist/src/lib/app-settings-descriptor.d.ts +1 -1
  118. package/dist/src/lib/app-settings-descriptor.js +6 -0
  119. package/dist/src/lib/app-settings-descriptor.js.map +1 -1
  120. package/dist/src/lib/auth-flow.d.ts +33 -0
  121. package/dist/src/lib/auth-flow.js +404 -13
  122. package/dist/src/lib/auth-flow.js.map +1 -1
  123. package/dist/src/lib/block-selector.d.ts +9 -15
  124. package/dist/src/lib/block-selector.js +9 -20
  125. package/dist/src/lib/block-selector.js.map +1 -1
  126. package/dist/src/lib/cli-manifest.d.ts +9 -0
  127. package/dist/src/lib/cli-manifest.js +10 -1
  128. package/dist/src/lib/cli-manifest.js.map +1 -1
  129. package/dist/src/lib/cli-version.d.ts +14 -0
  130. package/dist/src/lib/cli-version.js +38 -0
  131. package/dist/src/lib/cli-version.js.map +1 -0
  132. package/dist/src/lib/codegen-shared/prettierStable.d.ts +41 -0
  133. package/dist/src/lib/codegen-shared/prettierStable.js +146 -24
  134. package/dist/src/lib/codegen-shared/prettierStable.js.map +1 -1
  135. package/dist/src/lib/command-groups.d.ts +30 -0
  136. package/dist/src/lib/command-groups.js +109 -0
  137. package/dist/src/lib/command-groups.js.map +1 -0
  138. package/dist/src/lib/command-status.d.ts +147 -0
  139. package/dist/src/lib/command-status.js +266 -0
  140. package/dist/src/lib/command-status.js.map +1 -0
  141. package/dist/src/lib/config-object-descriptor.d.ts +6 -0
  142. package/dist/src/lib/config-object-descriptor.js +71 -1
  143. package/dist/src/lib/config-object-descriptor.js.map +1 -1
  144. package/dist/src/lib/config-toml.d.ts +11 -2
  145. package/dist/src/lib/config-toml.js +25 -2
  146. package/dist/src/lib/config-toml.js.map +1 -1
  147. package/dist/src/lib/data-input.d.ts +1 -1
  148. package/dist/src/lib/data-input.js +1 -1
  149. package/dist/src/lib/db-codegen/dbTsTypes.d.ts +1 -1
  150. package/dist/src/lib/db-codegen/dbTsTypes.js +3 -0
  151. package/dist/src/lib/db-codegen/dbTsTypes.js.map +1 -1
  152. package/dist/src/lib/db-codegen/dbTypeIR.d.ts +18 -1
  153. package/dist/src/lib/db-codegen/dbTypeIR.js +14 -5
  154. package/dist/src/lib/db-codegen/dbTypeIR.js.map +1 -1
  155. package/dist/src/lib/db-type-records.d.ts +106 -0
  156. package/dist/src/lib/db-type-records.js +224 -0
  157. package/dist/src/lib/db-type-records.js.map +1 -0
  158. package/dist/src/lib/db3-export.d.ts +51 -14
  159. package/dist/src/lib/db3-export.js +136 -28
  160. package/dist/src/lib/db3-export.js.map +1 -1
  161. package/dist/src/lib/db3-index-output.d.ts +92 -4
  162. package/dist/src/lib/db3-index-output.js +183 -11
  163. package/dist/src/lib/db3-index-output.js.map +1 -1
  164. package/dist/src/lib/db3-type-models.d.ts +49 -7
  165. package/dist/src/lib/db3-type-models.js +159 -28
  166. package/dist/src/lib/db3-type-models.js.map +1 -1
  167. package/dist/src/lib/deprecation.d.ts +2 -2
  168. package/dist/src/lib/deprecation.js +2 -2
  169. package/dist/src/lib/experimental-apis.d.ts +36 -0
  170. package/dist/src/lib/experimental-apis.js +46 -0
  171. package/dist/src/lib/experimental-apis.js.map +1 -0
  172. package/dist/src/lib/file-attachment.d.ts +24 -0
  173. package/dist/src/lib/file-attachment.js +31 -0
  174. package/dist/src/lib/file-attachment.js.map +1 -0
  175. package/dist/src/lib/function-authorize-check.d.ts +1 -1
  176. package/dist/src/lib/function-authorize-check.js +2 -1
  177. package/dist/src/lib/function-authorize-check.js.map +1 -1
  178. package/dist/src/lib/function-authorize-view.d.ts +12 -0
  179. package/dist/src/lib/function-authorize-view.js +38 -0
  180. package/dist/src/lib/function-authorize-view.js.map +1 -1
  181. package/dist/src/lib/function-bundle.d.ts +27 -5
  182. package/dist/src/lib/function-bundle.js +106 -7
  183. package/dist/src/lib/function-bundle.js.map +1 -1
  184. package/dist/src/lib/function-collect.d.ts +15 -0
  185. package/dist/src/lib/function-collect.js +73 -14
  186. package/dist/src/lib/function-collect.js.map +1 -1
  187. package/dist/src/lib/function-db-types.d.ts +63 -40
  188. package/dist/src/lib/function-db-types.js +289 -293
  189. package/dist/src/lib/function-db-types.js.map +1 -1
  190. package/dist/src/lib/function-document-types.d.ts +19 -7
  191. package/dist/src/lib/function-document-types.js +24 -12
  192. package/dist/src/lib/function-document-types.js.map +1 -1
  193. package/dist/src/lib/function-lint.d.ts +24 -1
  194. package/dist/src/lib/function-lint.js +123 -1
  195. package/dist/src/lib/function-lint.js.map +1 -1
  196. package/dist/src/lib/function-run.d.ts +1 -1
  197. package/dist/src/lib/function-run.js +1 -1
  198. package/dist/src/lib/function-run.js.map +1 -1
  199. package/dist/src/lib/function-schema-codegen.d.ts +85 -21
  200. package/dist/src/lib/function-schema-codegen.js +191 -85
  201. package/dist/src/lib/function-schema-codegen.js.map +1 -1
  202. package/dist/src/lib/function-schema-refs.d.ts +98 -0
  203. package/dist/src/lib/function-schema-refs.js +177 -0
  204. package/dist/src/lib/function-schema-refs.js.map +1 -0
  205. package/dist/src/lib/function-sync.d.ts +38 -4
  206. package/dist/src/lib/function-sync.js +91 -14
  207. package/dist/src/lib/function-sync.js.map +1 -1
  208. package/dist/src/lib/function-typecheck.d.ts +52 -0
  209. package/dist/src/lib/function-typecheck.js +171 -54
  210. package/dist/src/lib/function-typecheck.js.map +1 -1
  211. package/dist/src/lib/generated-build-flags.d.ts +13 -0
  212. package/dist/src/lib/generated-build-flags.js +14 -0
  213. package/dist/src/lib/generated-build-flags.js.map +1 -0
  214. package/dist/src/lib/generated-command-status.d.ts +6 -0
  215. package/dist/src/lib/generated-command-status.js +469 -0
  216. package/dist/src/lib/generated-command-status.js.map +1 -0
  217. package/dist/src/lib/generated-config-surfaces.d.ts +239 -14
  218. package/dist/src/lib/generated-config-surfaces.js +670 -85
  219. package/dist/src/lib/generated-config-surfaces.js.map +1 -1
  220. package/dist/src/lib/generated-sdk-types.d.ts +1 -1
  221. package/dist/src/lib/generated-sdk-types.js +1 -1
  222. package/dist/src/lib/generated-sdk-types.js.map +1 -1
  223. package/dist/src/lib/hosting-build.d.ts +97 -0
  224. package/dist/src/lib/hosting-build.js +204 -0
  225. package/dist/src/lib/hosting-build.js.map +1 -0
  226. package/dist/src/lib/hosting-client.d.ts +167 -0
  227. package/dist/src/lib/hosting-client.js +340 -0
  228. package/dist/src/lib/hosting-client.js.map +1 -0
  229. package/dist/src/lib/hosting-environments.d.ts +32 -0
  230. package/dist/src/lib/hosting-environments.js +74 -0
  231. package/dist/src/lib/hosting-environments.js.map +1 -0
  232. package/dist/src/lib/hosting-errors.d.ts +30 -0
  233. package/dist/src/lib/hosting-errors.js +43 -0
  234. package/dist/src/lib/hosting-errors.js.map +1 -0
  235. package/dist/src/lib/hosting-token.d.ts +46 -0
  236. package/dist/src/lib/hosting-token.js +60 -0
  237. package/dist/src/lib/hosting-token.js.map +1 -0
  238. package/dist/src/lib/hosting-wait.d.ts +42 -0
  239. package/dist/src/lib/hosting-wait.js +84 -0
  240. package/dist/src/lib/hosting-wait.js.map +1 -0
  241. package/dist/src/lib/hosting-wfp-upload.d.ts +86 -0
  242. package/dist/src/lib/hosting-wfp-upload.js +149 -0
  243. package/dist/src/lib/hosting-wfp-upload.js.map +1 -0
  244. package/dist/src/lib/integration-test-request.d.ts +54 -0
  245. package/dist/src/lib/integration-test-request.js +207 -0
  246. package/dist/src/lib/integration-test-request.js.map +1 -0
  247. package/dist/src/lib/invoker-shared-enums.d.ts +35 -0
  248. package/dist/src/lib/invoker-shared-enums.js +98 -0
  249. package/dist/src/lib/invoker-shared-enums.js.map +1 -0
  250. package/dist/src/lib/log-inspection.d.ts +4 -1
  251. package/dist/src/lib/log-inspection.js.map +1 -1
  252. package/dist/src/lib/metadata-report.d.ts +85 -0
  253. package/dist/src/lib/metadata-report.js +81 -0
  254. package/dist/src/lib/metadata-report.js.map +1 -0
  255. package/dist/src/lib/output.d.ts +1 -1
  256. package/dist/src/lib/output.js +1 -1
  257. package/dist/src/lib/platform-owned.js +5 -0
  258. package/dist/src/lib/platform-owned.js.map +1 -1
  259. package/dist/src/lib/primitive-declaration-names.d.ts +21 -0
  260. package/dist/src/lib/primitive-declaration-names.js +22 -0
  261. package/dist/src/lib/primitive-declaration-names.js.map +1 -0
  262. package/dist/src/lib/primitive-declaration.d.ts +174 -0
  263. package/dist/src/lib/primitive-declaration.js +792 -0
  264. package/dist/src/lib/primitive-declaration.js.map +1 -0
  265. package/dist/src/lib/prompt-schema-codegen.d.ts +36 -12
  266. package/dist/src/lib/prompt-schema-codegen.js +94 -98
  267. package/dist/src/lib/prompt-schema-codegen.js.map +1 -1
  268. package/dist/src/lib/prompt-schema-document.d.ts +35 -0
  269. package/dist/src/lib/prompt-schema-document.js +92 -0
  270. package/dist/src/lib/prompt-schema-document.js.map +1 -0
  271. package/dist/src/lib/prompt-schema-refs.d.ts +173 -0
  272. package/dist/src/lib/prompt-schema-refs.js +478 -0
  273. package/dist/src/lib/prompt-schema-refs.js.map +1 -0
  274. package/dist/src/lib/records-verbs.d.ts +12 -2
  275. package/dist/src/lib/records-verbs.js +7 -2
  276. package/dist/src/lib/records-verbs.js.map +1 -1
  277. package/dist/src/lib/register-commands.d.ts +36 -0
  278. package/dist/src/lib/register-commands.js +37 -0
  279. package/dist/src/lib/register-commands.js.map +1 -0
  280. package/dist/src/lib/retired-imports.d.ts +53 -0
  281. package/dist/src/lib/retired-imports.js +120 -0
  282. package/dist/src/lib/retired-imports.js.map +1 -0
  283. package/dist/src/lib/schema-codegen/compiledSpace.d.ts +62 -0
  284. package/dist/src/lib/schema-codegen/compiledSpace.js +103 -0
  285. package/dist/src/lib/schema-codegen/compiledSpace.js.map +1 -0
  286. package/dist/src/lib/schema-codegen/generated-db3-bridge.d.ts +86 -0
  287. package/dist/src/lib/schema-codegen/generated-db3-bridge.js +227 -0
  288. package/dist/src/lib/schema-codegen/generated-db3-bridge.js.map +1 -0
  289. package/dist/src/lib/schema-codegen/generated-db3-query-capabilities.d.ts +85 -0
  290. package/dist/src/lib/schema-codegen/generated-db3-query-capabilities.js +86 -0
  291. package/dist/src/lib/schema-codegen/generated-db3-query-capabilities.js.map +1 -0
  292. package/dist/src/lib/schema-codegen/generated-field-grammar.d.ts +218 -0
  293. package/dist/src/lib/schema-codegen/generated-field-grammar.js +397 -0
  294. package/dist/src/lib/schema-codegen/generated-field-grammar.js.map +1 -0
  295. package/dist/src/lib/schema-codegen/generated-field-table.d.ts +80 -0
  296. package/dist/src/lib/schema-codegen/generated-field-table.js +542 -0
  297. package/dist/src/lib/schema-codegen/generated-field-table.js.map +1 -0
  298. package/dist/src/lib/schema-codegen/generated-prompt-schemas.d.ts +195 -0
  299. package/dist/src/lib/schema-codegen/generated-prompt-schemas.js +503 -0
  300. package/dist/src/lib/schema-codegen/generated-prompt-schemas.js.map +1 -0
  301. package/dist/src/lib/schema-codegen/generated-schema-descriptor.d.ts +129 -0
  302. package/dist/src/lib/schema-codegen/generated-schema-descriptor.js +154 -1
  303. package/dist/src/lib/schema-codegen/generated-schema-descriptor.js.map +1 -1
  304. package/dist/src/lib/schema-codegen/generated-schema-file.d.ts +129 -0
  305. package/dist/src/lib/schema-codegen/generated-schema-file.js +475 -0
  306. package/dist/src/lib/schema-codegen/generated-schema-file.js.map +1 -0
  307. package/dist/src/lib/schema-codegen/generated-schema-provenance.d.ts +115 -0
  308. package/dist/src/lib/schema-codegen/generated-schema-provenance.js +274 -0
  309. package/dist/src/lib/schema-codegen/generated-schema-provenance.js.map +1 -0
  310. package/dist/src/lib/schema-codegen/generated-schema-refs.d.ts +366 -0
  311. package/dist/src/lib/schema-codegen/generated-schema-refs.js +1789 -0
  312. package/dist/src/lib/schema-codegen/generated-schema-refs.js.map +1 -0
  313. package/dist/src/lib/schema-codegen/generated-schema-shape.d.ts +27 -0
  314. package/dist/src/lib/schema-codegen/generated-schema-shape.js +126 -0
  315. package/dist/src/lib/schema-codegen/generated-schema-shape.js.map +1 -0
  316. package/dist/src/lib/schema-codegen/namedRefs.d.ts +56 -0
  317. package/dist/src/lib/schema-codegen/namedRefs.js +143 -0
  318. package/dist/src/lib/schema-codegen/namedRefs.js.map +1 -0
  319. package/dist/src/lib/schema-codegen/schemaChanges.d.ts +74 -0
  320. package/dist/src/lib/schema-codegen/schemaChanges.js +277 -0
  321. package/dist/src/lib/schema-codegen/schemaChanges.js.map +1 -0
  322. package/dist/src/lib/schema-codegen/schemaDocs.d.ts +69 -0
  323. package/dist/src/lib/schema-codegen/schemaDocs.js +219 -0
  324. package/dist/src/lib/schema-codegen/schemaDocs.js.map +1 -0
  325. package/dist/src/lib/schema-codegen/schemaIR.d.ts +158 -0
  326. package/dist/src/lib/schema-codegen/schemaIR.js +279 -0
  327. package/dist/src/lib/schema-codegen/schemaIR.js.map +1 -0
  328. package/dist/src/lib/schema-codegen/schemaToTs.d.ts +40 -13
  329. package/dist/src/lib/schema-codegen/schemaToTs.js +124 -160
  330. package/dist/src/lib/schema-codegen/schemaToTs.js.map +1 -1
  331. package/dist/src/lib/schema-codegen/valuesLists.d.ts +48 -0
  332. package/dist/src/lib/schema-codegen/valuesLists.js +144 -0
  333. package/dist/src/lib/schema-codegen/valuesLists.js.map +1 -0
  334. package/dist/src/lib/schema-family-index.d.ts +228 -0
  335. package/dist/src/lib/schema-family-index.js +813 -0
  336. package/dist/src/lib/schema-family-index.js.map +1 -0
  337. package/dist/src/lib/schema-pins.d.ts +82 -0
  338. package/dist/src/lib/schema-pins.js +198 -0
  339. package/dist/src/lib/schema-pins.js.map +1 -0
  340. package/dist/src/lib/schema-preview.d.ts +244 -0
  341. package/dist/src/lib/schema-preview.js +498 -0
  342. package/dist/src/lib/schema-preview.js.map +1 -0
  343. package/dist/src/lib/skill-installer.d.ts +2 -2
  344. package/dist/src/lib/skill-installer.js +2 -21
  345. package/dist/src/lib/skill-installer.js.map +1 -1
  346. package/dist/src/lib/step-run-table.d.ts +1 -2
  347. package/dist/src/lib/step-run-table.js +1 -2
  348. package/dist/src/lib/step-run-table.js.map +1 -1
  349. package/dist/src/lib/swift-codegen/agentGenerator.d.ts +2 -1
  350. package/dist/src/lib/swift-codegen/agentGenerator.js +24 -22
  351. package/dist/src/lib/swift-codegen/agentGenerator.js.map +1 -1
  352. package/dist/src/lib/swift-codegen/banners.d.ts +12 -0
  353. package/dist/src/lib/swift-codegen/banners.js +12 -0
  354. package/dist/src/lib/swift-codegen/banners.js.map +1 -1
  355. package/dist/src/lib/swift-codegen/functionGenerator.d.ts +36 -1
  356. package/dist/src/lib/swift-codegen/functionGenerator.js +168 -50
  357. package/dist/src/lib/swift-codegen/functionGenerator.js.map +1 -1
  358. package/dist/src/lib/swift-codegen/schemaToSwift.d.ts +31 -7
  359. package/dist/src/lib/swift-codegen/schemaToSwift.js +213 -177
  360. package/dist/src/lib/swift-codegen/schemaToSwift.js.map +1 -1
  361. package/dist/src/lib/swift-codegen/sharedGenerator.d.ts +45 -0
  362. package/dist/src/lib/swift-codegen/sharedGenerator.js +165 -0
  363. package/dist/src/lib/swift-codegen/sharedGenerator.js.map +1 -0
  364. package/dist/src/lib/swift-codegen/userPropertiesGenerator.d.ts +30 -0
  365. package/dist/src/lib/swift-codegen/userPropertiesGenerator.js +69 -0
  366. package/dist/src/lib/swift-codegen/userPropertiesGenerator.js.map +1 -0
  367. package/dist/src/lib/sync-resource-types.d.ts +37 -5
  368. package/dist/src/lib/sync-resource-types.js +50 -5
  369. package/dist/src/lib/sync-resource-types.js.map +1 -1
  370. package/dist/src/lib/sync-selectors.d.ts +7 -0
  371. package/dist/src/lib/sync-selectors.js +22 -2
  372. package/dist/src/lib/sync-selectors.js.map +1 -1
  373. package/dist/src/lib/test-runs.d.ts +45 -0
  374. package/dist/src/lib/test-runs.js +150 -0
  375. package/dist/src/lib/test-runs.js.map +1 -0
  376. package/dist/src/lib/toml-database-config.d.ts +2 -1
  377. package/dist/src/lib/toml-database-config.js +7 -4
  378. package/dist/src/lib/toml-database-config.js.map +1 -1
  379. package/dist/src/lib/toml-scalar-edit.js +6 -4
  380. package/dist/src/lib/toml-scalar-edit.js.map +1 -1
  381. package/dist/src/lib/transition-warnings.d.ts +21 -0
  382. package/dist/src/lib/transition-warnings.js +49 -0
  383. package/dist/src/lib/transition-warnings.js.map +1 -0
  384. package/dist/src/lib/user-index.d.ts +80 -0
  385. package/dist/src/lib/user-index.js +166 -0
  386. package/dist/src/lib/user-index.js.map +1 -0
  387. package/dist/src/lib/user-properties/generated-properties-schema.d.ts +159 -0
  388. package/dist/src/lib/user-properties/generated-properties-schema.js +471 -0
  389. package/dist/src/lib/user-properties/generated-properties-schema.js.map +1 -0
  390. package/dist/src/lib/user-properties/user-properties-codegen.d.ts +55 -0
  391. package/dist/src/lib/user-properties/user-properties-codegen.js +129 -0
  392. package/dist/src/lib/user-properties/user-properties-codegen.js.map +1 -0
  393. package/dist/src/lib/user-walk.d.ts +31 -0
  394. package/dist/src/lib/user-walk.js +102 -0
  395. package/dist/src/lib/user-walk.js.map +1 -0
  396. package/dist/src/lib/worker-perf-format.d.ts +22 -0
  397. package/dist/src/lib/worker-perf-format.js +27 -0
  398. package/dist/src/lib/worker-perf-format.js.map +1 -0
  399. package/dist/src/types/index.d.ts +13 -34
  400. package/package.json +5 -3
package/README.md CHANGED
@@ -82,7 +82,7 @@ primitive -e prod login
82
82
  # Login to a custom server from outside a project
83
83
  PRIMITIVE_SERVER_URL=https://api.example.com primitive login
84
84
 
85
- # View current session
85
+ # View current session, including your app-creation limit
86
86
  primitive whoami
87
87
 
88
88
  # Get access token for scripting
@@ -163,7 +163,7 @@ Manage applications (requires admin access).
163
163
  ```bash
164
164
  primitive apps list # List all accessible apps
165
165
  primitive apps create "My App" # Create a new app (mints the app id)
166
- primitive apps get <app-id> # Get app details
166
+ primitive apps get <app-id> # Get app details (a child's parent and lineage too)
167
167
  primitive apps delete <app-id> # Delete an app
168
168
  ```
169
169
 
@@ -193,7 +193,8 @@ primitive users set-role [app-id] <user-id> <role> # Change role
193
193
  primitive users set-profile [app-id] <user-id> [--name <name>] [--avatar-url <url> | --clear-avatar] # Set display name/avatar
194
194
  primitive users transfer-owner [app-id] <new-owner-id> # Transfer ownership
195
195
  primitive users mint-jwt <user-id> [--role <role>] # Mint test JWT (dev/test only)
196
- primitive users invitations [app-id] # List pending invitations
196
+ primitive users invitations list [app-id] [--limit <n>] [--cursor <c>] # List invitations with status and accept link
197
+ primitive users invitations revoke <invitation-id> # Revoke an invitation (and an admin's console invitation)
197
198
  ```
198
199
 
199
200
  ### Waitlist
@@ -203,7 +204,8 @@ Manage waitlist entries for apps in waitlist mode.
203
204
  ```bash
204
205
  primitive waitlist list [app-id] # List waitlist entries
205
206
  primitive waitlist invite [app-id] <waitlist-id> # Invite from waitlist
206
- primitive waitlist bulk-invite [app-id] -n 10 # Bulk invite
207
+ primitive waitlist bulk-invite [app-id] -n 10 # Bulk invite the next 10 in line
208
+ primitive waitlist bulk-invite [app-id] --ids <id,...> # Bulk invite the named entries
207
209
  primitive waitlist remove [app-id] <waitlist-id> # Remove from waitlist
208
210
  ```
209
211
 
@@ -215,6 +217,9 @@ Manage HTTP integrations (external API connections).
215
217
  primitive integrations list [app-id] # List integrations
216
218
  primitive integrations get <integration-id> # Get details
217
219
  primitive integrations test <id> # Test connection
220
+ primitive integrations test <id> --method POST --path /upload \
221
+ --header 'X-Request-Id: abc' --field title=Report --file document=@./report.pdf
222
+ # --form, --raw-body <path|-> [--content-type] also
218
223
  primitive integrations logs <id> # View invocation logs
219
224
  ```
220
225
 
@@ -227,6 +232,19 @@ primitive config create integration weather-api # scaffold the file
227
232
  primitive config push --only integration/weather-api
228
233
  ```
229
234
 
235
+ **Tests** take the integration's key or ID:
236
+
237
+ ```bash
238
+ primitive integrations tests list <integration> [--limit <n>] [--cursor <cursor>]
239
+ primitive integrations tests run-all <integration>
240
+ primitive integrations tests runs <integration> [--limit <n>] [--cursor <cursor>] # One page of runs
241
+ primitive integrations tests runs get <integration> <run-id> # One run: output and checks
242
+ primitive comparisons get <group> # Every run of one run-all batch
243
+ ```
244
+
245
+ `tests runs` no longer takes `--group`; read a batch's runs with
246
+ `comparisons get <group>`. An integration keyed `get` is listed by its ID.
247
+
230
248
  **Secrets management:**
231
249
 
232
250
  Integration-scoped secrets are **retired** — the `primitive integrations secrets`
@@ -241,6 +259,7 @@ Manage encrypted app secrets (API keys, tokens, credentials). Values are encrypt
241
259
  ```bash
242
260
  primitive secrets list [--app <app-id>] # List secrets (values never shown)
243
261
  primitive secrets set <KEY> --value <value> [--summary <text>] # Create or update a secret
262
+ primitive secrets set <KEY> --summary <text> | --clear-summary # Change a summary; the value is unchanged
244
263
  primitive secrets delete <KEY> # Delete a secret
245
264
  ```
246
265
 
@@ -262,6 +281,7 @@ Manage LLM prompt configurations.
262
281
  primitive prompts list [app-id] # List prompts
263
282
  primitive prompts get <prompt-id> # Get details
264
283
  primitive prompts execute <id> --vars '{}' # Execute prompt
284
+ primitive prompts execute <id> --attach ./report.pdf # Execute with a file attachment (repeatable)
265
285
  primitive prompts preview <id> --vars '{}' # Preview rendered template
266
286
  ```
267
287
 
@@ -281,45 +301,37 @@ primitive prompts configs list <prompt-id>
281
301
  primitive prompts configs get <prompt> <config>
282
302
  ```
283
303
 
284
- ### Workflows (retained history)
285
-
286
- DSL workflows are retired (#3190): nothing creates, changes or runs one. Write
287
- the logic as a server function (`primitive config create function <key>`). The
288
- definitions, configurations and revisions an app stored stay readable until
289
- their retention expires:
304
+ **Tests** take the prompt's key or ID:
290
305
 
291
306
  ```bash
292
- primitive workflows list [app-id] # Retained definitions
293
- primitive workflows get <workflow-id-or-key> # One, with configs and revisions
294
- primitive workflows configs list <workflow-id-or-key> # Its configurations
295
- primitive workflows configs get <workflow-id-or-key> <config-id>
307
+ primitive prompts tests list <prompt> [--limit <n>] [--cursor <cursor>]
308
+ primitive prompts tests run-all <prompt>
309
+ primitive prompts tests runs <prompt> [--limit <n>] [--cursor <cursor>] # One page of runs
310
+ primitive prompts tests runs get <prompt> <run-id> # One run: output and checks
311
+ primitive comparisons get <group> # Every run of one run-all batch
296
312
  ```
297
313
 
298
- A config tree that still holds `workflows/` or `transforms/` is refused by
299
- `config push` and reported by `config diff`, naming the migration page.
314
+ `tests runs` no longer takes `--group`; read a batch's runs with
315
+ `comparisons get <group>`. A prompt keyed `get` is listed by its ID.
300
316
 
301
- **A configuration object's field surface has ONE definition (issue #2644):**
302
- `src/config-surface/` on the server records, per configuration object, which
303
- `models.yaml` fields exist, which TOML key each carries, which modes the server
304
- accepts it in, and — for a field with real behavior — the handler that owns it.
305
- The server's create/update handlers take their accepted key set from it
306
- (`pickWritableFields`), and `cli/scripts/gen-config-surfaces.mjs` vendors the
307
- same modules into the committed artifact
308
- `cli/src/lib/generated-config-surfaces.ts`, which the CLI's push builder, pull
309
- serializer and TOML key validation read. The generator runs automatically at CLI
310
- `prebuild`; regenerate manually with `node cli/scripts/gen-config-surfaces.mjs`
311
- (or `pnpm -C cli gen:config-surfaces`).
317
+ ### Email Templates
312
318
 
313
- Three hard-fail checks live in `cli/tests/unit/config-surface-drift-guard.test.ts`:
314
- freshness (`--check`, a byte comparison), coverage (every model field of every
315
- registered object is either exposed or classified `notExposed` **with a
316
- reason**), and registry existence (every `SYNC_RESOURCE_TYPES` label has a
317
- definition — the migration's `PENDING_MIGRATION` exemption list is gone, so
318
- there is nowhere to park one). Add a
319
- field to `models.yaml` and the CLI unit suite fails until you regenerate and
320
- classify it — so the CLI can no longer silently drop a new server-side field.
321
- This supersedes the workflow-only descriptor and generator from #2326.
319
+ Read and preview the emails Primitive sends for an app.
322
320
 
321
+ ```bash
322
+ primitive email-templates list [app-id] # Email types and override status
323
+ primitive email-templates get <type> # Current template for a type
324
+ primitive email-templates variables <type> # Variables the type substitutes
325
+ primitive email-templates preview <type> [--vars '<json>'] # Render without sending
326
+ primitive email-templates test <type> # Send a test email
327
+ ```
328
+
329
+ `preview` renders the server's saved template (or the built-in default) with the type's sample values; `--vars` overrides them, e.g. `--vars '{"appName":"Acme"}'`. An override is authored in `email-templates/<emailType>.toml` and applied with `config push`:
330
+
331
+ ```bash
332
+ primitive config create email-template email-sign-in
333
+ primitive config push --only email-template/email-sign-in
334
+ ```
323
335
 
324
336
  ### Tokens
325
337
 
@@ -340,7 +352,14 @@ primitive tokens revoke <token-id> [app-id] # Revoke t
340
352
 
341
353
  ### Databases
342
354
 
343
- Manage online databases and permissions. `list` returns databases the user has direct access to; group-shared databases are listed via `primitive groups databases`.
355
+ A database is a `db3` on the CLI:
356
+
357
+ ```bash
358
+ primitive db3 list --custodian <app|user:<user-id>> [--limit <n>] [--cursor <c>] # Databases one custodian holds
359
+ primitive db3 list --user-id <user-id> [--via held,shared,app] # Every database a user can open, sync-off included
360
+ ```
361
+
362
+ Legacy online databases and their permissions: `list` returns databases the user has direct access to; group-shared databases are listed via `primitive groups databases`.
344
363
 
345
364
  ```bash
346
365
  primitive databases list [app-id] # List databases (direct access)
@@ -365,17 +384,6 @@ primitive metadata set database <database-id> <category> --data '{"key":"value"}
365
384
  primitive metadata get database <database-id> <category> # Read it back
366
385
  ```
367
386
 
368
- **Operations:**
369
- ```bash
370
- primitive databases operations list <database-id> [--app <app-id>] # List registered operations
371
- primitive databases operations execute <database-id> <op-name> --params '{}' # Execute operation
372
- primitive databases operations execute <database-id> <op-name> --token <jwt> # Execute as specific user
373
- ```
374
-
375
- The `--token` flag lets you execute an operation as a specific user using a test JWT from `users mint-jwt`. Useful for testing access rules.
376
-
377
- Under `--json`, the printed shape is the operation's own. A `query` — and a `pipeline` whose `returnField` names a query step — prints the CLI's list envelope `{ items, hasMore, nextCursor? }`, the same shape as `databases records query --json`. Every other operation type prints unchanged: `count` → `{ count }`, `aggregate` → `{ result }`, mutation → `{ results }`, `applyToQuery` → `{ matched, affected, failed, … }`, and a `returnField = "all"` pipeline → `{ steps: { … } }` with each step's own keys left alone. `--timing` adds `_timing` alongside whichever shape you get.
378
-
379
387
  **Records (schema introspection):**
380
388
  ```bash
381
389
  primitive databases records models <database-id> [--app <app-id>] # List model names
@@ -395,7 +403,7 @@ primitive databases export [app-id] <database-id> --output <dir> # Export r
395
403
  primitive databases import [app-id] <path> --overwrite --dry-run # Import from export directory
396
404
  ```
397
405
 
398
- Export creates a directory with `metadata.json`, `records.jsonl`, `indexes.json`, and `constraints.json`. Import restores records, indexes, and constraints into a new or existing database; it reads every file first, so a malformed export fails without creating a database. Database type config (operations, triggers, access rules) is managed separately via `primitive config` — run `config push` on the target app before importing.
406
+ Export creates a directory with `metadata.json`, `records.jsonl`, `indexes.json`, and `constraints.json`. Import restores records, indexes, and constraints into a new or existing database; it reads every file first, so a malformed export fails without creating a database. Database type config (triggers, access rules) is managed separately via `primitive config` — run `config push` on the target app before importing.
399
407
 
400
408
  A database the target app doesn't have is created with a new id. `databases import --json` lists each database in `databases[]` with `sourceDatabaseId`, `title`, `action` (`created`, `updated`, `skipped`), `targetDatabaseId` (the id written to; absent for skipped entries and under `--dry-run`), and `reason` for a skip (`exists`, `no metadata.json`). The human output prints `Imported database <source> (<title>) as <target>` when the id changed.
401
409
 
@@ -435,16 +443,16 @@ primitive collections create <name> --description <text> # --owner <userId-or-e
435
443
  primitive collections get <collection-id>
436
444
  primitive collections update <collection-id> --name <name>
437
445
  primitive collections delete <collection-id> # documents are preserved
438
- primitive collections access <collection-id> # groups + members in one view
446
+ primitive collections transfer <collection-id> user:<user-id> # or "app"; the owner role moves with it
439
447
  primitive collections for-document <document-id>
440
448
  ```
441
449
 
442
- **Documents, members and group grants:**
450
+ **Documents and members** (a member is a user id, or `group:<group-id>` for a whole group):
443
451
  ```bash
444
- primitive collections documents list|add|remove <collection-id> [document-id]
445
- primitive collections members list|add|remove <collection-id> [user-id] --permission reader
446
- primitive collections share <collection-id> --group <type>/<id> --permission read-write
447
- primitive collections unshare <collection-id> --group <type>/<id>
452
+ primitive collections documents {list|add|remove} <collection-id> [document-id]
453
+ primitive collections members {list|remove} <collection-id> [principal]
454
+ primitive collections members add <collection-id> <principal> --role contributor # viewer, contributor, editor or manager
455
+ primitive collections members set-role <collection-id> <principal> editor
448
456
  ```
449
457
 
450
458
  **Export / Import:**
@@ -476,7 +484,7 @@ primitive groups delete <group-id> # Delete group
476
484
  **Members:**
477
485
  ```bash
478
486
  primitive groups members list <group-id> # With each member's role
479
- primitive groups members add <group-id> <user-id> [--role manager|member]
487
+ primitive groups members add <group-id> <user-id|email> [--role manager|member] # An email names an existing app user
480
488
  primitive groups members set-role <group-id> <user-id> <role>
481
489
  primitive groups members remove <group-id> <user-id>
482
490
  ```
@@ -508,11 +516,17 @@ primitive analytics cohort-retention [app-id] # Weekly cohort retention
508
516
  primitive analytics top-users [app-id] # Most active users
509
517
  primitive analytics user-search [app-id] --query <q> # Search by email or ULID
510
518
  primitive analytics user-detail <user-ulid> [app-id] # User activity breakdown
519
+ primitive analytics user-detail --anonymous [app-id] # Activity with no signed-in user
511
520
  primitive analytics user-snapshot <user-ulid> [app-id] # Latest context snapshot
512
521
 
513
522
  # Events
514
523
  primitive analytics events [app-id] # Paginated event feed
515
524
  primitive analytics events-grouped [app-id] # Events grouped by dimension
525
+ primitive analytics events --where action=login --where country!=US # Only matching events
526
+ primitive analytics errors-groups --where source!=integration # Leave out a source
527
+
528
+ # Recompute instead of reading the analytics cache (any command)
529
+ primitive analytics overview --fresh
516
530
 
517
531
  # Features
518
532
  primitive analytics integrations [app-id] # Integration usage metrics
@@ -524,8 +538,69 @@ primitive analytics prompts [app-id] # Top prompts by executio
524
538
  - `--limit <n>` - Result limit (top-users, prompts)
525
539
  - `--group-by <dim>` - Dimension for events-grouped (action, feature, route, country, deviceType, plan, day)
526
540
  - `--page <n>` - Page number for events feed (0-based)
541
+ - `--where <field><op><value>` - Filter events, events-grouped and errors-groups; op is `=`, `!=`, `~` (contains) or `^=` (starts with). Repeatable; all must match
542
+ - `--fresh` - Bypass the analytics cache (every command)
543
+ - `--anonymous` - user-detail: anonymous activity in place of a user
527
544
  - `--json` - Output raw JSON
528
545
 
546
+ ### Usage
547
+
548
+ Read an app's usage and estimated cost (beta). Costs are estimates from list
549
+ prices, printed in dollars; `--json` prints millionths of a dollar.
550
+
551
+ ```bash
552
+ primitive usage get [app-id] # This month by meter and by day, bytes held now
553
+ primitive usage get [app-id] --month 2026-09 # A closed month
554
+ primitive usage top-users [app-id] # Top users by api.request
555
+ primitive usage top-users --meter llm.tokens.in # Top users by another meter
556
+ primitive usage top-users --by cost # Top users by estimated cost
557
+ primitive usage user <user-id> [app-id] # One user's usage and the bytes they own
558
+ primitive usage system [app-id] # System usage by origin, source and resource
559
+
560
+ # Super-admin only
561
+ primitive usage top-apps # Top apps by cost, month to date
562
+ primitive usage top-developers # Top developers by cost, month to date
563
+ primitive usage jobs # The daily close, storage baseline and DynamoDB scan
564
+ ```
565
+
566
+ **Common options:**
567
+ - `--since <date>` / `--until <date>` - The window, ISO 8601, UTC (default the last 30 days; at most 90 days back)
568
+ - `--limit <n>` - Result limit
569
+ - `--json` - Output raw JSON
570
+
571
+ ### Hosting
572
+
573
+ Publish the app's static front end at `https://<slug>.primitive.app` (beta).
574
+ Every deploy uploads only the files that changed, activates the deployment,
575
+ and returns once the origin serves it (at most 120 seconds).
576
+
577
+ ```bash
578
+ primitive hosting deploy dist --slug my-app # First deploy: claims the slug
579
+ primitive hosting deploy # Later deploys of dist find the slug by app id
580
+ primitive hosting deploy out --routing static # Clean URLs and 404.html instead of the SPA fallback
581
+ primitive hosting get # Slug, origin, state and active deployment
582
+ primitive hosting deployments # Deployments, newest first, the active one marked
583
+ primitive hosting activate <deploy-id> # Serve an earlier deployment again
584
+ primitive hosting disable # The origin answers 404; slug and deployments are kept
585
+ primitive hosting enable # Serve the last active deployment again
586
+ primitive hosting rename <slug> # Move to a new slug; the old origin redirects for 90 days
587
+
588
+ # Super-admin only
589
+ primitive hosting suspend <app-id> # Answer 451 on every hostname the app owns
590
+ primitive hosting unsuspend <app-id>
591
+ ```
592
+
593
+ `activate`, `disable`, `enable`, `rename`, `suspend` and `unsuspend` ask for
594
+ confirmation; `-y` skips it. Hosting receives a short-lived `write`-only token
595
+ derived from your login, never the login itself, or a CI token as it is.
596
+ In production and on agent, `deploy` uploads the changed files straight to
597
+ `api.cloudflare.com` with an upload session the hosting service opens for the
598
+ app; an `upload_session_expired` error means running the deploy again.
599
+ Before uploading anything, `deploy` refuses a build of more than 99,999 files
600
+ (`too_many_files`), a path over 768 bytes or a manifest over 88 MiB.
601
+ `primitive apps delete` tells hosting the app is gone, so its origin answers
602
+ 410.
603
+
529
604
  ### Admins (Super-Admin Only)
530
605
 
531
606
  Manage the admin directory.
@@ -533,34 +608,41 @@ Manage the admin directory.
533
608
  ```bash
534
609
  primitive admins list # List all admins
535
610
  primitive admins search <email> # Search by email
611
+ primitive admins get <email> # Show an admin and their assigned apps
612
+ primitive admins reindex <admin-id> # Rebuild an admin's index entries
536
613
  primitive admins invite <email> # Create invitation
537
614
  primitive admins update <admin-id> [options] # Update settings
538
615
  primitive admins disable <admin-id> # Disable account
539
616
  primitive admins enable <admin-id> # Enable account
540
- primitive admins invitations list # List invitations
617
+ primitive admins invitations list --email <email> # List an address's pending invitations
541
618
  primitive admins invitations delete <invitation-id>
542
619
  ```
543
620
 
544
- ### Catalog (Super-Admin Only)
621
+ ### Transitions (Super-Admin Only)
545
622
 
546
- Manage the global prompt and integration catalog.
623
+ Read the platform transitions across every app (beta), and who still calls a
624
+ deprecated HTTP operation or sends a deprecated WebSocket message.
547
625
 
548
626
  ```bash
549
- # Prompt catalog
550
- primitive catalog prompts list
551
- primitive catalog prompts create --from-file prompt.toml
552
- primitive catalog prompts get <catalog-id>
553
- primitive catalog prompts update <catalog-id> [options]
554
- primitive catalog prompts delete <catalog-id>
555
-
556
- # Integration catalog
557
- primitive catalog integrations list
558
- primitive catalog integrations create --from-file integration.toml
559
- primitive catalog integrations get <catalog-id>
560
- primitive catalog integrations update <catalog-id> [options]
561
- primitive catalog integrations delete <catalog-id>
627
+ primitive transitions list # Every transition, its defaults and apps per value
628
+ primitive transitions report <transition> # Each app's state, use by call site and eligible date
629
+ primitive transitions report <transition> --in-use # Only apps that used the old path in the window
630
+ primitive transitions deprecated-calls # Calls to deprecated operations, last 14 days
631
+ primitive transitions deprecated-calls --days 90 --app <app-id>
632
+ primitive transitions deprecated-calls --operation "ws:subscribe"
562
633
  ```
563
634
 
635
+ `deprecated-calls` lists one row per app, operation, source (`api`, `fn` or
636
+ `ws`) and client (`js`, `swift`, `cli`, `fn` or `unknown`), most calls first.
637
+ An operation is `<surface>:<METHOD> /<route>` for HTTP, such as
638
+ `app:GET /documents/:documentId`, and `ws:<type>` for a WebSocket message.
639
+ `cli` and `fn` are certain; `js` and `swift` are inferred from the
640
+ `User-Agent`, so a hand-written caller counts as the client it resembles. A
641
+ call on an admin surface for no app is listed as `(platform)`. On a deployed
642
+ server counts are sampled estimates. When the answer is cut at `--limit`
643
+ (default 200, at most 1000) the command says so: narrow it with `--app` or
644
+ `--operation`.
645
+
564
646
  ### Config (TOML Configuration)
565
647
 
566
648
  Author app configuration as TOML files and reconcile them with the server.
@@ -580,6 +662,31 @@ another app: select a different environment with `--env <name>` (#3154).
580
662
  - `--dry-run` - Show changes without applying (push only)
581
663
  - `--force` - Overwrite remote changes (push only)
582
664
 
665
+ A config tree that still holds `workflows/` or `transforms/` is refused by
666
+ `config push` and reported by `config diff`, naming the migration page.
667
+
668
+ **A configuration object's field surface has ONE definition (issue #2644):**
669
+ `src/config-surface/` on the server records, per configuration object, which
670
+ `models.yaml` fields exist, which TOML key each carries, which modes the server
671
+ accepts it in, and — for a field with real behavior — the handler that owns it.
672
+ The server's create/update handlers take their accepted key set from it
673
+ (`pickWritableFields`), and `cli/scripts/gen-config-surfaces.mjs` vendors the
674
+ same modules into the committed artifact
675
+ `cli/src/lib/generated-config-surfaces.ts`, which the CLI's push builder, pull
676
+ serializer and TOML key validation read. The generator runs automatically at CLI
677
+ `prebuild`; regenerate manually with `node cli/scripts/gen-config-surfaces.mjs`
678
+ (or `pnpm -C cli gen:config-surfaces`).
679
+
680
+ Three hard-fail checks live in `cli/tests/unit/config-surface-drift-guard.test.ts`:
681
+ freshness (`--check`, a byte comparison), coverage (every model field of every
682
+ registered object is either exposed or classified `notExposed` **with a
683
+ reason**), and registry existence (every `SYNC_RESOURCE_TYPES` label has a
684
+ definition — the migration's `PENDING_MIGRATION` exemption list is gone, so
685
+ there is nowhere to park one). Add a
686
+ field to `models.yaml` and the CLI unit suite fails until you regenerate and
687
+ classify it — so the CLI can no longer silently drop a new server-side field.
688
+ This supersedes the workflow-only descriptor and generator from #2326.
689
+
583
690
  ## TOML Configuration Format
584
691
 
585
692
  The sync commands use TOML files for configuration. Here's the directory structure:
@@ -876,6 +983,7 @@ types and never loads it at runtime.
876
983
  ## Environment Variables
877
984
 
878
985
  - `PRIMITIVE_SERVER_URL` - Server URL for `login` and `apps delete` outside a project (defaults to `https://primitiveapi.com`); ignored inside a project
986
+ - `PRIMITIVE_HOSTING_URL` - The hosting service `primitive hosting` and `apps delete` use, such as a local `http://hosting-api.localhost:8788`; production and agent are found from the API URL
879
987
 
880
988
  **Login server resolution:**
881
989
  1. Project mode (`primitive/config.json` present): the active environment's
@@ -903,7 +1011,7 @@ It is internal maintainer guidance and is not published.
903
1011
  # Run without building (uses tsx)
904
1012
  pnpm run cli:dev -- login
905
1013
 
906
- # Type check
1014
+ # Type check (builds packages/js-bao first; the CLI reads its dist types)
907
1015
  pnpm run cli:typecheck
908
1016
 
909
1017
  # Build
@@ -2,16 +2,17 @@
2
2
  name: primitive-platform
3
3
  description: >
4
4
  Fetches the Primitive platform's agent guides and applies them. MUST be used whenever the user
5
- is writing or reviewing code that uses js-bao, js-bao-wss-client, primitive-app,
6
- primitive-functions, or any Primitive platform feature (databases, server functions,
5
+ is writing or reviewing code that uses js-bao, js-bao-wss-client, primitive-functions,
6
+ JsBaoClient (Swift), or any Primitive platform feature (databases, server functions,
7
7
  prompts, integrations, blobs, authentication, users/groups), and before running any `primitive`
8
8
  CLI command. All development guidance lives in the guides this skill fetches; after writing or
9
9
  modifying code that touches Primitive APIs, it cross-references the code against those guides
10
10
  and corrects mistakes. Use this skill even if the user doesn't explicitly ask for it. Also use it
11
11
  when something looks like a platform bug or missing platform capability, to record the platform
12
12
  feedback in the app's PRIMITIVE-FEEDBACK.md. Also trigger whenever the user wants to upgrade or
13
- update the app to a newer platform version — bumping js-bao, js-bao-wss-client, primitive-app, or
14
- the primitive CLI — which follows the "Upgrading Platform Libraries" workflow below.
13
+ update the app to a newer platform version — bumping js-bao, js-bao-wss-client, JsBaoClient or
14
+ the primitive CLI, or moving an app off the retired `primitive-app` / `swift-primitive-app`
15
+ libraries — which follows the "Upgrading Platform Libraries" workflow below.
15
16
  allowed-tools: Bash, Read, Edit, Write, Glob, Grep, Agent
16
17
  ---
17
18
 
@@ -95,8 +96,10 @@ primitive guides get <topic> # the topic's default variant
95
96
  After writing or modifying code that touches Primitive, review it without being asked:
96
97
 
97
98
  1. **Identify the features touched.** Imports from `js-bao`, `js-bao-wss-client`,
98
- `primitive-app`, or `primitive-functions`; files in the project's configuration tree; model
99
- definitions and schemas.
99
+ `primitive-functions`, or `JsBaoClient`; files in the project's configuration tree; model
100
+ definitions and schemas. An import from `primitive-app` or `PrimitiveApp` means the app has
101
+ not migrated off a retired library: report it, and point at the `changelog` guide's
102
+ retirement entry (Step 6 of "Upgrading Platform Libraries").
100
103
  2. **Fetch those guides** in the project's language and platform.
101
104
  3. **Compare the code against them.** API usage, lifecycle, access and authorization, anything
102
105
  the guide warns against, and any follow-up step the guide requires that the change skipped.
@@ -106,7 +109,9 @@ After writing or modifying code that touches Primitive, review it without being
106
109
  ## When the user is starting a new feature
107
110
 
108
111
  1. Run `primitive guides list` and pick every relevant topic.
109
- 2. Fetch those guides in the project's language and platform.
112
+ 2. Fetch those guides in the project's language and platform. In an app that still uses
113
+ `primitive-app` or `PrimitiveApp`, build on the client and the app's own code rather than
114
+ the retired library, and suggest the migration (Step 6 of the upgrade workflow).
110
115
  3. Recommend a data model from the guides. If requirements are ambiguous, ask clarifying
111
116
  questions first: a data model is much easier to get right up front than to migrate.
112
117
  4. Outline the implementation, citing the guide patterns it follows.
@@ -120,11 +125,9 @@ After writing or modifying code that touches Primitive, review it without being
120
125
 
121
126
  ## When the user is moving an app's data to another app
122
127
 
123
- Fetch the `documents` guide and follow its export/import sections. A migration is two
124
- exports into one directory and two imports out of it, in a fixed order — the documents
125
- bundle, then the collections those documents sit in — and the guide has the commands, the
126
- order they must run in, and what does not travel. Don't run a single export or import from
127
- memory: the wrong order silently loses every collection's document membership.
128
+ Fetch `primitive guides get databases` and follow its export and import steps. Never run an
129
+ export or import from memory: the guide has the commands, the order they run in, and what
130
+ does not travel.
128
131
 
129
132
  ## Upgrading Platform Libraries
130
133
 
@@ -134,17 +137,37 @@ platform bugs should come out, the starter template the app was scaffolded from
134
137
  moved too, and new platform capabilities should be considered. The refreshed guides are the
135
138
  source of truth for what the platform can do now.
136
139
 
140
+ The first upgrade after the starter templates folded the app libraries in is also a
141
+ migration: an app on `primitive-app` (web) or `swift-primitive-app` (iOS) moves onto the
142
+ template's own code in Step 6. A library is retired when the `changelog` guide's **Breaking**
143
+ entries say so (`primitive guides get changelog --refresh`); npm may also mark the package
144
+ deprecated, but the changelog is the rule. Moving `js-bao-wss-client` or `JsBaoClient` forward
145
+ while keeping a retired library is not a path the platform tests (the frozen Swift library
146
+ can stop building against a newer client, and `primitive-app`'s peer range may refuse it), so
147
+ the choice is to migrate, or to stay on the whole old set for now. Never pin back or suppress
148
+ to keep both.
149
+
137
150
  The backend is upgraded by the platform team, not by the app — the app only chooses which
138
151
  environment it points at (see the `configuration` guide). A library upgrade against the production environment
139
152
  needs no server-side changes.
140
153
 
141
154
  ### 1. Snapshot the current state
142
155
 
143
- - Read `package.json` and note the installed versions of the platform packages the app
144
- uses: `js-bao`, `js-bao-wss-client`, `primitive-app`, and `primitive-admin` (the CLI).
145
- - Check what's available: `pnpm view <pkg> dist-tags` for each. Compare the target tag's
146
- version against what's installed — a dist-tag can lag (or even point behind another
147
- tag), so confirm the upgrade actually moves forward before proceeding.
156
+ Snapshot each client the app has (an app with a web and an iOS client snapshots both):
157
+
158
+ - **Web.** Read `package.json` and note the installed versions of the platform packages:
159
+ `js-bao`, `js-bao-wss-client`, and `primitive-admin` (the CLI, which is also a dev
160
+ dependency: the template's build imports `primitive-admin/vite`). Check what's available:
161
+ `pnpm view <pkg> dist-tags` for each. Compare the target tag's version against what's
162
+ installed — a dist-tag can lag (or even point behind another tag), so confirm the upgrade
163
+ actually moves forward before proceeding.
164
+ - **iOS.** Note the `JsBaoClient` package's `branch:` in `Package.swift` (and in `project.yml`
165
+ when the app has one): `main` is production, `alpha` is alpha. Note the revision it is
166
+ pinned to in `Package.resolved`, and the version in `.primitive-cli-version`.
167
+ - **Retired libraries.** A dependency the `changelog` guide's **Breaking** entries retire
168
+ (`primitive-app` in `package.json`; the `PrimitiveApp` or `PrimitiveAppTesting` products of
169
+ `swift-primitive-app` in `Package.swift` or `project.yml`) is never bumped. Note it for
170
+ Step 6, which removes it. `pnpm view <pkg> deprecated` may confirm a retired npm package.
148
171
  - Locate the app's platform feedback doc (convention below). Note its upgrade stamp and
149
172
  the tracked workarounds — Step 5 revisits each one.
150
173
 
@@ -166,15 +189,34 @@ Upgrading the CLI first matters for two reasons:
166
189
 
167
190
  ### 3. Upgrade the app's libraries
168
191
 
192
+ Web, with pnpm by default (use npm only if the app already uses npm):
193
+
194
+ ```bash
195
+ pnpm add js-bao@latest js-bao-wss-client@latest # the packages the app uses
196
+ pnpm add -D primitive-admin@latest # the CLI the build imports from
197
+ ```
198
+
199
+ iOS:
200
+
169
201
  ```bash
170
- # pnpm by default (use npm only if the app already uses npm), for the packages the app uses:
171
- pnpm add js-bao@latest js-bao-wss-client@latest primitive-app@latest
202
+ swift package update # moves JsBaoClient to the newest commit on its branch
172
203
  ```
173
204
 
205
+ An iOS app built through Xcode also needs its project's packages updated: Xcode resolves
206
+ from its own copy of `Package.resolved`, so run Xcode's package update, or the template's
207
+ `scripts/sync-xcode-pins.sh`, which copies the root pin into the project (the template's
208
+ build scripts run it before every `xcodebuild`). Then set `.primitive-cli-version` to the
209
+ installed CLI's version (`primitive --version`). That file is only the codegen phase's
210
+ fallback: the phase runs `PRIMITIVE_CLI` when it is set, then an installed `primitive`, and
211
+ only when neither exists `npx` with the version the file pins.
212
+
213
+ A retired library stays where it is until Step 6 removes it.
214
+
174
215
  Upgrade the libraries **before** fetching guides: the guides system selects its version
175
216
  channel from the *installed* `js-bao-wss-client` major, so fetching first returns guides
176
- for the old version. Then refetch the guides for every feature area the app uses,
177
- passing `--refresh` on the first call.
217
+ for the old version.
218
+ Then refetch the guides for every feature area the app uses, passing `--refresh` on the
219
+ first call (and `--language swift` for an iOS app).
178
220
 
179
221
  ### 4. Fix breaking changes, then scan for deprecated API use
180
222
 
@@ -183,6 +225,11 @@ feature area and migrate the code to the current API — don't pin back or suppr
183
225
  major version bump means breaking changes are expected; treat the migration as part of
184
226
  the upgrade, not an optional follow-up.
185
227
 
228
+ Some errors mean a retired library, not an API change: `Cannot find module 'primitive-app'`
229
+ or a typecheck error on its exports (web), `no such module 'PrimitiveApp'`, or a frozen
230
+ `PrimitiveApp` that no longer builds against the updated `JsBaoClient` (iOS). Those are
231
+ the migration. Do Step 6 first, then come back here.
232
+
186
233
  Once it builds, find every platform API the app still uses that the platform has
187
234
  deprecated. A deprecated surface works today and is removed in a later major, so this
188
235
  is the moment to warn the user, not the moment it breaks. Each surface marks its
@@ -232,6 +279,20 @@ so default to removing them the moment they're unnecessary.
232
279
 
233
280
  ### 6. Adopt template updates
234
281
 
282
+ When Step 1 found a retired library, this step is the upgrade. The `changelog` guide's
283
+ **Breaking** entry for the retirement lists the migration for each platform; follow it
284
+ rather than diffing file by file. In outline: the app moves to the template's client setup
285
+ (`src/lib/client.ts`), auth store and sign-in pages on the web, or to the template's
286
+ `AppState` and `AuthModel` with their views on iOS; `primitive-app/vite` becomes
287
+ `primitive-admin/vite`; the dev tools go; the in-app test groups move to plain vitest or
288
+ XCTest with the template's sign-in helper; and the dependency is dropped. The entry holds
289
+ the details. Then run the baseline diff below for everything else.
290
+
291
+ The migration replaces the library's starter pieces only. Where the app itself uses
292
+ something the template no longer has — user prefs, theming, group-aware routing, its root
293
+ document, its own data model — that use stays: the app changed it, so ask (the third case
294
+ below).
295
+
235
296
  The app was scaffolded by `primitive init` from a starter template —
236
297
  `Primitive-Labs/primitive-vue-template` for web apps, `Primitive-Labs/primitive-swift-template`
237
298
  for iOS. Those templates keep moving with the platform: config, setup, and wiring fixes
@@ -279,7 +340,9 @@ guides for the app's feature areas. Compare against what the app actually does:
279
340
 
280
341
  Run the app's tests, apply the post-change review above to everything modified, and
281
342
  update the feedback doc's upgrade stamp (date, channel, versions, and the template
282
- commit synced in Step 6). If the upgrade changed the configuration tree and the
343
+ commit synced in Step 6). Versions are the web packages' versions, or for iOS the
344
+ `JsBaoClient` branch and the revision `Package.resolved` now pins; an app with both
345
+ clients lists both. If the upgrade changed the configuration tree and the
283
346
  environment is shared, verify against the child app from Step 4, not the shared
284
347
  environment; the `configuration` guide's "Child apps" workflow covers applying the
285
348
  merged tree to the parent and deleting the child.
@@ -299,7 +362,8 @@ have one, create it the first time there is something to record:
299
362
  ## Upgrade stamp
300
363
  - Last upgraded: 2026-07-21
301
364
  - Channel: production
302
- - Versions: js-bao-wss-client 2.0.6, primitive-app 3.0.5, js-bao 0.5.1, primitive-admin 1.0.55
365
+ - Versions: js-bao-wss-client 3.5.0, js-bao 0.12.0, primitive-admin 1.1.0
366
+ - Versions (iOS): JsBaoClient main @ a1d82eb
303
367
  - Template: primitive-vue-template @ main 0f1c2d3
304
368
 
305
369
  ## Open items