@gadicc/loom 0.0.0-oidc-bootstrap.0

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 (342) hide show
  1. package/LICENSE +201 -0
  2. package/NOTICE +6 -0
  3. package/README.md +448 -0
  4. package/THIRD_PARTY_NOTICES.md +25 -0
  5. package/db/drizzle-config.d.ts +20 -0
  6. package/db/drizzle-config.js +34 -0
  7. package/db/fixtures.d.ts +31 -0
  8. package/db/fixtures.js +52 -0
  9. package/db/neon.d.ts +3 -0
  10. package/db/neon.js +20 -0
  11. package/db/neonFull.d.ts +12 -0
  12. package/db/neonFull.js +33 -0
  13. package/db/package.json +3 -0
  14. package/db/testing.d.ts +26 -0
  15. package/db/testing.js +76 -0
  16. package/db/testing.test.ts +28 -0
  17. package/db/valibot.d.ts +23 -0
  18. package/db/valibot.js +8 -0
  19. package/esm/_dnt.polyfills.d.ts +149 -0
  20. package/esm/_dnt.polyfills.d.ts.map +1 -0
  21. package/esm/_dnt.polyfills.js +163 -0
  22. package/esm/_dnt.shims.d.ts +2 -0
  23. package/esm/_dnt.shims.d.ts.map +1 -0
  24. package/esm/_dnt.shims.js +57 -0
  25. package/esm/bin/loom.d.ts +2 -0
  26. package/esm/bin/loom.d.ts.map +1 -0
  27. package/esm/bin/loom.js +11 -0
  28. package/esm/mod.d.ts +9 -0
  29. package/esm/mod.d.ts.map +1 -0
  30. package/esm/mod.js +8 -0
  31. package/esm/package.json +3 -0
  32. package/esm/src/apiKeys/authorize.d.ts +4 -0
  33. package/esm/src/apiKeys/authorize.d.ts.map +1 -0
  34. package/esm/src/apiKeys/authorize.js +184 -0
  35. package/esm/src/apiKeys/country.d.ts +3 -0
  36. package/esm/src/apiKeys/country.d.ts.map +1 -0
  37. package/esm/src/apiKeys/country.js +7 -0
  38. package/esm/src/apiKeys/credentials.d.ts +4 -0
  39. package/esm/src/apiKeys/credentials.d.ts.map +1 -0
  40. package/esm/src/apiKeys/credentials.js +55 -0
  41. package/esm/src/apiKeys/fingerprint.d.ts +3 -0
  42. package/esm/src/apiKeys/fingerprint.d.ts.map +1 -0
  43. package/esm/src/apiKeys/fingerprint.js +5 -0
  44. package/esm/src/apiKeys/mod.d.ts +9 -0
  45. package/esm/src/apiKeys/mod.d.ts.map +1 -0
  46. package/esm/src/apiKeys/mod.js +8 -0
  47. package/esm/src/apiKeys/policy.d.ts +59 -0
  48. package/esm/src/apiKeys/policy.d.ts.map +1 -0
  49. package/esm/src/apiKeys/policy.js +88 -0
  50. package/esm/src/apiKeys/retention.d.ts +55 -0
  51. package/esm/src/apiKeys/retention.d.ts.map +1 -0
  52. package/esm/src/apiKeys/retention.js +65 -0
  53. package/esm/src/apiKeys/types.d.ts +175 -0
  54. package/esm/src/apiKeys/types.d.ts.map +1 -0
  55. package/esm/src/apiKeys/types.js +1 -0
  56. package/esm/src/cli/externalSkills.d.ts +39 -0
  57. package/esm/src/cli/externalSkills.d.ts.map +1 -0
  58. package/esm/src/cli/externalSkills.js +177 -0
  59. package/esm/src/cli/mod.d.ts +337 -0
  60. package/esm/src/cli/mod.d.ts.map +1 -0
  61. package/esm/src/cli/mod.js +9268 -0
  62. package/esm/src/cli/projectSkills.d.ts +102 -0
  63. package/esm/src/cli/projectSkills.d.ts.map +1 -0
  64. package/esm/src/cli/projectSkills.js +592 -0
  65. package/esm/src/files/client.d.ts +29 -0
  66. package/esm/src/files/client.d.ts.map +1 -0
  67. package/esm/src/files/client.js +41 -0
  68. package/esm/src/files/errors.d.ts +37 -0
  69. package/esm/src/files/errors.d.ts.map +1 -0
  70. package/esm/src/files/errors.js +66 -0
  71. package/esm/src/files/hash.d.ts +15 -0
  72. package/esm/src/files/hash.d.ts.map +1 -0
  73. package/esm/src/files/hash.js +82 -0
  74. package/esm/src/files/memory.d.ts +29 -0
  75. package/esm/src/files/memory.d.ts.map +1 -0
  76. package/esm/src/files/memory.js +109 -0
  77. package/esm/src/files/metadata.d.ts +10 -0
  78. package/esm/src/files/metadata.d.ts.map +1 -0
  79. package/esm/src/files/metadata.js +186 -0
  80. package/esm/src/files/mod.d.ts +10 -0
  81. package/esm/src/files/mod.d.ts.map +1 -0
  82. package/esm/src/files/mod.js +9 -0
  83. package/esm/src/files/s3.d.ts +29 -0
  84. package/esm/src/files/s3.d.ts.map +1 -0
  85. package/esm/src/files/s3.js +107 -0
  86. package/esm/src/files/service.d.ts +27 -0
  87. package/esm/src/files/service.d.ts.map +1 -0
  88. package/esm/src/files/service.js +136 -0
  89. package/esm/src/files/types.d.ts +134 -0
  90. package/esm/src/files/types.d.ts.map +1 -0
  91. package/esm/src/files/types.js +1 -0
  92. package/esm/src/jobs/catalog.d.ts +32 -0
  93. package/esm/src/jobs/catalog.d.ts.map +1 -0
  94. package/esm/src/jobs/catalog.js +208 -0
  95. package/esm/src/jobs/controller.d.ts +28 -0
  96. package/esm/src/jobs/controller.d.ts.map +1 -0
  97. package/esm/src/jobs/controller.js +95 -0
  98. package/esm/src/jobs/direct.d.ts +36 -0
  99. package/esm/src/jobs/direct.d.ts.map +1 -0
  100. package/esm/src/jobs/direct.js +122 -0
  101. package/esm/src/jobs/events.d.ts +15 -0
  102. package/esm/src/jobs/events.d.ts.map +1 -0
  103. package/esm/src/jobs/events.js +30 -0
  104. package/esm/src/jobs/format.d.ts +16 -0
  105. package/esm/src/jobs/format.d.ts.map +1 -0
  106. package/esm/src/jobs/format.js +183 -0
  107. package/esm/src/jobs/http.d.ts +22 -0
  108. package/esm/src/jobs/http.d.ts.map +1 -0
  109. package/esm/src/jobs/http.js +44 -0
  110. package/esm/src/jobs/log.d.ts +2 -0
  111. package/esm/src/jobs/log.d.ts.map +1 -0
  112. package/esm/src/jobs/log.js +10 -0
  113. package/esm/src/jobs/mod.d.ts +10 -0
  114. package/esm/src/jobs/mod.d.ts.map +1 -0
  115. package/esm/src/jobs/mod.js +9 -0
  116. package/esm/src/jobs/run.d.ts +20 -0
  117. package/esm/src/jobs/run.d.ts.map +1 -0
  118. package/esm/src/jobs/run.js +57 -0
  119. package/esm/src/jobs/types.d.ts +31 -0
  120. package/esm/src/jobs/types.d.ts.map +1 -0
  121. package/esm/src/jobs/types.js +1 -0
  122. package/esm/src/mui/apiKeys.d.ts +65 -0
  123. package/esm/src/mui/apiKeys.d.ts.map +1 -0
  124. package/esm/src/mui/apiKeys.js +301 -0
  125. package/esm/src/mui/apiKeysView.d.ts +48 -0
  126. package/esm/src/mui/apiKeysView.d.ts.map +1 -0
  127. package/esm/src/mui/apiKeysView.js +34 -0
  128. package/esm/src/mui/confirm.d.ts +12 -0
  129. package/esm/src/mui/confirm.d.ts.map +1 -0
  130. package/esm/src/mui/confirm.js +78 -0
  131. package/esm/src/mui/mod.d.ts +4 -0
  132. package/esm/src/mui/mod.d.ts.map +1 -0
  133. package/esm/src/mui/mod.js +2 -0
  134. package/esm/src/next/apiKeys/mod.d.ts +64 -0
  135. package/esm/src/next/apiKeys/mod.d.ts.map +1 -0
  136. package/esm/src/next/apiKeys/mod.js +217 -0
  137. package/esm/src/next/auth/config.d.ts +34 -0
  138. package/esm/src/next/auth/config.d.ts.map +1 -0
  139. package/esm/src/next/auth/config.js +103 -0
  140. package/esm/src/next/auth/mod.d.ts +3 -0
  141. package/esm/src/next/auth/mod.d.ts.map +1 -0
  142. package/esm/src/next/auth/mod.js +2 -0
  143. package/esm/src/next/auth/server.d.ts +28 -0
  144. package/esm/src/next/auth/server.d.ts.map +1 -0
  145. package/esm/src/next/auth/server.js +24 -0
  146. package/esm/src/next/files/mod.d.ts +3 -0
  147. package/esm/src/next/files/mod.d.ts.map +1 -0
  148. package/esm/src/next/files/mod.js +2 -0
  149. package/esm/src/next/files/route.d.ts +99 -0
  150. package/esm/src/next/files/route.d.ts.map +1 -0
  151. package/esm/src/next/files/route.js +349 -0
  152. package/esm/src/next/jobs/list.d.ts +25 -0
  153. package/esm/src/next/jobs/list.d.ts.map +1 -0
  154. package/esm/src/next/jobs/list.js +39 -0
  155. package/esm/src/next/jobs/mod.d.ts +6 -0
  156. package/esm/src/next/jobs/mod.d.ts.map +1 -0
  157. package/esm/src/next/jobs/mod.js +5 -0
  158. package/esm/src/next/jobs/paths.d.ts +14 -0
  159. package/esm/src/next/jobs/paths.d.ts.map +1 -0
  160. package/esm/src/next/jobs/paths.js +40 -0
  161. package/esm/src/next/jobs/route.d.ts +48 -0
  162. package/esm/src/next/jobs/route.d.ts.map +1 -0
  163. package/esm/src/next/jobs/route.js +101 -0
  164. package/esm/src/next/jobs/run.d.ts +51 -0
  165. package/esm/src/next/jobs/run.d.ts.map +1 -0
  166. package/esm/src/next/jobs/run.js +563 -0
  167. package/esm/src/next/jobs/stream.d.ts +3 -0
  168. package/esm/src/next/jobs/stream.d.ts.map +1 -0
  169. package/esm/src/next/jobs/stream.js +25 -0
  170. package/esm/src/next/pwa/mod.d.ts +104 -0
  171. package/esm/src/next/pwa/mod.d.ts.map +1 -0
  172. package/esm/src/next/pwa/mod.js +169 -0
  173. package/esm/src/next/pwa/worker.d.ts +27 -0
  174. package/esm/src/next/pwa/worker.d.ts.map +1 -0
  175. package/esm/src/next/pwa/worker.js +27 -0
  176. package/package.json +293 -0
  177. package/script/_dnt.polyfills.d.ts +149 -0
  178. package/script/_dnt.polyfills.d.ts.map +1 -0
  179. package/script/_dnt.polyfills.js +166 -0
  180. package/script/_dnt.shims.d.ts +2 -0
  181. package/script/_dnt.shims.d.ts.map +1 -0
  182. package/script/_dnt.shims.js +60 -0
  183. package/script/bin/loom.d.ts +2 -0
  184. package/script/bin/loom.d.ts.map +1 -0
  185. package/script/bin/loom.js +17 -0
  186. package/script/mod.d.ts +9 -0
  187. package/script/mod.d.ts.map +1 -0
  188. package/script/mod.js +24 -0
  189. package/script/package.json +3 -0
  190. package/script/src/apiKeys/authorize.d.ts +4 -0
  191. package/script/src/apiKeys/authorize.d.ts.map +1 -0
  192. package/script/src/apiKeys/authorize.js +187 -0
  193. package/script/src/apiKeys/country.d.ts +3 -0
  194. package/script/src/apiKeys/country.d.ts.map +1 -0
  195. package/script/src/apiKeys/country.js +10 -0
  196. package/script/src/apiKeys/credentials.d.ts +4 -0
  197. package/script/src/apiKeys/credentials.d.ts.map +1 -0
  198. package/script/src/apiKeys/credentials.js +58 -0
  199. package/script/src/apiKeys/fingerprint.d.ts +3 -0
  200. package/script/src/apiKeys/fingerprint.d.ts.map +1 -0
  201. package/script/src/apiKeys/fingerprint.js +8 -0
  202. package/script/src/apiKeys/mod.d.ts +9 -0
  203. package/script/src/apiKeys/mod.d.ts.map +1 -0
  204. package/script/src/apiKeys/mod.js +24 -0
  205. package/script/src/apiKeys/policy.d.ts +59 -0
  206. package/script/src/apiKeys/policy.d.ts.map +1 -0
  207. package/script/src/apiKeys/policy.js +92 -0
  208. package/script/src/apiKeys/retention.d.ts +55 -0
  209. package/script/src/apiKeys/retention.d.ts.map +1 -0
  210. package/script/src/apiKeys/retention.js +70 -0
  211. package/script/src/apiKeys/types.d.ts +175 -0
  212. package/script/src/apiKeys/types.d.ts.map +1 -0
  213. package/script/src/apiKeys/types.js +2 -0
  214. package/script/src/cli/externalSkills.d.ts +39 -0
  215. package/script/src/cli/externalSkills.d.ts.map +1 -0
  216. package/script/src/cli/externalSkills.js +181 -0
  217. package/script/src/cli/mod.d.ts +337 -0
  218. package/script/src/cli/mod.d.ts.map +1 -0
  219. package/script/src/cli/mod.js +9337 -0
  220. package/script/src/cli/projectSkills.d.ts +102 -0
  221. package/script/src/cli/projectSkills.d.ts.map +1 -0
  222. package/script/src/cli/projectSkills.js +606 -0
  223. package/script/src/files/client.d.ts +29 -0
  224. package/script/src/files/client.d.ts.map +1 -0
  225. package/script/src/files/client.js +45 -0
  226. package/script/src/files/errors.d.ts +37 -0
  227. package/script/src/files/errors.d.ts.map +1 -0
  228. package/script/src/files/errors.js +76 -0
  229. package/script/src/files/hash.d.ts +15 -0
  230. package/script/src/files/hash.d.ts.map +1 -0
  231. package/script/src/files/hash.js +89 -0
  232. package/script/src/files/memory.d.ts +29 -0
  233. package/script/src/files/memory.d.ts.map +1 -0
  234. package/script/src/files/memory.js +113 -0
  235. package/script/src/files/metadata.d.ts +10 -0
  236. package/script/src/files/metadata.d.ts.map +1 -0
  237. package/script/src/files/metadata.js +189 -0
  238. package/script/src/files/mod.d.ts +10 -0
  239. package/script/src/files/mod.d.ts.map +1 -0
  240. package/script/src/files/mod.js +25 -0
  241. package/script/src/files/s3.d.ts +29 -0
  242. package/script/src/files/s3.d.ts.map +1 -0
  243. package/script/src/files/s3.js +110 -0
  244. package/script/src/files/service.d.ts +27 -0
  245. package/script/src/files/service.d.ts.map +1 -0
  246. package/script/src/files/service.js +139 -0
  247. package/script/src/files/types.d.ts +134 -0
  248. package/script/src/files/types.d.ts.map +1 -0
  249. package/script/src/files/types.js +2 -0
  250. package/script/src/jobs/catalog.d.ts +32 -0
  251. package/script/src/jobs/catalog.d.ts.map +1 -0
  252. package/script/src/jobs/catalog.js +223 -0
  253. package/script/src/jobs/controller.d.ts +28 -0
  254. package/script/src/jobs/controller.d.ts.map +1 -0
  255. package/script/src/jobs/controller.js +100 -0
  256. package/script/src/jobs/direct.d.ts +36 -0
  257. package/script/src/jobs/direct.d.ts.map +1 -0
  258. package/script/src/jobs/direct.js +128 -0
  259. package/script/src/jobs/events.d.ts +15 -0
  260. package/script/src/jobs/events.d.ts.map +1 -0
  261. package/script/src/jobs/events.js +37 -0
  262. package/script/src/jobs/format.d.ts +16 -0
  263. package/script/src/jobs/format.d.ts.map +1 -0
  264. package/script/src/jobs/format.js +193 -0
  265. package/script/src/jobs/http.d.ts +22 -0
  266. package/script/src/jobs/http.d.ts.map +1 -0
  267. package/script/src/jobs/http.js +50 -0
  268. package/script/src/jobs/log.d.ts +2 -0
  269. package/script/src/jobs/log.d.ts.map +1 -0
  270. package/script/src/jobs/log.js +13 -0
  271. package/script/src/jobs/mod.d.ts +10 -0
  272. package/script/src/jobs/mod.d.ts.map +1 -0
  273. package/script/src/jobs/mod.js +25 -0
  274. package/script/src/jobs/run.d.ts +20 -0
  275. package/script/src/jobs/run.d.ts.map +1 -0
  276. package/script/src/jobs/run.js +61 -0
  277. package/script/src/jobs/types.d.ts +31 -0
  278. package/script/src/jobs/types.d.ts.map +1 -0
  279. package/script/src/jobs/types.js +2 -0
  280. package/script/src/mui/apiKeys.d.ts +65 -0
  281. package/script/src/mui/apiKeys.d.ts.map +1 -0
  282. package/script/src/mui/apiKeys.js +327 -0
  283. package/script/src/mui/apiKeysView.d.ts +48 -0
  284. package/script/src/mui/apiKeysView.d.ts.map +1 -0
  285. package/script/src/mui/apiKeysView.js +40 -0
  286. package/script/src/mui/confirm.d.ts +12 -0
  287. package/script/src/mui/confirm.d.ts.map +1 -0
  288. package/script/src/mui/confirm.js +85 -0
  289. package/script/src/mui/mod.d.ts +4 -0
  290. package/script/src/mui/mod.d.ts.map +1 -0
  291. package/script/src/mui/mod.js +19 -0
  292. package/script/src/next/apiKeys/mod.d.ts +64 -0
  293. package/script/src/next/apiKeys/mod.d.ts.map +1 -0
  294. package/script/src/next/apiKeys/mod.js +224 -0
  295. package/script/src/next/auth/config.d.ts +34 -0
  296. package/script/src/next/auth/config.d.ts.map +1 -0
  297. package/script/src/next/auth/config.js +142 -0
  298. package/script/src/next/auth/mod.d.ts +3 -0
  299. package/script/src/next/auth/mod.d.ts.map +1 -0
  300. package/script/src/next/auth/mod.js +18 -0
  301. package/script/src/next/auth/server.d.ts +28 -0
  302. package/script/src/next/auth/server.d.ts.map +1 -0
  303. package/script/src/next/auth/server.js +27 -0
  304. package/script/src/next/files/mod.d.ts +3 -0
  305. package/script/src/next/files/mod.d.ts.map +1 -0
  306. package/script/src/next/files/mod.js +18 -0
  307. package/script/src/next/files/route.d.ts +99 -0
  308. package/script/src/next/files/route.d.ts.map +1 -0
  309. package/script/src/next/files/route.js +353 -0
  310. package/script/src/next/jobs/list.d.ts +25 -0
  311. package/script/src/next/jobs/list.d.ts.map +1 -0
  312. package/script/src/next/jobs/list.js +48 -0
  313. package/script/src/next/jobs/mod.d.ts +6 -0
  314. package/script/src/next/jobs/mod.d.ts.map +1 -0
  315. package/script/src/next/jobs/mod.js +21 -0
  316. package/script/src/next/jobs/paths.d.ts +14 -0
  317. package/script/src/next/jobs/paths.d.ts.map +1 -0
  318. package/script/src/next/jobs/paths.js +47 -0
  319. package/script/src/next/jobs/route.d.ts +48 -0
  320. package/script/src/next/jobs/route.d.ts.map +1 -0
  321. package/script/src/next/jobs/route.js +105 -0
  322. package/script/src/next/jobs/run.d.ts +51 -0
  323. package/script/src/next/jobs/run.d.ts.map +1 -0
  324. package/script/src/next/jobs/run.js +570 -0
  325. package/script/src/next/jobs/stream.d.ts +3 -0
  326. package/script/src/next/jobs/stream.d.ts.map +1 -0
  327. package/script/src/next/jobs/stream.js +28 -0
  328. package/script/src/next/pwa/mod.d.ts +104 -0
  329. package/script/src/next/pwa/mod.d.ts.map +1 -0
  330. package/script/src/next/pwa/mod.js +192 -0
  331. package/script/src/next/pwa/worker.d.ts +27 -0
  332. package/script/src/next/pwa/worker.d.ts.map +1 -0
  333. package/script/src/next/pwa/worker.js +33 -0
  334. package/skills/loom/SKILL.md +200 -0
  335. package/skills/loom-api-keys/SKILL.md +123 -0
  336. package/skills/loom-auth/SKILL.md +70 -0
  337. package/skills/loom-db/SKILL.md +94 -0
  338. package/skills/loom-db/references/db-stack.md +39 -0
  339. package/skills/loom-files/SKILL.md +97 -0
  340. package/skills/loom-jobs/SKILL.md +148 -0
  341. package/skills/upgrade-deps/SKILL.md +165 -0
  342. package/skills/upgrade-deps/agents/openai.yaml +4 -0
