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
@@ -1,25 +1,53 @@
1
+ import { Option } from "commander";
2
+ import { commandStatus } from "../lib/command-status.js";
1
3
  import { ApiClient } from "../lib/api-client.js";
2
4
  import { resolveAppId } from "../lib/config.js";
3
- import { error, flushOutput, formatDate, formatTable, info, json, result as printResult, success } from "../lib/output.js";
5
+ import { error, flushOutput, formatDate, formatTable, info, json, result as printResult, success, warn } from "../lib/output.js";
4
6
  import { confirmPrompt } from "../lib/confirm-prompt.js";
5
7
  import { normalizeCliListEnvelope, wholeListEnvelope } from "../lib/paginate.js";
6
8
  import { parseDataOption } from "../lib/data-input.js";
7
- import { DB3_ROUTES } from "../lib/records-verbs.js";
9
+ import { parseFilterOptions } from "../lib/record-filter.js";
10
+ import { DB3_BATCH_OPERATION_CAP, DB3_ROUTES } from "../lib/records-verbs.js";
8
11
  import { DB3_LOAD_ROUTES } from "../lib/load-routes.js";
9
12
  import { declarationOfSchemaAnswer, declaredModelNames, exportDb3, loadDb3Rows, pendingRegistrations, planDb3Import, readDb3Manifest, readExportedBlobs, resolvedTypeName, } from "../lib/db3-export.js";
10
13
  import fs from "fs";
11
14
  import path from "path";
12
- import { db3IndexRefusalLines, db3IndexTableRows } from "../lib/db3-index-output.js";
15
+ import { DB3_INDEX_KINDS, DB3_INDEX_PLACEMENTS, VECTOR_DISTANCES, VECTOR_INDEX_MODES, VECTOR_QUANTIZERS, db3IndexKindOnTheWire, db3IndexRefusalLines, db3IndexRefusalSentence, db3IndexTableRows, listsVectorIndex, db3TextOptionsOf, vectorIndexOptions, } from "../lib/db3-index-output.js";
13
16
  import { parseCustodianOrExit } from "../lib/custodian.js";
14
17
  import { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, printPageHint } from "../lib/list-options.js";
15
- import { BULK_DATA_FILE_HELP, aggregateRecordsAction, bulkRecordsAction, countRecordsAction, deleteRecordAction, describeAction, describeRecordsFailure, displayTags, inspectAction, modelsAction, patchRecordAction, queryRecordsAction, saveRecordAction, schemaAction, statsAction, ingestAction, listIngestsAction, getIngestAction, abortIngestAction, listSnapshotsAction, getSnapshotAction, buildSnapshotAction, } from "./documents.js";
18
+ import { aggregateReadOf, aggregateRecordsAction, batchReadRecordsAction, batchRecordsAction, countRecordsAction, deleteRecordAction, describeAction, describeRecordsFailure, displayTags, inspectAction, modelsAction, patchRecordAction, queryReadOf, queryRecordsAction, saveRecordAction, schemaAction, statsAction, ingestAction, listIngestsAction, getIngestAction, abortIngestAction, listSnapshotsAction, getSnapshotAction, buildSnapshotAction, } from "./documents.js";
19
+ /**
20
+ * The `--data-file` help of `db3 records batch`: the db3 operation shapes,
21
+ * reads among them (#5243), the cap, and the command for a larger load.
22
+ */
23
+ export const DB3_BATCH_DATA_FILE_HELP = "JSON file with { operations: [...] } or a bare operations array, " +
24
+ `at most ${DB3_BATCH_OPERATION_CAP} operations per call (atomic): all apply or none do, in order. ` +
25
+ "Each write is one of { model, action: create, data, id? } (the database assigns " +
26
+ "the id when none is given), { model, action: patch, id, data }, " +
27
+ "{ model, action: increment, id, fields } (each field's delta), " +
28
+ "{ model, action: delete, id } or { model, action: upsert, constraint, data, id? } " +
29
+ "(merged into the record holding that unique constraint's key, or created). " +
30
+ "Any write takes a condition, a query filter the record must match or the batch is refused. " +
31
+ "A read { model, action: query, filter?, sort?, limit?, cursor?, include? }, " +
32
+ "{ model, action: count, filter? } or { model, action: aggregate, options } is answered " +
33
+ "against the writes before it. For larger loads use `primitive db3 ingest`";
34
+ /** The `--data-file` help of `db3 records batch-read` (#5243): the read shapes and the cap. */
35
+ export const DB3_BATCH_READ_DATA_FILE_HELP = "JSON file with { operations: [...] } or a bare array of reads, " +
36
+ `at most ${DB3_BATCH_OPERATION_CAP} per call, all answered from one state of the db3. ` +
37
+ "Each read is { model, action: query, filter?, sort?, limit?, cursor?, include? }, " +
38
+ "{ model, action: count, filter? } or { model, action: aggregate, options }";
16
39
  /**
17
40
  * A refused index call: the server's sentence, its code and status, then one
18
41
  * line per detail the code names (the duplicate keys, the origins keeping
19
- * the index, the index a name belongs to, the stored format).
42
+ * the index, the index a name belongs to, the stored format). The sentence
43
+ * is printed in the CLI's words (#5890): a set-element index, and `spelling`
44
+ * for the set-element flag the user typed.
20
45
  */