@@ -0,0 +1,123 @@
1
+ ---
2
+ name: loom-api-keys
3
+ description: Use when adopting Loom API keys, the managed audit schema, API-key route authorization, Vercel IP/country snapshots, key management UI, audit retention, or explicit jobs integration.
4
+ ---
5
+
6
+ # Loom API keys
7
+
8
+ Read `loom.json`, then inspect `features.api-keys.config`. Better Auth remains
9
+ the authority for key creation, hashing, enablement, expiry, and native
10
+ permissions. The app owns its Better Auth plugin configuration, verifier,
11
+ current-role policy, audit repository, lifecycle actions, and migrations.
12
+
13
+ ## Foundation and integrations
14
+
15
+ - `loom add api-keys` requires active `auth` and `db`, materializes the
16
+ hash-tracked audit schema, and scaffolds safe stubs. It never creates SQL.
17
+ - Replace the deny-all policy, verifier, audit repository, and lifecycle action
18
+ stubs before production.
19
+ - Install compatible matching `better-auth` and `@better-auth/api-key` versions.
20
+ Keep API-key sessions disabled and adapt `verifyApiKey()` exactly once.
21
+ - Foundation installation does not authorize any existing HTTP surface.
22
+ - Enable jobs separately with
23
+ `loom api-keys integrate jobs --resource jobs --action execute`. The command
24
+ refuses an unguarded jobs HTTP route and never replaces browser/session auth.
25
+ - Direct local job runners import the catalog and execute in the trusted local
26
+ process. They remain API-key-free. A future remote HTTP client is a different
27
+ trust boundary and must authenticate.
28
+
29
+ ## Adoption checklist
30
+
31
+ - Activate `auth`, `db`, then `api-keys`; review the managed schema and generate
32
+ the consumer migration deliberately. Existing installs sync to audit blueprint
33
+ v3 before migration generation.
34
+ - Replace all generated safe stubs. Implement the verifier exactly once, fresh
35
+ role/owner policy, audit append/list and retention repositories, and
36
+ owner/admin lifecycle actions.
37
+ - On directly hosted Vercel routes, add
38
+ `requestContext: vercelApiKeyRequestContext`. Supply deterministic context in
39
+ local tests because Vercel geolocation headers are deployment-only.
40
+ - Derive recent use from the newest allowed authorization event, not Better
41
+ Auth's generic `lastRequest`. Map its IP/country into the MUI recent-use row
42
+ and map each audit event's IP/country into its audit row.
43
+ - Exercise denial, audit-outage, handler-failure, query-credential, and stream
44
+ behavior before enabling a route. Run `loom check` and app checks afterward.
45
+
46
+ ## Adding consumer scopes
47
+
48
+ - Keep the shared Loom layer scope-agnostic. Define consumer permissions with
49
+ `defineApiKeyScopes` using stable resource/action names, and treat names
50
+ already issued to keys as a compatibility contract. Use its `list` projection
51
+ for UI and its `permissions` projection for route descriptors.
52
+ - Build the consumer's server policy with `createApiKeyPolicy`. Every registered
53
+ scope must have an explicit `"allow"`, `"deny"`, or callback rule; unknown
54
+ resource/action pairs deny automatically. Enforce creation-time eligibility
55
+ separately, and use callbacks to re-check mutable privileges such as current
56
+ roles at use time.
57
+ - Give each protected operation a stable audit operation name and the exact
58
+ required permission in its route descriptor. Foundation installation or a
59
+ registry entry alone must never expose an HTTP capability.
60
+ - Carry the verified principal into the handler and constrain user-owned data in
61
+ its database query. Do not fetch broadly and filter afterward; define global
62
+ data semantics explicitly and fail closed when ownership is ambiguous.
63
+ - Keep Bearer and `X-API-Key` as the default transports. Enable query transport
64
+ only for routes whose consumer explicitly accepts URL-credential leakage, and
65
+ keep audit metadata allowlisted and free of credential-bearing values.
66
+ - Do not silently expand existing keys when a scope is introduced. Require a
67
+ replacement key for increased authority.
68
+ - A new native resource/action value normally uses the existing Better Auth
69
+ permission field and Loom text audit columns, so it does not by itself require
70
+ a migration. Generate one only when the consumer's persistence shape changes.
71
+ - Test registry conversion and forged IDs, creation and fresh use-time policy,
72
+ wrong-scope and revoked keys, configured transports and ambiguity rejection,
73
+ database ownership, and audit failure before handler execution.
74
+ - Add a shared integration hook and manifest contract only when the capability
75
+ is reusable across consumers. App-specific routes should use the generic
76
+ authorization wrapper and remain in the consumer.
77
+
78
+ ## Security boundaries
79
+
80
+ - Bearer and `X-API-Key` are enabled by default. Query credentials require an
81
+ explicit consumer opt-in and can leak through browser history, access logs,
82
+ copied links, and referrers.
83
+ - Reject multiple transports even when values match.
84
+ - Never log or persist plaintext keys, authorization headers, full URLs, query
85
+ strings, or arbitrary handler parameters.
86
+ - An allowed authorization audit event must be durable before execution. Denied
87
+ requests remain denied if denial auditing is unavailable.
88
+ - Completion events describe response creation for streaming responses; Loom
89
+ does not buffer streams to observe full consumption.
90
+ - On Vercel, prefer `vercelApiKeyRequestContext` to snapshot the platform-owned
91
+ IP and country headers with no lookup dependency. The headers are absent
92
+ locally and require special handling when another proxy fronts Vercel.
93
+ - Elsewhere, resolve an optional country code from the app's trusted originating
94
+ IP with `resolveCountryCode`. Prefer an offline, build-refreshed database such
95
+ as `ip-location-api/pack` with `user-country`; never make a request-time
96
+ geolocation service call. Resolver failures must not affect auth.
97
+ - Persist the ISO country code with the authorization event and render that
98
+ snapshot. Do not re-resolve historical audit rows after database updates.
99
+ - Revoke by disabling keys so audit attribution and snapshots remain intact.
100
+
101
+ ## Audit retention
102
+
103
+ - The general default is 180 days, 5,000 authorization request groups per key,
104
+ and batches of 1,000 request groups. Do not count physical rows: delete an
105
+ authorization event and its completion event atomically.
106
+ - Run `loom api-keys retention enable` to record an explicit policy. It does not
107
+ modify jobs or create a schedule.
108
+ - Implement `apiKeyAuditRetentionRepository.pruneBatch` against the
109
+ `ApiKeyAuditRetentionRepository` contract and schedule
110
+ `runApiKeyAuditRetention` daily in app-owned infrastructure.
111
+ - Prefer a trusted in-process scheduler invocation. If cleanup is exposed over
112
+ HTTP, require explicit scheduler authentication; never create a public
113
+ maintenance route.
114
+ - Apply the age cutoff to unattributed denials. Apply the per-key cap only where
115
+ a key is attributed, retaining the newest request groups.
116
+ - Monitor `complete`; retry or alert when the runner reaches its batch safety
117
+ bound. Record aggregate cleanup metrics outside the audit table.
118
+ - Override retention for documented legal, regulatory, contractual, incident, or
119
+ legal-hold needs. PCI-scoped consumers commonly need at least 365 days.
120
+
121
+ Run `loom check` during development and `loom check --production` before
122
+ release. After a schema materialization or sync, review the diff and generate
123
+ the app-local migration deliberately.
@@ -0,0 +1,70 @@
1
+ ---
2
+ name: loom-auth
3
+ description: Use when a Loom consumer changes Better Auth wiring, BETTER_AUTH_SECRET or BETTER_AUTH_SECRETS, auth cookie/session settings, or environment-specific auth configuration.
4
+ ---
5
+
6
+ # Loom Auth
7
+
8
+ Use this skill for the shared Better Auth boundary in a consuming app.
9
+
10
+ ## Start here
11
+
12
+ 1. Read `loom.json` and use the configured auth module and route paths.
13
+ 2. Check the installed `better-auth` version before recommending versioned
14
+ secret rotation. `BETTER_AUTH_SECRETS` requires Better Auth 1.5 or newer.
15
+ 3. Keep database adapters, providers, plugins, redirect behavior, and app-local
16
+ session enrichment in the consumer.
17
+
18
+ ## Secret loading
19
+
20
+ - Keep `requireBetterAuthSecret()` in the module-level `betterAuth()` config.
21
+ Failing during module initialization catches missing production config during
22
+ a build instead of allowing an insecure runtime default.
23
+ - When `BETTER_AUTH_SECRETS` exists, Better Auth reads the complete versioned
24
+ list directly. The helper validates that list and returns `BETTER_AUTH_SECRET`
25
+ as Better Auth's legacy fallback when it exists; do not parse the first
26
+ version into a replacement singular environment variable.
27
+ - Do not use a dummy build secret for a production artifact. Vercel's
28
+ `vercel pull` build path can provide Sensitive variables to an external CI
29
+ runner, and server-only variables are read again in the deployed runtime.
30
+ - Treat `.vercel/.env.<target>.local` as a plaintext secret file. Keep it
31
+ ignored, mask pulled values in GitHub Actions before later commands can log
32
+ them, and do not cache or upload it as an artifact.
33
+ - `vercel env run` does not provide Sensitive variables. CI commands that need
34
+ the production secret set should run from the file created by `vercel pull`.
35
+
36
+ ## Rotation
37
+
38
+ - Prefer Better Auth's versioned rotation with
39
+ `BETTER_AUTH_SECRETS=2:new,1:old`; the first entry signs new data and older
40
+ entries remain available for decryption.
41
+ - Preserve `BETTER_AUTH_SECRET` during the first versioned rollout when legacy
42
+ data predates the versioned envelope. Better Auth uses the singular value as
43
+ that legacy fallback.
44
+ - Sensitive Vercel variables are intentionally unreadable after creation. Store
45
+ recovery and previous rotation values in the team's password manager before
46
+ converting or replacing them.
47
+ - Do not delete an old key until the app's longest relevant session, cookie,
48
+ verification, and token lifetime has elapsed and active OAuth flows have had
49
+ time to finish.
50
+
51
+ ## Production and Preview
52
+
53
+ Use different auth signing keys when Preview is a different trust boundary.
54
+ Sharing a key is more than a logging-isolation concern: preview code that gains
55
+ the key can sign or decrypt data accepted by Production when cookie names,
56
+ domains, or backing data overlap. Separate host-only cookies and isolated
57
+ Preview databases reduce the practical risk, so this is guidance rather than a
58
+ blanket release blocker for trusted long-lived previews.
59
+
60
+ If the app uses Better Auth's OAuth Proxy plugin, check that plugin's secret
61
+ requirements before separating keys; the proxy may need an explicitly shared
62
+ secret for cross-environment state exchange.
63
+
64
+ ## Verification
65
+
66
+ - Run `loom check` and the consumer's typecheck/tests.
67
+ - Run a production Vercel build after changing secret selection or auth module
68
+ initialization.
69
+ - Confirm server-only secret values do not occur in `.next/static`, generated
70
+ client chunks, cached artifacts, or committed files.
@@ -0,0 +1,94 @@
1
+ ---
2
+ name: loom-db
3
+ description: Use when the task mentions the loom db feature, neon.ts, neonFull.ts, drizzle.config.ts, loom db schema-gen, valibot-generated schemas, PGlite DB tests, or repairing loom-managed DB wrappers and scripts in a consuming app.
4
+ ---
5
+
6
+ # Loom DB
7
+
8
+ Use this skill when working on the shared DB stack from a consuming app.
9
+
10
+ ## Start here
11
+
12
+ 1. Read `loom.json`.
13
+ 2. Inspect `features.db.config` and use the configured module and directory
14
+ paths instead of assuming defaults.
15
+ 3. Check the app-local schema barrel before changing any Loom-managed DB files.
16
+
17
+ ## Ownership boundaries
18
+
19
+ - App-local Drizzle schemas remain the source of truth.
20
+ - Loom schema blueprints may be materialized into committed app-local schema
21
+ files for schema-bearing features such as `files`; migrations remain app-local
22
+ and explicit.
23
+ - Loom owns the standard wiring around thin wrappers for `neon.ts`,
24
+ `neonFull.ts`, `drizzle.config.ts`, `schema:gen`, `db:fixtures`, and the
25
+ shared PGlite test harness.
26
+ - Valibot generated files stay app-local, but should be regenerated through
27
+ `loom db schema-gen` instead of ad hoc commands.
28
+ - DB-backed scripts, Drizzle commands, direct SQL inspection, and migrations
29
+ should use the app's env-aware package scripts or
30
+ `pnpm exec loom env -- <command>`. Do not add `dotenv` or `@next/env` imports
31
+ to implementation files.
32
+ - `createDrizzleConfig()` prefers `DATABASE_URL_UNPOOLED` when Vercel/Neon
33
+ provides it and falls back to `DATABASE_URL`, so local environments do not
34
+ need to define both.
35
+ - App-specific fixture table selection, extra Valibot refinements, and auth
36
+ integration should stay local unless they are being extracted deliberately.
37
+
38
+ ## What to preserve
39
+
40
+ - Existing local schema files and migrations.
41
+ - Managed schema blueprint files whose current hash matches `loom.json`; put
42
+ app-specific schema changes in separate local schema files instead of editing
43
+ generated blueprint files.
44
+ - Intentional refinements under `src/db/valibot/refinements`.
45
+ - Any app-local fixture filtering logic inside `scripts/dump-test-tables.ts`.
46
+ - Transactional code paths that depend on `neonFull.ts`.
47
+
48
+ ## Validation and tests
49
+
50
+ - Use `loom db schema-gen` after schema changes that affect generated Valibot
51
+ output.
52
+ - Use `loom db schemas sync` to refresh active Loom-managed schema blueprints,
53
+ then review diffs and run the normal migration generation flow deliberately.
54
+ - Keep `src/db/valibot/generated/*` generated and committed, never hand-edited.
55
+ - Prefer `tests/memory-pglite.ts` plus a mock of `@/db/neon` or `@/db/neonFull`
56
+ for DB-backed unit tests.
57
+ - If fixtures are used, keep them under `tests/fixtures/db/` and serialize them
58
+ with `superjson`.
59
+
60
+ ## Verification
61
+
62
+ - Run `loom check` after DB feature changes.
63
+ - Confirm package scripts still point at Loom-managed commands, especially
64
+ `schema:gen`, `db:fixtures`, and the Drizzle script that runs through
65
+ `loom env --`.
66
+ - Confirm `drizzle.config.ts` still points at the configured schema and drizzle
67
+ directories.
68
+ - Confirm the Valibot barrel matches the generated and refinement modules.
69
+ - Confirm active Loom-managed feature schemas match their recorded hash in
70
+ `loom.json` and are exported from the app-local schema barrel.
71
+ - For Vercel production releases, confirm `vercel.json` disables automatic
72
+ `main` deployments and GitHub Actions builds with Vercel production settings,
73
+ uploads a staged production deployment with `--prebuilt --prod --skip-domain`,
74
+ runs `db:migrate` with the env file produced by `vercel pull`, and then
75
+ promotes the staged deployment. `vercel env run` omits Sensitive variables and
76
+ is not the release migration boundary. Pass `--scope "$VERCEL_ORG_ID"` to
77
+ Vercel CLI release commands so multi-account CI jobs do not resolve the wrong
78
+ team.
79
+ - Use `loom check --network` after wiring a production release workflow so Loom
80
+ can verify the linked Vercel project plus GitHub's `VERCEL_TOKEN`,
81
+ `VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` release configuration.
82
+ - Use `loom db release setup-github` to create/update that GitHub release
83
+ configuration from the linked Vercel project, including storing a Vercel token
84
+ scoped to the linked team as the GitHub `VERCEL_TOKEN` environment secret.
85
+ - Smoke check the staged deployment URL after promotion with normal `curl`.
86
+ Create a short-lived Vercel Protection Bypass for Automation secret through
87
+ the Vercel API, send it as the `x-vercel-protection-bypass` header, and revoke
88
+ it in the same step. Avoid the beta `vercel curl` command in CI.
89
+ - Production migrations must remain backward-compatible with the currently live
90
+ app because old code continues serving traffic until the staged deployment is
91
+ promoted. Use expand/contract migrations for destructive schema changes.
92
+ - Keep `VERCEL_TOKEN` in a protected GitHub Environment, limit that environment
93
+ to release branches, and expose the token only on steps that call Vercel. Pin
94
+ third-party Actions to full commit SHAs and let Dependabot maintain them.
@@ -0,0 +1,39 @@
1
+ # Loom DB Stack
2
+
3
+ The Loom DB feature standardizes the cross-app wiring around:
4
+
5
+ - thin wrappers for `src/db/neon.ts`
6
+ - thin wrappers for `src/db/neonFull.ts`
7
+ - thin wrappers for `drizzle.config.ts`
8
+ - `scripts/dump-test-tables.ts` as an app-local table-selection entrypoint
9
+ - thin wrappers for `tests/memory-pglite.ts`
10
+ - thin wrappers for `src/db/valibot/refinements/_common.ts`
11
+ - `src/db/valibot/index.ts`
12
+ - `package.json` DB scripts, including `schema:gen` and `db:fixtures`
13
+
14
+ It does not own:
15
+
16
+ - app-specific schema files or migrations
17
+ - local schema extensions around Loom-managed schema blueprints
18
+ - auth runtime setup
19
+ - domain-specific Valibot refinements
20
+ - fixture table selection policy
21
+
22
+ Schema-bearing Loom features may own versioned blueprints that are materialized
23
+ into committed app-local schema files. `loom db schemas sync` refreshes those
24
+ files only when the current file still matches the hash recorded in `loom.json`;
25
+ it does not generate migrations.
26
+
27
+ The intended consumer flow is:
28
+
29
+ 1. `loom add db`
30
+ 2. keep schema files app-local under the configured schema directory
31
+ 3. keep only app-local fixture table selection in `scripts/dump-test-tables.ts`
32
+ 4. run `loom db schema-gen`
33
+ 5. run `loom check`
34
+
35
+ For schema-bearing feature updates:
36
+
37
+ 1. run `loom db schemas sync`
38
+ 2. review the schema diff
39
+ 3. run the app's normal `db:generate` flow if the schema changed
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: loom-files
3
+ description: Use when the task touches the Loom files feature, loomFiles.ts, @gadicc/loom/files, @gadicc/loom/next/files, upload/download routes, object storage, or legacy file2 migration planning in a consuming app.
4
+ ---
5
+
6
+ # Loom Files
7
+
8
+ Use this skill when working on the shared files feature from a consuming app.
9
+
10
+ ## Start here
11
+
12
+ 1. Read `loom.json`.
13
+ 2. Inspect `features.files.config.schema` and `features.db.config` before
14
+ assuming schema paths.
15
+ 3. Confirm the app-local schema barrel exports the managed files schema.
16
+ 4. Identify the app-local repository, storage, auth, route, and UI adapters.
17
+
18
+ ## Ownership boundaries
19
+
20
+ - Loom owns the managed `files` schema blueprint, runtime contracts, headless
21
+ helpers, and route factories.
22
+ - The consuming app owns Drizzle migrations, repository adapter code, storage
23
+ provider configuration, auth/access policy, route placement, UI, and domain
24
+ associations.
25
+ - Do not edit the managed `loomFiles.ts` schema file for app-specific columns or
26
+ relations. Add local schema files and export them from the schema barrel.
27
+ - Keep file bytes in object storage and metadata in the DB. Do not store large
28
+ binary artifacts in DB JSON fields.
29
+
30
+ ## Runtime guidance
31
+
32
+ - Use `@gadicc/loom/files` for SHA-256 hashing, digest verification, metadata
33
+ detection, repository/storage contracts, duplicate upload policy, and
34
+ content-addressed save behavior.
35
+ - Use `@gadicc/loom/files/s3` when the app already provides AWS SDK v3 S3 client
36
+ and command constructors. Enable conditional writes for content-addressed
37
+ private uploads when overwrites should be rejected.
38
+ - Use `@gadicc/loom/next/files` for App Router upload, metadata, and download
39
+ handlers. Prefer explicit query params or App Router route params for file
40
+ lookup; avoid loose path-tail inference.
41
+ - The default object key is the server-verified SHA-256 digest. Preserve that
42
+ unless the app has a clear provider-specific key policy.
43
+ - If file rows are user-private and there is no app-local association table yet,
44
+ reject duplicate SHA-256 uploads instead of reusing another user's canonical
45
+ row.
46
+ - Keep upload UI dependencies app-local. Loom helpers should remain headless.
47
+
48
+ ## Cloudflare R2 and local MinIO
49
+
50
+ - Run `loom files r2 setup --account-id <id>` after activating Files. Require
51
+ explicit account selection when Wrangler exposes multiple Cloudflare accounts;
52
+ use `--cloudflare-profile` for a named Wrangler login. Persist the stable
53
+ account ID in `loom.json`, but keep machine-specific profile names local; pass
54
+ the flag per command or bind a profile to the consumer directory with
55
+ `wrangler auth activate`.
56
+ - Keep the default separate private Production and Preview buckets unless the
57
+ app deliberately chooses `--shared-bucket`. Do not enable public development
58
+ URLs, custom domains, browser-direct uploads, or CORS as part of standard
59
+ setup.
60
+ - Create an R2 Object Read & Write API token manually and scope it only to the
61
+ configured bucket or buckets. Use `--configure-secrets` to let Vercel prompt
62
+ for missing Production/Preview values without exposing them to Loom. Never
63
+ copy credentials into Vercel Development or commit them to the repository.
64
+ - Prefer local MinIO, which setup configures in gitignored `.env.local` by
65
+ default. Preserve existing canonical credentials and unrelated env entries. On
66
+ Arch, the MinIO client executable is `mcli`, from the `minio-client` package.
67
+ Use `--local-provider r2 --local-bucket <name>` only when shared dev files are
68
+ intentional, or `--local-provider none` when storage is managed separately.
69
+ - Setup is rerunnable and reuses existing buckets. Use `--repair` only for
70
+ reviewed non-secret drift; do not delete buckets or rotate credentials as a
71
+ repair side effect.
72
+
73
+ ## Legacy migration planning
74
+
75
+ - Inventory old routes, callers, DB records, object keys, ownership semantics,
76
+ and domain records before replacing `file2`.
77
+ - Preserve existing SHA-256 object keys where possible.
78
+ - If old callers or domain records use Mongo ids, add an app-local alias table
79
+ or compatibility wrapper instead of overloading the managed files row.
80
+ - Migrate metadata first, then validate object existence and byte hashes before
81
+ switching upload/download routes.
82
+ - Keep `/api/file2` compatibility only while live callers need it, and route it
83
+ through the shared service layer.
84
+
85
+ ## Verification
86
+
87
+ - Run `loom check` after changing files wiring.
88
+ - Run `loom files r2 check` after provider setup, or `loom check --network` to
89
+ include the same remote account, bucket, privacy, Vercel scope, and local
90
+ MinIO checks with the rest of the project.
91
+ - Treat generated access/storage stubs as unfinished work;
92
+ `loom check
93
+ --production` should fail while they are still present.
94
+ - Run `loom db schemas sync` only for managed blueprint refreshes, then review
95
+ diffs and generate migrations with the app's normal DB flow.
96
+ - Add route tests for upload, metadata lookup, authorization failures, digest
97
+ mismatch, dedupe, and download behavior.
@@ -0,0 +1,148 @@
1
+ ---
2
+ name: loom-jobs
3
+ description: Use when the task mentions the loom jobs feature, src/jobs or jobs catalogs, /admin/jobs pages or route handlers, createJobsListPage, createJobsRunPage, createJobsRouteHandler, direct runners, or repairing loom-managed jobs wrappers in a consuming app.
4
+ ---
5
+
6
+ # Loom Jobs
7
+
8
+ Use this skill when working on the shared jobs feature from a consuming app.
9
+
10
+ ## Start here
11
+
12
+ 1. Read `loom.json`.
13
+ 2. Inspect `features.jobs.config` and use the configured module and UI paths
14
+ instead of assuming defaults.
15
+ 3. Check the app-local jobs catalog files before changing wrappers.
16
+
17
+ ## Ownership boundaries
18
+
19
+ - App-local jobs still live in the app and remain the source of truth for job
20
+ definitions and app-specific rendering.
21
+ - Shared pages and handlers from `@gadicc/loom` should stay behind thin local
22
+ wrappers when the app uses the standard installation mode.
23
+ - New generated Jobs route wrappers use the 30-minute `maxDuration = 1800`
24
+ default. Override `staticRoutes.maxDuration` or a single job's `maxDuration`
25
+ in `loom.json` when the app needs a shorter limit.
26
+ - If behavior would benefit every loom consumer, fix it in the shared package
27
+ instead of duplicating logic in one app.
28
+
29
+ ## What to preserve
30
+
31
+ - Existing custom renderers or route wrappers that intentionally extend the
32
+ shared helpers.
33
+ - The configured catalog imports, especially metadata-only exports used by the
34
+ jobs list page.
35
+ - Direct-runner settings and script paths when the app has opted into them.
36
+ - Direct job runners should assume env has already been loaded by the package
37
+ script. Keep env loading in scripts such as `job` via `loom env --`, not in
38
+ `scripts/jobDirect.ts`.
39
+
40
+ ## Catalog runtime boundaries
41
+
42
+ - Keep the configured metadata catalog dependency-free. Define job metadata in a
43
+ neutral module and re-export it from each implementation; do not re-export
44
+ `meta` from implementation modules into `indexWithMetaOnly.ts`.
45
+ - Build executable catalog entries with `createLazyJob` and a literal dynamic
46
+ import so Next.js can identify each boundary while the route evaluates only
47
+ the selected implementation:
48
+ ```ts
49
+ export const example = createLazyJob(exampleMeta, () => import("./example"));
50
+ ```
51
+ - Do not use eager `export * as job from "./job"` barrels for HTTP catalogs. A
52
+ single optional or worker-only dependency would then initialize when any
53
+ unrelated job route is requested.
54
+ - A job that supports both an in-process and worker-only runtime should also
55
+ load its worker executor only after the persisted execution target selects
56
+ that runtime.
57
+ - When deployment tracing must isolate large or worker-only dependencies, use
58
+ one static App Router route per job with `createJobRouteHandler({ job })`.
59
+ `createLazyJob` prevents eager runtime evaluation, but one dynamic `[id]`
60
+ route is still one serverless function whose trace includes every reachable
61
+ job implementation.
62
+ - Configure `features.jobs.config.staticRoutes` with the HTTP job-to-module map,
63
+ then run `loom add jobs` to synchronize marker-owned route wrappers. Loom
64
+ preserves unmanaged collisions and `loom check` reports missing, stale, or
65
+ edited managed routes.
66
+ - Keep `maxDuration` as a direct positive integer export in every App Router
67
+ route file. Next.js does not reliably include a re-exported route segment
68
+ config in deployment metadata; Loom-generated routes therefore declare the
69
+ configured literal locally.
70
+
71
+ ## HTTP authorization and API keys
72
+
73
+ - The optional `createJobsRouteHandler` authorization callback protects remote
74
+ HTTP execution. Configure the app's fresh session/admin policy before adding
75
+ any API-key branch.
76
+ - API-key foundation installation does not change jobs. Opt in explicitly with
77
+ `loom api-keys integrate jobs --resource <resource> --action <action>` and
78
+ preserve the existing session/admin branch.
79
+ - Use `authorizeSessionOrApiKeyRequest` plus `completeApiKeyAuthorizedResponse`
80
+ for auditable response creation without buffering job streams.
81
+ - GET and POST remain supported; a future POST-only change requires a separate
82
+ compatibility migration.
83
+ - The direct local runner imports the catalog and executes inside the trusted
84
+ shell process with local environment/database access. It remains API-key-free.
85
+ A future command that calls a deployed HTTP route is a remote client and must
86
+ authenticate.
87
+
88
+ ## Diagnosing queued work
89
+
90
+ - Distinguish the control-plane action that queues a job from the worker or
91
+ runner that actually processes it.
92
+ - When a job-backed workflow fails, inspect durable job/run state before
93
+ inferring from UI status alone: run rows, checkpoints, artifacts, persisted
94
+ metadata, logs, and the trigger that created the run.
95
+ - For resume or challenge flows, verify which state is saved for the suspended
96
+ run and which follow-up trigger is expected to consume it.
97
+ - If the app has no always-on worker in the current environment, call out the
98
+ manual runner or admin route needed to drain queued work.
99
+
100
+ ## Job Parameters and Validation
101
+
102
+ Loom supports declarative job parameter definitions on each job's `meta` object.
103
+ When adding or upgrading a job:
104
+
105
+ - **Declare Parameters**: Specify `params` on the job `meta` object with their
106
+ `type` (`"string" | "number" | "boolean"`), `desc`, and optional `default` or
107
+ `required` flags.
108
+ ```typescript
109
+ export const meta: Job["meta"] = {
110
+ id: "my-job",
111
+ desc: "My job description",
112
+ params: {
113
+ count: {
114
+ type: "number",
115
+ desc: "Number of times to run",
116
+ default: 5,
117
+ },
118
+ verbose: {
119
+ type: "boolean",
120
+ desc: "Enable verbose logs",
121
+ default: false,
122
+ },
123
+ },
124
+ };
125
+ ```
126
+ - **Upgrade Old-Style Params**: If you are working on an existing job that
127
+ accesses parameters from raw query/string objects (e.g. using
128
+ `Number(params.count)` or `params.resetStale === "true"` manually), **upgrade
129
+ it** to use declarative `params` metadata. This removes manual type
130
+ casting/checking boilerplate from the handler and improves safety.
131
+ - **Scaffolding and UI**: Declaring parameters will automatically:
132
+ 1. Render a premium parameters form on the Next.js admin `/run` page with
133
+ hover tooltips and default placeholders.
134
+ 2. Perform automatic type validation on Next.js API routes (returning
135
+ `400 Bad Request` on invalid inputs).
136
+ 3. Validate options and print a beautiful `--help` option menu in the CLI
137
+ `jobDirect` runner.
138
+
139
+ ## Verification
140
+
141
+ - Run `loom check` after changes.
142
+ - Confirm local wrappers still point at the configured shared modules.
143
+ - Confirm the jobs modules still use the shared helpers: `createJobsListPage`,
144
+ `createJobsRunPage`, and `createJobsRouteHandler`.
145
+ - Confirm executable catalog entries use `createLazyJob` and the metadata
146
+ catalog does not import job implementations.
147
+ - Confirm the `job` package script runs the direct runner through `loom env --`
148
+ and that the direct-runner file does not import `dotenv` or `@next/env`.