21
- function refuse(err) {
22
- error(describeRecordsFailure(err));
46
+ function refuse(err, spelling = "--set-elements") {
47
+ const reworded = typeof err?.message === "string"
48
+ ? { message: db3IndexRefusalSentence(err.message, err.code, spelling), code: err.code, statusCode: err.statusCode, status: err.status }
49
+ : err;
50
+ error(describeRecordsFailure(reworded));
23
51
  for (const line of db3IndexRefusalLines(err))
24
52
  console.error(` ${line}`);
25
53
  process.exit(1);
@@ -29,6 +57,83 @@ function fail(err) {
29
57
  error(describeRecordsFailure(err));
30
58
  process.exit(1);
31
59
  }
60
+ /** `--explain` on a records read verb (#5240). */
61
+ const EXPLAIN_FLAG = "Explain the read on the server instead of answering it: the indexes it used, what it scanned and the rows it read";
62
+ /** `--index` on a records read verb (#5240). */
63
+ const INDEX_FLAG = "Explain the read forced onto this index of the model, or 'none' to read with no index (implies --explain)";
64
+ /** Whether a records read verb was asked to explain: `--explain`, or `--index`, which implies it. */
65
+ const explaining = (options) => options.explain === true || options.index !== undefined;
66
+ /**
67
+ * A records read explained (#5240): sends `read` through `client`, with
68
+ * `--index` as its force, to `POST db3/:id/records/:model/explain` and prints the answer,
69
+ * or `--json` it. A refusal prints the server's sentence, code and status,
70
+ * and a force's reason.
71
+ */
72
+ async function explainReadAction(client, appId, db3Id, modelName, options, read) {
73
+ try {
74
+ const answer = await client.explainDb3Read(appId, db3Id, modelName, {
75
+ ...read,
76
+ ...(options.index !== undefined ? { index: options.index } : {}),
77
+ });
78
+ if (options.json) {
79
+ json(answer);
80
+ return;
81
+ }
82
+ printExplain(answer);
83
+ }
84
+ catch (err) {
85
+ refuse(err);
86
+ }
87
+ }
88
+ /** An explain's answer: the read and its force, what it used, scanned, read and answered, then each statement's plan. */
89
+ function printExplain(answer) {
90
+ const forced = answer.index === null ? "no" : answer.index === "none" ? "none (no index)" : answer.index;
91
+ printResult("Read", `${answer.op} ${answer.model}`);
92
+ printResult("Forced", forced);
93
+ printResult("Indexes", answer.indexes.length > 0 ? answer.indexes.join(", ") : "none");
94
+ printResult("Scanned", answer.scanned.length > 0 ? answer.scanned.join(", ") : "none");
95
+ printResult("Rows read", answer.cost?.rowsRead ?? "not reported");
96
+ printResult("Answered", answer.answered);
97
+ for (const statement of answer.statements) {
98
+ console.log("");
99
+ console.log(statement.runs > 1 ? `${statement.model} (${statement.runs} runs)` : statement.model);
100
+ if (statement.plan === null)
101
+ console.log(` (no plan: ${statement.planError ?? "refused"})`);
102
+ else
103
+ for (const line of statement.plan)
104
+ console.log(` ${line}`);
105
+ }
106
+ }
107
+ /** Print `message` and exit 1, before any request. */
108
+ function refuseList(message) {
109
+ error(message);
110
+ process.exit(1);
111
+ }
112
+ /** The ways `db3 list --user-id` reads, in listing order. */
113
+ const DB3_VIAS = ["held", "shared", "app"];
114
+ /**
115
+ * The columns of `db3 list --user-id`, in order: each a field of the client's
116
+ * `Db3Row` or `Db3ListEntry` (`src/client/api/db3Api.ts`).
117
+ */
118
+ export const USER_DB3_TABLE_FIELDS = ["id", "title", "via", "permission", "custodian", "sync", "type", "grantedAt"];
119
+ const USER_DB3_TABLE_HEADERS = {
120
+ id: "ID",
121
+ title: "TITLE",
122
+ via: "VIA",
123
+ permission: "PERMISSION",
124
+ custodian: "CUSTODIAN",
125
+ sync: "SYNC",
126
+ type: "TYPE",
127
+ grantedAt: "GRANTED",
128
+ };
129
+ /** `--via` as a list of ways, or exit 1 before any request when it names anything else. */
130
+ function parseVia(value) {
131
+ const ways = value.split(",");
132
+ if (!value || ways.some((way) => !DB3_VIAS.includes(way))) {
133
+ refuseList("--via lists some of held, shared and app, comma-separated.");
134
+ }
135
+ return ways;
136
+ }
32
137
  /** `on` or `off` as a boolean, or exit 1 naming `label` before any request. */
33
138
  function parseOnOff(value, label) {
34
139
  if (value === "on")
@@ -60,6 +165,7 @@ export function registerDb3Commands(program) {
60
165
  const db3 = program
61
166
  .command("db3")
62
167
  .description("Work with db3s: create, read, list and delete them, their sync, app access and custody, indexes, records, schema and room");
168
+ commandStatus(db3, { stability: "beta" });
63
169
  // ---- Indexes ----
64
170
  const indexes = db3.command("indexes").description("List, register and drop a db3's indexes");
65
171
  indexes
@@ -87,6 +193,10 @@ export function registerDb3Commands(program) {
87
193
  { header: "FIELDS", key: "fields" },
88
194
  { header: "UNIQUE", key: "unique" },
89
195
  { header: "ORIGINS", key: "origins" },
196
+ { header: "KIND", key: "kind" },
197
+ { header: "ON", key: "on" },
198
+ // #5229 — a vector index's shared model; a list with no vector index prints as before.
199
+ ...(listsVectorIndex(list) ? [{ header: "ANN MODEL", key: "annModel" }] : []),
90
200
  ]));
91
201
  }
92
202
  catch (err) {
@@ -101,31 +211,90 @@ export function registerDb3Commands(program) {
101
211
  .requiredOption("--field <field>", "Field to index (repeat it for a composite unique index, which also needs --unique and --name)", (value, previous = []) => previous.concat(value))
102
212
  .option("--unique", "Enforce that no two records share the key")
103
213
  .option("--name <name>", "Name the index (idx_named_<model>_<name>)")
104
- .option("--members", "Index a string-set field's members (idx_members_<model>_<field>) for $contains, any-of and facets; one --field, no --unique or --name")
214
+ .option("--set-elements", "Index a string-set field's elements (idx_members_<model>_<field>) for $contains, any-of and facets; one --field, no --unique or --name (the same as --kind set-elements)")
215
+ // #5890 — the old spelling of --set-elements, kept outside the documented surface.
216
+ .addOption(new Option("--members", "Deprecated: use --set-elements").hideHelp())
217
+ .option("--kind <kind>", `What the index is: ${DB3_INDEX_KINDS.join(", ")} (default scalar, set-elements with --set-elements)`)
218
+ .option("--on <placement>", `Where the index lives: ${DB3_INDEX_PLACEMENTS.join(", ")} (default both, server for a set-element index, device for a vector index); change it by dropping and registering again`)
219
+ .option("--distance <distance>", `A vector index's distance: ${VECTOR_DISTANCES.join(", ")} (with --kind vector)`)
220
+ .option("--index <mode>", `A vector index's search: ${VECTOR_INDEX_MODES.join(", ")} (with --kind vector; default exact)`)
221
+ .option("--nbucket <n>", "An ann vector index's bucket count (with --index ann)")
222
+ .option("--codesize <n>", "An ann vector index's bytes per quantized vector (with --index ann)")
223
+ .option("--quantizer <quantizer>", `An ann vector index's quantizer: ${VECTOR_QUANTIZERS.join(", ")} (with --index ann)`)
224
+ .option("--tokenizer <tokenizer>", "A text index's tokenizer: unicode61 (the default, diacritics folded) or porter (English stems)")
225
+ .option("--prefix <lengths>", "A text index's prefix lengths to index, comma-separated (e.g. 2,3)")
226
+ .option("--weight <field=weight>", "A text index's weight for one of its fields (repeatable; 1 by default)", (value, previous = []) => previous.concat(value))
105
227
  .option("--app <app-id>", "App ID")
106
228
  .option("--json", "Output as JSON")
107
229
  .action(async (db3Id, options) => {
108
230
  const resolvedAppId = resolveAppId(undefined, options);
109
231
  const fields = options.field;
110
- if (options.members) {
111
- const conflict = fields.length > 1
112
- ? "--members takes one --field: a member index covers one string-set field"
113
- : options.unique
114
- ? "--members takes no --unique: a member index enforces nothing"
115
- : options.name !== undefined
116
- ? "--members takes no --name: a member index is named idx_members_<model>_<field>"
117
- : null;
118
- if (conflict) {
119
- error(conflict);
120
- process.exit(1);
121
- }
232
+ const kind = options.kind;
233
+ const vector = vectorIndexOptions(options, kind);
234
+ if ("problem" in vector) {
235
+ error(vector.problem);
236
+ process.exit(1);
237
+ }
238
+ if (options.members && options.setElements) {
239
+ error("--members is the old spelling of --set-elements: give --set-elements alone");
240
+ process.exit(1);
241
+ }
242
+ // #5890 — the old spellings still register the same index, saying so once each.
243
+ if (options.members)
244
+ warn("--members is deprecated: use --set-elements");
245
+ if (kind === "members")
246
+ warn("--kind members is deprecated: use --kind set-elements");
247
+ const setFlag = options.setElements === true || options.members === true;
248
+ const setFlagSpelling = options.members ? "--members" : "--set-elements";
249
+ const members = setFlag || kind === "members" || kind === "set-elements";
250
+ // The set-element spelling the user typed: the flag, else the kind.
251
+ const flag = setFlag
252
+ ? setFlagSpelling
253
+ : kind === "members"
254
+ ? "--kind members"
255
+ : kind === "set-elements"
256
+ ? "--kind set-elements"
257
+ : "--set-elements";
258
+ const textOptions = options.tokenizer !== undefined || options.prefix !== undefined || options.weight !== undefined;
259
+ const text = kind === "text" ? db3TextOptionsOf(options) : null;
260
+ const conflict = kind !== undefined && kind !== "members" && !DB3_INDEX_KINDS.includes(kind)
261
+ ? `--kind must be one of ${DB3_INDEX_KINDS.join(", ")}`
262
+ : options.on !== undefined && !DB3_INDEX_PLACEMENTS.includes(options.on)
263
+ ? `--on must be one of ${DB3_INDEX_PLACEMENTS.join(", ")}`
264
+ : setFlag && kind !== undefined && kind !== "members" && kind !== "set-elements"
265
+ ? `${setFlagSpelling} is --kind set-elements: give --kind ${kind} without ${setFlagSpelling}, or --kind set-elements`
266
+ : textOptions && kind !== "text"
267
+ ? `--tokenizer, --prefix and --weight apply to --kind text`
268
+ : text && "refusal" in text
269
+ ? text.refusal
270
+ : kind === "text" && options.unique
271
+ ? `--kind text takes no --unique: a text index enforces nothing`
272
+ : kind === "text" && options.name !== undefined
273
+ ? `--kind text takes no --name: a model's text index is named idx_text_<model>`
274
+ : !members
275
+ ? null
276
+ : fields.length > 1
277
+ ? `${flag} takes one --field: a set-element index covers one string-set field`
278
+ : options.unique
279
+ ? `${flag} takes no --unique: a set-element index enforces nothing`
280
+ : options.name !== undefined
281
+ ? `${flag} takes no --name: a set-element index is named idx_members_<model>_<field>`
282
+ : null;
283
+ if (conflict) {
284
+ error(conflict);
285
+ process.exit(1);
122
286
  }
287
+ const textBody = text && "text" in text && Object.keys(text.text).length > 0 ? { text: text.text } : {};
123
288
  const body = {
124
289
  model: options.model,
125
290
  ...(fields.length === 1 ? { field: fields[0] } : { fields }),
126
291
  ...(options.unique ? { unique: true } : {}),
127
292
  ...(options.name !== undefined ? { name: options.name } : {}),
128
- ...(options.members ? { members: true } : {}),
293
+ ...(setFlag ? { members: true } : {}),
294
+ ...(kind !== undefined ? { kind: db3IndexKindOnTheWire(kind) } : {}),
295
+ ...(options.on !== undefined ? { on: options.on } : {}),
296
+ ...(vector.options ? { vector: vector.options } : {}),
297
+ ...textBody,
129
298
  };
130
299
  const client = new ApiClient();
131
300
  try {
@@ -134,10 +303,10 @@ export function registerDb3Commands(program) {
134
303
  json(index);
135
304
  return;
136
305
  }
137
- success(`Registered ${index.name} on ${index.model} (${index.fields.join(", ")}${index.unique ? ", unique" : ""}${index.members ? ", members" : ""}).`);
306
+ success(`Registered ${index.name} on ${index.model} (${index.fields.join(", ")}${index.unique ? ", unique" : ""}${index.members ? ", set-element index" : ""}${index.kind === "text" ? ", text" : ""}).`);
138
307
  }
139
308
  catch (err) {
140
- refuse(err);
309
+ refuse(err, flag);
141
310
  }
142
311
  });
143
312
  indexes
@@ -177,6 +346,80 @@ export function registerDb3Commands(program) {
177
346
  refuse(err);
178
347
  }
179
348
  });
349
+ // ---- A vector index's shared ANN model (#5229) ----
350
+ const model = indexes.command("model").description("Fetch or delete an ann vector index's shared model");
351
+ model
352
+ .command("get")
353
+ .description("Write an ann vector index's shared model to a file, as a device uploaded it")
354
+ .argument("<db3-id>", "db3 ID")
355
+ .argument("<name>", "Vector index name, as `db3 indexes list` prints it")
356
+ .option("--out <file>", "Where to write the model (default <name>-<generation>-<revision>.pvm1)")
357
+ .option("--app <app-id>", "App ID")
358
+ .option("--json", "Output as JSON")
359
+ .action(async (db3Id, name, options) => {
360
+ const resolvedAppId = resolveAppId(undefined, options);
361
+ const client = new ApiClient();
362
+ try {
363
+ const fetched = await client.fetchDb3IndexModel(resolvedAppId, db3Id, name);
364
+ const out = path.resolve(options.out ?? `${name}-${fetched.generation}-${fetched.revision}.pvm1`);
365
+ fs.writeFileSync(out, fetched.data);
366
+ const summary = {
367
+ name,
368
+ file: out,
369
+ bytes: fetched.data.byteLength,
370
+ generation: fetched.generation,
371
+ revision: fetched.revision,
372
+ rows: fetched.rows,
373
+ trainedAt: fetched.trainedAt,
374
+ format: fetched.format,
375
+ };
376
+ if (options.json) {
377
+ json(summary);
378
+ return;
379
+ }
380
+ success(`Wrote ${name}'s model (revision ${fetched.revision}, ${fetched.rows} rows, trained ${fetched.trainedAt}) to ${out}: ${fetched.data.byteLength} bytes.`);
381
+ }
382
+ catch (err) {
383
+ refuse(err);
384
+ }
385
+ });
386
+ model
387
+ .command("delete")
388
+ .description("Delete an ann vector index's shared model so a device trains it again (the db3's owner)")
389
+ .argument("<db3-id>", "db3 ID")
390
+ .argument("<name>", "Vector index name, as `db3 indexes list` prints it")
391
+ .option("--app <app-id>", "App ID")
392
+ .option("-y, --yes", "Skip confirmation prompt")
393
+ .option("--json", "Output as JSON")
394
+ .action(async (db3Id, name, options) => {
395
+ const resolvedAppId = resolveAppId(undefined, options);
396
+ if (!options.yes) {
397
+ let confirmed;
398
+ try {
399
+ confirmed = await confirmPrompt(`Delete ${name}'s shared model on db3 ${db3Id}? Every device answers exactly until one trains it again.`);
400
+ }
401
+ catch (err) {
402
+ error(err.message);
403
+ process.exit(1);
404
+ }
405
+ if (!confirmed) {
406
+ info("Cancelled.");
407
+ return;
408
+ }
409
+ }
410
+ const client = new ApiClient();
411
+ try {
412
+ const answer = await client.deleteDb3IndexModel(resolvedAppId, db3Id, name);
413
+ if (options.json) {
414
+ json(answer);
415
+ return;
416
+ }
417
+ success(`Deleted ${answer.name}'s model; its revision is now ${answer.revision}.`);
418
+ }
419
+ catch (err) {
420
+ refuse(err);
421
+ }
422
+ });
180
423
  // ---- Records: the `documents records` verbs' twins ----
181
424
  const records = db3.command("records").description("Query and write a db3's records");
182
425
  records
@@ -191,9 +434,26 @@ export function registerDb3Commands(program) {
191
434
  .option("--limit <n>", "Records per page (default 100, max 10000)")
192
435
  .option("--cursor <cursor>", "Pagination cursor from a previous query (valid only with the same --sort)")
193
436
  .option("--include <json>", "Related records as a JSON array of include specs, e.g. '[{\"model\":\"customer\",\"type\":\"refersTo\",\"sourceField\":\"customerId\"}]'; answered as _related")
437
+ .option("--explain", EXPLAIN_FLAG)
438
+ .option("--index <name>", INDEX_FLAG)
194
439
  .option("--json", "Output as JSON")
195
440
  .action(async (db3Id, modelName, options) => {
196
441
  const resolvedAppId = resolveAppId(undefined, options);
442
+ if (explaining(options)) {
443
+ const { filter, sort, include } = queryReadOf(options);
444
+ const limit = options.limit === undefined ? undefined : /^\d+$/.test(options.limit) ? Number(options.limit) : options.limit;
445
+ await explainReadAction(new ApiClient(), resolvedAppId, db3Id, modelName, options, {
446
+ op: "query",
447
+ ...(filter ? { filter } : {}),
448
+ options: {
449
+ ...(sort !== undefined ? { sort } : {}),
450
+ ...(limit !== undefined ? { limit } : {}),
451
+ ...(options.cursor !== undefined ? { cursor: options.cursor } : {}),
452
+ ...(include !== undefined ? { include } : {}),
453
+ },
454
+ });
455
+ return;
456
+ }
197
457
  await queryRecordsAction(DB3_ROUTES, resolvedAppId, db3Id, modelName, options);
198
458
  });
199
459
  records
@@ -204,9 +464,16 @@ export function registerDb3Commands(program) {
204
464
  .option("--app <app-id>", "App ID")
205
465
  .option("--filter <json>", "Filter as JSON (e.g. '{\"status\":\"open\"}')")
206
466
  .option("--filter-file <path>", "Read filter from a JSON or TOML file")
467
+ .option("--explain", EXPLAIN_FLAG)
468
+ .option("--index <name>", INDEX_FLAG)
207
469
  .option("--json", "Output as JSON")
208
470
  .action(async (db3Id, modelName, options) => {
209
471
  const resolvedAppId = resolveAppId(undefined, options);
472
+ if (explaining(options)) {
473
+ const filter = parseFilterOptions(options);
474
+ await explainReadAction(new ApiClient(), resolvedAppId, db3Id, modelName, options, { op: "count", ...(filter ? { filter } : {}) });
475
+ return;
476
+ }
210
477
  await countRecordsAction(DB3_ROUTES, resolvedAppId, db3Id, modelName, options);
211
478
  });
212
479
  records
@@ -220,9 +487,19 @@ export function registerDb3Commands(program) {
220
487
  .option("--group-by <field>", "Group results by this field (repeatable)", (value, previous = []) => previous.concat(value), [])
221
488
  .option("--filter <json>", "Filter as JSON")
222
489
  .option("--filter-file <path>", "Read filter from a JSON or TOML file")
490
+ .option("--explain", EXPLAIN_FLAG)
491
+ .option("--index <name>", INDEX_FLAG)
223
492
  .option("--json", "Output as JSON")
224
493
  .action(async (db3Id, modelName, options) => {
225
494
  const resolvedAppId = resolveAppId(undefined, options);
495
+ if (explaining(options)) {
496
+ const { operations, groupBy, filter } = aggregateReadOf(options);
497
+ await explainReadAction(new ApiClient(), resolvedAppId, db3Id, modelName, options, {
498
+ op: "aggregate",
499
+ aggregate: { operations, groupBy, ...(filter ? { filter } : {}) },
500
+ });
501
+ return;
502
+ }
226
503
  await aggregateRecordsAction(DB3_ROUTES, resolvedAppId, db3Id, modelName, options);
227
504
  });
228
505
  records
@@ -270,15 +547,29 @@ export function registerDb3Commands(program) {
270
547
  await deleteRecordAction(DB3_ROUTES, resolvedAppId, db3Id, modelName, recordId, options);
271
548
  });
272
549
  records
273
- .command("bulk")
274
- .description("Apply an atomic create/patch/delete/upsert operations blob to a db3")
550
+ .command("batch")
551
+ .description(`Apply create/patch/increment/delete/upsert operations to a db3, with reads among them, at most ${DB3_BATCH_OPERATION_CAP} ` +
552
+ "operations per call (atomic); use `primitive db3 ingest` for larger loads")
275
553
  .argument("<db3-id>", "db3 ID")
276
- .requiredOption("--data-file <file>", BULK_DATA_FILE_HELP)
554
+ .requiredOption("--data-file <file>", DB3_BATCH_DATA_FILE_HELP)
277
555
  .option("--app <app-id>", "App ID")
278
556
  .option("-y, --yes", "Skip confirmation prompt")
279
557
  .option("--json", "Output as JSON")
280
558
  .action(async (db3Id, options) => {
281
- await bulkRecordsAction(DB3_ROUTES, db3Id, options);
559
+ await batchRecordsAction(DB3_ROUTES, db3Id, options);
560
+ });
561
+ records
562
+ .command("batch-read")
563
+ .description(`Run several queries, counts and aggregates on a db3 in one request, at most ${DB3_BATCH_OPERATION_CAP} ` +
564
+ "per call, answered from one state of the db3")
565
+ .argument("<db3-id>", "db3 ID")
566
+ .requiredOption("--data-file <file>", DB3_BATCH_READ_DATA_FILE_HELP)
567
+ .option("--partial", "Answer a refused read in its place instead of refusing the request")
568
+ .option("--app <app-id>", "App ID")
569
+ .option("--json", "Output as JSON")
570
+ .action(async (db3Id, options) => {
571
+ const client = new ApiClient();
572
+ await batchReadRecordsAction(client, db3Id, options);
282
573
  });
283
574
  records
284
575
  .command("models")
@@ -629,16 +920,92 @@ Custody:
629
920
  fail(err);
630
921
  }
631
922
  });
923
+ db3
924
+ .command("update")
925
+ .description("Rename a db3")
926
+ .argument("<db3-id>", "db3 ID")
927
+ .requiredOption("--title <title>", "The db3's new title (at most 255 characters; stored trimmed)")
928
+ .option("--app <app-id>", "App ID")
929
+ .option("--json", "Output as JSON")
930
+ .action(async (db3Id, options) => {
931
+ const resolvedAppId = resolveAppId(undefined, options);
932
+ try {
933
+ const updated = await new ApiClient().updateDb3(resolvedAppId, db3Id, { title: options.title });
934
+ if (options.json) {
935
+ json(updated);
936
+ return;
937
+ }
938
+ success("db3 updated.");
939
+ printDb3(updated);
940
+ }
941
+ catch (err) {
942
+ fail(err);
943
+ }
944
+ });
632
945
  db3
633
946
  .command("list")
634
- .description("List one custodian's db3s, oldest first")
635
- .requiredOption("--custodian <custodian>", '"app" or "user:<user-id>"')
947
+ .description("List one custodian's db3s, oldest first, or every db3 a user reaches: held, shared with them, then app access")
948
+ .option("--custodian <custodian>", '"app" or "user:<user-id>"')
949
+ .option("--user-id <user-id>", "List every db3 this user reaches, one row per way, sync-off db3s included")
950
+ .option("--via <ways>", "With --user-id: some of held, shared and app, comma-separated")
636
951
  .option("--app <app-id>", "App ID")
637
952
  .addOption(pageLimitOption())
638
953
  .addOption(pageCursorOption())
639
954
  .option("--json", "Output as JSON")
640
955
  .allowExcessArguments(false)
641
956
  .action(async (options) => {
957
+ if ((options.custodian === undefined) === (options.userId === undefined)) {
958
+ refuseList("db3 list takes exactly one of --custodian and --user-id.");
959
+ }
960
+ if (options.userId === undefined) {
961
+ if (options.via !== undefined)
962
+ refuseList("--via is valid only with --user-id.");
963
+ return listByCustodian(options);
964
+ }
965
+ const userId = options.userId;
966
+ if (!userId.trim() || userId.startsWith("user:"))
967
+ refuseList("--user-id needs a bare user id.");
968
+ const via = options.via === undefined ? undefined : parseVia(options.via);
969
+ const limit = parsePageLimit(options.limit);
970
+ const resolvedAppId = resolveAppId(undefined, options);
971
+ try {
972
+ const page = normalizeCliListEnvelope(await new ApiClient().listDb3ForUser(resolvedAppId, userId, {
973
+ ...(via ? { via } : {}),
974
+ ...(limit !== undefined ? { limit } : {}),
975
+ ...(options.cursor ? { cursor: options.cursor } : {}),
976
+ }));
977
+ if (options.json) {
978
+ json(page);
979
+ return;
980
+ }
981
+ if (page.items.length === 0) {
982
+ printEmptyPage(page, "db3s");
983
+ return;
984
+ }
985
+ const rows = page.items.map((row) => ({
986
+ id: row.id,
987
+ title: row.title ?? "",
988
+ via: row.via,
989
+ permission: row.permission ?? "none",
990
+ custodian: row.custodian ?? "none",
991
+ sync: row.sync === false ? "off" : "on",
992
+ type: row.type ?? "none",
993
+ grantedAt: row.grantedAt,
994
+ }));
995
+ console.log(formatTable(rows, USER_DB3_TABLE_FIELDS.map((key) => ({
996
+ header: USER_DB3_TABLE_HEADERS[key],
997
+ key,
998
+ ...(key === "title" ? { flex: true } : {}),
999
+ ...(key === "grantedAt" ? { format: (value) => (value ? formatDate(value) : "—") } : {}),
1000
+ }))));
1001
+ printPageHint(page);
1002
+ }
1003
+ catch (err) {
1004
+ fail(err);
1005
+ }
1006
+ });
1007
+ /** `db3 list --custodian`: one custodian's db3s from the admin API (#4800). */
1008
+ async function listByCustodian(options) {
642
1009
  const limit = parsePageLimit(options.limit);
643
1010
  const custodian = parseCustodianOrExit(options.custodian, "--custodian");
644
1011
  const resolvedAppId = resolveAppId(undefined, options);
@@ -676,7 +1043,7 @@ Custody:
676
1043
  catch (err) {
677
1044
  fail(err);
678
1045
  }
679
- });
1046
+ }
680
1047
  db3
681
1048
  .command("delete")
682
1049
  .description("Delete a db3 and all its data (records, blobs, aliases, permissions)")
@@ -1004,7 +1371,17 @@ async function importAction(dir, options) {
1004
1371
  register = pending.register;
1005
1372
  }
1006
1373
  for (const registration of register) {
1007
- await client.registerDb3Index(resolvedAppId, db3Id, registration);
1374
+ try {
1375
+ await client.registerDb3Index(resolvedAppId, db3Id, registration);
1376
+ }
1377
+ catch (err) {
1378
+ // A refused registration prints in the CLI's words (#5890), as `indexes register` prints it.
1379
+ if (!err?.statusCode || typeof err?.message !== "string")
1380
+ throw err;
1381
+ const reworded = { message: db3IndexRefusalSentence(err.message, err.code, "--set-elements"), code: err.code, statusCode: err.statusCode, status: err.status };
1382
+ error(describeRecordsFailure(reworded));
1383
+ return 1;
1384
+ }
1008
1385
  }
1009
1386
  const outcome = await loadDb3Rows(client, resolvedAppId, db3Id, root, (line) => info(line));
1010
1387
  const session = outcome?.session ?? null;