@gusto/baerly-storage 0.5.0 → 0.7.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 (215) hide show
  1. package/README.md +47 -124
  2. package/dist/API.md +161 -511
  3. package/dist/CHANGELOG.md +1148 -307
  4. package/dist/RECIPES.md +398 -80
  5. package/dist/THIRD-PARTY-LICENSES.txt +5 -26
  6. package/dist/{app-config-DyiFK3_k.d.ts → app-config-C6qW7m8S.d.ts} +119 -111
  7. package/dist/app-config.d.ts +31 -1
  8. package/dist/app-config.js +1 -2
  9. package/dist/app-config.js.map +1 -1
  10. package/dist/auth.d.ts +33 -28
  11. package/dist/auth.js +549 -985
  12. package/dist/auth.js.map +1 -1
  13. package/dist/baerly.js +130 -138
  14. package/dist/baerly.js.map +1 -1
  15. package/dist/baerly.spec.json +97 -22
  16. package/dist/capacity-warning-header-BlVopyiI.js +16 -0
  17. package/dist/capacity-warning-header-BlVopyiI.js.map +1 -0
  18. package/dist/{client-Fe8CwB73.d.ts → client-CHQTXpef.d.ts} +121 -36
  19. package/dist/client-react.d.ts +67 -20
  20. package/dist/client-react.js +240 -54
  21. package/dist/client-react.js.map +1 -1
  22. package/dist/client.d.ts +5 -4
  23. package/dist/client.js +51 -16
  24. package/dist/client.js.map +1 -1
  25. package/dist/{cloudflare-DzKBrUlg.js → cloudflare-CKHYXccw.js} +504 -124
  26. package/dist/cloudflare-CKHYXccw.js.map +1 -0
  27. package/dist/cloudflare.d.ts +106 -71
  28. package/dist/cloudflare.js +334 -271
  29. package/dist/cloudflare.js.map +1 -1
  30. package/dist/code-resolution-CL_7L0wS.js +22 -0
  31. package/dist/code-resolution-CL_7L0wS.js.map +1 -0
  32. package/dist/collection-api-DbyhLAY8.d.ts +1001 -0
  33. package/dist/config-DEzInG6M.js +4035 -0
  34. package/dist/config-DEzInG6M.js.map +1 -0
  35. package/dist/constants-D3GSH3tc.js +469 -0
  36. package/dist/constants-D3GSH3tc.js.map +1 -0
  37. package/dist/{context-DRZ3tZ5l.js → context-rlpSnHFA.js} +17 -17
  38. package/dist/context-rlpSnHFA.js.map +1 -0
  39. package/dist/cost-B52llVDx.js +330 -0
  40. package/dist/cost-B52llVDx.js.map +1 -0
  41. package/dist/{current-json-C6nhPOm1.js → current-json-CC6lE4Aj.js} +115 -32
  42. package/dist/current-json-CC6lE4Aj.js.map +1 -0
  43. package/dist/db-plFUNTSF.d.ts +130 -0
  44. package/dist/db-read-seams-BSs0m1z1.js +3261 -0
  45. package/dist/db-read-seams-BSs0m1z1.js.map +1 -0
  46. package/dist/{deploy-DonTr-CV.js → deploy-Obj4nE-Z.js} +12 -16
  47. package/dist/deploy-Obj4nE-Z.js.map +1 -0
  48. package/dist/{dev-banner-CWHIk8tH.d.ts → dev-banner-B5AUHmu1.d.ts} +1 -4
  49. package/dist/dev-landing-BI5UdmOb.d.ts +32 -0
  50. package/dist/dev-landing-CD-si4dW.js +50 -0
  51. package/dist/dev-landing-CD-si4dW.js.map +1 -0
  52. package/dist/dev-vite.d.ts +38 -39
  53. package/dist/dev-vite.js +67 -36
  54. package/dist/dev-vite.js.map +1 -1
  55. package/dist/dev.d.ts +3 -2
  56. package/dist/dev.js +2 -1
  57. package/dist/doctor-BA0i-YAN.js +270 -0
  58. package/dist/doctor-BA0i-YAN.js.map +1 -0
  59. package/dist/dump-D1vX8ozg.js +133 -0
  60. package/dist/dump-D1vX8ozg.js.map +1 -0
  61. package/dist/errors-7Rk1HGCE.js +160 -0
  62. package/dist/errors-7Rk1HGCE.js.map +1 -0
  63. package/dist/{validate-DtljsCh1.js → export-BVL2EvYE.js} +409 -19
  64. package/dist/export-BVL2EvYE.js.map +1 -0
  65. package/dist/fsck-BWkPgov4.js +145 -0
  66. package/dist/fsck-BWkPgov4.js.map +1 -0
  67. package/dist/gcs-admin-Dso1HWQj.d.ts +127 -0
  68. package/dist/gcs.d.ts +30 -0
  69. package/dist/gcs.js +1 -0
  70. package/dist/goog4-signer-CeLIABoE.js +331 -0
  71. package/dist/goog4-signer-CeLIABoE.js.map +1 -0
  72. package/dist/{http-DGd5tbNs.js → http-Z5rZyYMX.js} +898 -271
  73. package/dist/http-Z5rZyYMX.js.map +1 -0
  74. package/dist/http-transport-DNUM8kU-.js +1299 -0
  75. package/dist/http-transport-DNUM8kU-.js.map +1 -0
  76. package/dist/http.d.ts +366 -294
  77. package/dist/http.js +2 -2
  78. package/dist/index-JJrIu1pO.d.ts +135 -0
  79. package/dist/index-LEgHN0qJ.d.ts +50 -0
  80. package/dist/{index-CuA9Mi3K.d.ts → index-RiEYj8t0.d.ts} +291 -78
  81. package/dist/index.d.ts +27 -6
  82. package/dist/index.js +3 -5
  83. package/dist/inspect-BTsVYZKd.js +196 -0
  84. package/dist/inspect-BTsVYZKd.js.map +1 -0
  85. package/dist/{key-Di6yyxFu.js → key-C4FPZ9Io.js} +3 -4
  86. package/dist/{key-Di6yyxFu.js.map → key-C4FPZ9Io.js.map} +1 -1
  87. package/dist/ledger-Dj_bGgo0.js +192 -0
  88. package/dist/ledger-Dj_bGgo0.js.map +1 -0
  89. package/dist/legacy-names-DgZBtgOh.js +47 -0
  90. package/dist/legacy-names-DgZBtgOh.js.map +1 -0
  91. package/dist/log-C9W15Dfo.d.ts +94 -0
  92. package/dist/log-tail-DWJbneBF.js +142 -0
  93. package/dist/log-tail-DWJbneBF.js.map +1 -0
  94. package/dist/log-walk-C-vA-WGJ.js +111 -0
  95. package/dist/log-walk-C-vA-WGJ.js.map +1 -0
  96. package/dist/maintenance-Dd-Yakqj.js +1709 -0
  97. package/dist/maintenance-Dd-Yakqj.js.map +1 -0
  98. package/dist/maintenance-DevB6z4e.js +2237 -0
  99. package/dist/maintenance-DevB6z4e.js.map +1 -0
  100. package/dist/maintenance.d.ts +100 -3
  101. package/dist/maintenance.js +1 -3
  102. package/dist/node.d.ts +130 -142
  103. package/dist/node.js +4 -3
  104. package/dist/{observability-BmflLCdF.js → observability-C-ISCCLE.js} +1275 -332
  105. package/dist/observability-C-ISCCLE.js.map +1 -0
  106. package/dist/observability.d.ts +27 -3
  107. package/dist/observability.js +3 -3
  108. package/dist/path-segment-DBXG26PW.js +363 -0
  109. package/dist/path-segment-DBXG26PW.js.map +1 -0
  110. package/dist/{plan-a7PJHBCy.js → plan-BvQbaNMe.js} +19 -11
  111. package/dist/plan-BvQbaNMe.js.map +1 -0
  112. package/dist/request-CRWiTrza.js +272 -0
  113. package/dist/request-CRWiTrza.js.map +1 -0
  114. package/dist/restore-U6Im8V1V.js +1467 -0
  115. package/dist/restore-U6Im8V1V.js.map +1 -0
  116. package/dist/retry-OBtLB2GC.js +126 -0
  117. package/dist/retry-OBtLB2GC.js.map +1 -0
  118. package/dist/rolldown-runtime-D3KUYPsf.js +12 -0
  119. package/dist/{runtime-spec-Dsw2-n8S.js → runtime-spec-B5mg3pHF.js} +189 -28
  120. package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
  121. package/dist/{s3-http-B-z8th6O.d.ts → s3-http-DBC_wiCL.d.ts} +18 -10
  122. package/dist/s3.d.ts +20 -7
  123. package/dist/s3.js +4 -5
  124. package/dist/s3.js.map +1 -1
  125. package/dist/sha256-4FfGQNPw.js +22 -0
  126. package/dist/sha256-4FfGQNPw.js.map +1 -0
  127. package/dist/{shared-secret-DgEicd3x.js → shared-secret-Vkur-8r0.js} +27 -15
  128. package/dist/shared-secret-Vkur-8r0.js.map +1 -0
  129. package/dist/sigv4-sign-5IUflUD_.js +507 -0
  130. package/dist/sigv4-sign-5IUflUD_.js.map +1 -0
  131. package/dist/snapshot-CknzkDM0.js +148 -0
  132. package/dist/snapshot-CknzkDM0.js.map +1 -0
  133. package/dist/{src-BL_JoPTn.js → src-Actga-bO.js} +1004 -378
  134. package/dist/src-Actga-bO.js.map +1 -0
  135. package/dist/src-D0MQfvOp.js +812 -0
  136. package/dist/src-D0MQfvOp.js.map +1 -0
  137. package/dist/src-Dr9uo3dc.js +501 -0
  138. package/dist/src-Dr9uo3dc.js.map +1 -0
  139. package/dist/{subcommand-DoDA-K7d.js → subcommand-BLoF66dG.js} +89 -16
  140. package/dist/subcommand-BLoF66dG.js.map +1 -0
  141. package/dist/{time-DUqvFMHq.js → time-DRxTP9iv.js} +15 -34
  142. package/dist/time-DRxTP9iv.js.map +1 -0
  143. package/dist/types-suVbsEWS.d.ts +116 -0
  144. package/dist/{usage-DBV1eQHC.js → usage-CPzVhrQr.js} +40 -45
  145. package/dist/usage-CPzVhrQr.js.map +1 -0
  146. package/dist/uuid-BuT_c404.js +333 -0
  147. package/dist/uuid-BuT_c404.js.map +1 -0
  148. package/dist/verifier-Bmlmndzo.d.ts +95 -0
  149. package/dist/{wire-izfGZDvr.js → wire-DndvKU-K.js} +2 -3
  150. package/dist/wire-DndvKU-K.js.map +1 -0
  151. package/package.json +96 -69
  152. package/dist/aws4fetch.esm-p7eEzLCs.js +0 -1702
  153. package/dist/aws4fetch.esm-p7eEzLCs.js.map +0 -1
  154. package/dist/bytes-BXdamO3L.js +0 -11
  155. package/dist/bytes-BXdamO3L.js.map +0 -1
  156. package/dist/cloudflare-DzKBrUlg.js.map +0 -1
  157. package/dist/config-1tv0-Yzm.js +0 -2693
  158. package/dist/config-1tv0-Yzm.js.map +0 -1
  159. package/dist/constants-CfeMWQWk.js +0 -222
  160. package/dist/constants-CfeMWQWk.js.map +0 -1
  161. package/dist/context-DRZ3tZ5l.js.map +0 -1
  162. package/dist/cost-DSMIVqzL.js +0 -203
  163. package/dist/cost-DSMIVqzL.js.map +0 -1
  164. package/dist/current-json-C6nhPOm1.js.map +0 -1
  165. package/dist/db-DsPkOVEH.d.ts +0 -254
  166. package/dist/deploy-DonTr-CV.js.map +0 -1
  167. package/dist/doctor-DSIyCDg_.js +0 -346
  168. package/dist/doctor-DSIyCDg_.js.map +0 -1
  169. package/dist/dump-Bh5k26VQ.js +0 -94
  170. package/dist/dump-Bh5k26VQ.js.map +0 -1
  171. package/dist/errors-Dfa3p78c.js +0 -78
  172. package/dist/errors-Dfa3p78c.js.map +0 -1
  173. package/dist/export-DtF5tDIM.js +0 -401
  174. package/dist/export-DtF5tDIM.js.map +0 -1
  175. package/dist/fsck-D_djMO5D.js +0 -279
  176. package/dist/fsck-D_djMO5D.js.map +0 -1
  177. package/dist/http-DGd5tbNs.js.map +0 -1
  178. package/dist/index-0rZcMBwy.d.ts +0 -115
  179. package/dist/index-BNRh23K9.d.ts +0 -162
  180. package/dist/index-BYk9oCNf.d.ts +0 -1112
  181. package/dist/indexes-Dn9hbGQG.d.ts +0 -22
  182. package/dist/inspect-6WZ-pC7-.js +0 -133
  183. package/dist/inspect-6WZ-pC7-.js.map +0 -1
  184. package/dist/log-tail-D98U1JBo.js +0 -522
  185. package/dist/log-tail-D98U1JBo.js.map +0 -1
  186. package/dist/maintenance-B4Dki6Ig.js +0 -2157
  187. package/dist/maintenance-B4Dki6Ig.js.map +0 -1
  188. package/dist/maintenance-B_e0T99L.d.ts +0 -537
  189. package/dist/maintenance-C7coQp4c.js +0 -1418
  190. package/dist/maintenance-C7coQp4c.js.map +0 -1
  191. package/dist/normalize-rjnZLwS4.js +0 -133
  192. package/dist/normalize-rjnZLwS4.js.map +0 -1
  193. package/dist/observability-BmflLCdF.js.map +0 -1
  194. package/dist/plan-a7PJHBCy.js.map +0 -1
  195. package/dist/query-rAtXNQQB.js +0 -1773
  196. package/dist/query-rAtXNQQB.js.map +0 -1
  197. package/dist/rebuild-index-BVzQSZlm.js +0 -81
  198. package/dist/rebuild-index-BVzQSZlm.js.map +0 -1
  199. package/dist/request-u0M51mhJ.js +0 -72
  200. package/dist/request-u0M51mhJ.js.map +0 -1
  201. package/dist/restore-R-4rbciV.js +0 -778
  202. package/dist/restore-R-4rbciV.js.map +0 -1
  203. package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
  204. package/dist/runtime-spec-Dsw2-n8S.js.map +0 -1
  205. package/dist/shared-secret-DgEicd3x.js.map +0 -1
  206. package/dist/src-BL_JoPTn.js.map +0 -1
  207. package/dist/src-CYHFDrKz.js +0 -536
  208. package/dist/src-CYHFDrKz.js.map +0 -1
  209. package/dist/src-DYZ4H1aF.js +0 -392
  210. package/dist/src-DYZ4H1aF.js.map +0 -1
  211. package/dist/subcommand-DoDA-K7d.js.map +0 -1
  212. package/dist/time-DUqvFMHq.js.map +0 -1
  213. package/dist/usage-DBV1eQHC.js.map +0 -1
  214. package/dist/validate-DtljsCh1.js.map +0 -1
  215. package/dist/wire-izfGZDvr.js.map +0 -1
@@ -1,392 +0,0 @@
1
- import { t as __commonJSMin } from "./rolldown-runtime-EAsCxrDo.js";
2
- import { n as createCurrentJson } from "./current-json-C6nhPOm1.js";
3
- import { t as BaerlyError } from "./errors-Dfa3p78c.js";
4
- import { t as assertValidStorageKey } from "./key-Di6yyxFu.js";
5
- import { createHash } from "node:crypto";
6
- import { link, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
7
- import { tmpdir } from "node:os";
8
- import { dirname, join, posix, relative, resolve, sep } from "node:path";
9
- //#region node_modules/.pnpm/picocolors@1.1.1/node_modules/picocolors/picocolors.browser.js
10
- var require_picocolors_browser = /* @__PURE__ */ __commonJSMin(((exports, module) => {
11
- var x = String;
12
- var create = function() {
13
- return {
14
- isColorSupported: false,
15
- reset: x,
16
- bold: x,
17
- dim: x,
18
- italic: x,
19
- underline: x,
20
- inverse: x,
21
- hidden: x,
22
- strikethrough: x,
23
- black: x,
24
- red: x,
25
- green: x,
26
- yellow: x,
27
- blue: x,
28
- magenta: x,
29
- cyan: x,
30
- white: x,
31
- gray: x,
32
- bgBlack: x,
33
- bgRed: x,
34
- bgGreen: x,
35
- bgYellow: x,
36
- bgBlue: x,
37
- bgMagenta: x,
38
- bgCyan: x,
39
- bgWhite: x,
40
- blackBright: x,
41
- redBright: x,
42
- greenBright: x,
43
- yellowBright: x,
44
- blueBright: x,
45
- magentaBright: x,
46
- cyanBright: x,
47
- whiteBright: x,
48
- bgBlackBright: x,
49
- bgRedBright: x,
50
- bgGreenBright: x,
51
- bgYellowBright: x,
52
- bgBlueBright: x,
53
- bgMagentaBright: x,
54
- bgCyanBright: x,
55
- bgWhiteBright: x
56
- };
57
- };
58
- module.exports = create();
59
- module.exports.createColors = create;
60
- }));
61
- //#endregion
62
- //#region packages/dev/src/dev-banner.ts
63
- var import_picocolors_browser = require_picocolors_browser();
64
- function printDevBanner(opts) {
65
- const isPlain = opts.plain !== void 0 ? opts.plain : process.env["CI"] !== void 0 || !process.stderr.isTTY;
66
- const write = opts.write ?? ((chunk) => process.stderr.write(chunk));
67
- const pc = (0, import_picocolors_browser.createColors)(!isPlain);
68
- const hints = opts.hints ?? [];
69
- const lines = [];
70
- if (isPlain) {
71
- lines.push(`baerly · ${opts.name}`);
72
- if (opts.primaryUrl) lines.push(`${opts.primaryUrl.label}: ${opts.primaryUrl.url}`);
73
- if (opts.apiUrl) {
74
- const note = opts.apiUrl.note ? ` (${opts.apiUrl.note})` : "";
75
- lines.push(`${opts.apiUrl.label}: ${opts.apiUrl.url}${note}`);
76
- }
77
- for (const hint of hints) lines.push(`${hint.key}: ${hint.value}`);
78
- write(lines.join("\n") + "\n");
79
- } else {
80
- lines.push(pc.bold(pc.cyan(`▎ baerly · ${opts.name}`)));
81
- lines.push("");
82
- if (opts.primaryUrl) {
83
- const marker = ` ${pc.green("← open this")}`;
84
- lines.push(` ${pc.dim(opts.primaryUrl.label)} → ${opts.primaryUrl.url}${marker}`);
85
- }
86
- if (opts.apiUrl) {
87
- const note = opts.apiUrl.note ? ` ${pc.dim(`(${opts.apiUrl.note})`)}` : "";
88
- lines.push(` ${pc.dim(opts.apiUrl.label)} → ${opts.apiUrl.url}${note}`);
89
- }
90
- if ((opts.primaryUrl || opts.apiUrl) && hints.length > 0) lines.push("");
91
- if (hints.length > 0) {
92
- const maxKeyLen = Math.max(...hints.map((h) => h.key.length));
93
- for (const hint of hints) lines.push(` ${pc.dim(hint.key.padEnd(maxKeyLen))} ${hint.value}`);
94
- }
95
- lines.push("");
96
- write(lines.join("\n"));
97
- }
98
- }
99
- //#endregion
100
- //#region packages/dev/src/dev-landing.ts
101
- /**
102
- * Render the dev landing page HTML. Dependency-free; system fonts
103
- * only; no JS. All substitutions are HTML-escaped to keep the page
104
- * inert even when `app` / `uiUrl` come from env vars.
105
- */
106
- const renderDevLanding = (opts) => {
107
- const label = escapeHtml(opts.app);
108
- const app = escapeHtml(opts.app);
109
- const uiUrl = escapeHtml(opts.uiUrl);
110
- return `<!doctype html>
111
- <html lang="en">
112
- <head>
113
- <meta charset="utf-8">
114
- <title>${label} — baerly api</title>
115
- <style>
116
- body { font-family: ui-sans-serif, system-ui, -apple-system, sans-serif; max-width: 40rem; margin: 3rem auto; padding: 0 1.5rem; color: #222; line-height: 1.5; }
117
- h1 { font-size: 1.25rem; margin: 0 0 0.25rem; }
118
- p.tag { color: #666; margin: 0 0 1.5rem; font-size: 0.9rem; }
119
- a { color: #06c; }
120
- ul { padding-left: 1.25rem; }
121
- li { margin: 0.25rem 0; }
122
- code { background: #f3f3f3; padding: 0.1em 0.35em; border-radius: 3px; font-size: 0.9em; }
123
- </style>
124
- </head>
125
- <body>
126
- <h1>${label}</h1>
127
- <p class="tag">baerly api server · app <code>${app}</code></p>
128
- <p>This is the API server. The UI lives at <a href="${uiUrl}">${uiUrl}</a>.</p>
129
- <ul>
130
- <li>Open the UI: <a href="${uiUrl}">${uiUrl}</a></li>
131
- <li>Health probe: <a href="/v1/healthz">/v1/healthz</a></li>
132
- <li>CRUD routes under <code>/v1/c/*</code> require an auth header and aren't clickable from here.</li>
133
- </ul>
134
- </body>
135
- </html>
136
- `;
137
- };
138
- const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => {
139
- switch (c) {
140
- case "&": return "&amp;";
141
- case "<": return "&lt;";
142
- case ">": return "&gt;";
143
- case "\"": return "&quot;";
144
- default: return "&#39;";
145
- }
146
- });
147
- //#endregion
148
- //#region packages/dev/src/ensure-table.ts
149
- /**
150
- * Optional pre-warm: idempotently create the `current.json` manifest
151
- * for a single `(app, tenant, table)` triple. The kernel auto-creates
152
- * this manifest on the first commit anyway (see `Db.create` and
153
- * `Writer.commit`), so calling `ensureTable` is **not required** for
154
- * correctness — it's a one-Class-A-PUT optimization for callers that
155
- * want the manifest in place before the first request lands (seed
156
- * scripts, deploy-time provisioning, CI fixtures that snapshot the
157
- * bucket between phases, etc.).
158
- *
159
- * Wraps {@link createCurrentJson} with the canonical key shape
160
- * (`app/<app>/tenant/<tenant>/manifests/<table>/current.json`) and
161
- * swallows `BaerlyError{code:"Conflict"}` so re-runs are safe. An
162
- * existing manifest is preserved verbatim — this function never
163
- * overwrites a populated manifest. The seed shape matches the
164
- * kernel's auto-create exactly, so a pre-warm and an
165
- * auto-provisioned bucket are byte-identical.
166
- *
167
- * @example
168
- * ```ts
169
- * import { LocalFsStorage, ensureTable } from "@gusto/baerly-storage/dev";
170
- *
171
- * const storage = new LocalFsStorage({ root: "./.baerly-data" });
172
- * // Pre-warm so the first request doesn't pay the bootstrap PUT.
173
- * await ensureTable(storage, { app: "helpdesk", tenant: "demo", table: "tickets" });
174
- * // …then `baerlyNode({ config, storage, verifier })`.
175
- * ```
176
- */
177
- const ensureTable = async (storage, args) => {
178
- const key = `app/${args.app}/tenant/${args.tenant}/manifests/${args.table}/current.json`;
179
- try {
180
- await createCurrentJson(storage, key, {
181
- schema_version: 3,
182
- snapshot: null,
183
- tail_hint: 0,
184
- log_seq_start: 0,
185
- writer_fence: {
186
- epoch: 0,
187
- owner: "",
188
- claimed_at: ""
189
- },
190
- snapshot_bytes: 0,
191
- snapshot_rows: 0
192
- });
193
- } catch (error) {
194
- if (error instanceof BaerlyError && error.code === "Conflict") return;
195
- throw error;
196
- }
197
- };
198
- //#endregion
199
- //#region packages/dev/src/local-fs.ts
200
- /**
201
- * Reserved prefix for the in-directory create-if-absent temp (see `put`).
202
- * `walk`/`list` skip it; it is internal/transient and never a real key.
203
- */
204
- const TEMP_PREFIX = ".baerly-tmp-";
205
- const utf8Encoder = new TextEncoder();
206
- /**
207
- * Compare two keys by their UTF-8 byte sequences — the order S3 and R2
208
- * use for `list`. JS's default string sort compares UTF-16 code units,
209
- * which diverges from UTF-8 byte order for supplementary-plane
210
- * characters; using this keeps `list` ordering faithful to the real
211
- * adapters. (All kernel keys are ASCII base-32, where both orders
212
- * coincide.)
213
- */
214
- const compareKeysUtf8 = (a, b) => {
215
- const ba = utf8Encoder.encode(a);
216
- const bb = utf8Encoder.encode(b);
217
- const n = Math.min(ba.length, bb.length);
218
- for (let i = 0; i < n; i++) if (ba[i] !== bb[i]) return ba[i] - bb[i];
219
- return ba.length - bb.length;
220
- };
221
- /**
222
- * `Storage` backed by a directory tree. Keys may contain `/` and map
223
- * to nested directories on disk so `ls`/`cat` work as expected.
224
- *
225
- * ETags are content-addressed: `"<sha-256-hex>"` (the surrounding
226
- * double-quotes match S3's wire format for non-multipart objects).
227
- * Identical bodies share an ETag across runs — the property that
228
- * makes this adapter useful for fixture-based tests.
229
- *
230
- * Writes are atomic via `writeFile(temp) + rename(final)`; readers
231
- * never see a partially-written file.
232
- *
233
- * `ifNoneMatch:"*"` uses a same-dir temp + `link(2)` (atomic exclusive
234
- * create; `EEXIST` ⇒ key exists) so concurrent creates have exactly one
235
- * winner. Same-dir avoids `EXDEV`; temp+`link` over `open(…,"wx")` keeps
236
- * a partially-written new key invisible to a concurrent reader. `ifMatch`
237
- * keeps the `rename` path (in-process TOCTOU only; cross-process
238
- * contention uses the S3 / Minio `If-Match` path).
239
- *
240
- * Node-only — imports `node:fs`, `node:path`, `node:crypto`. Lives in
241
- * `@baerly/dev` because the protocol kernel is pure-modules / no I/O
242
- * and must remain Worker-bundleable.
243
- */
244
- var LocalFsStorage = class {
245
- #root;
246
- constructor(opts) {
247
- this.#root = resolve(opts.root);
248
- }
249
- async get(key, opts) {
250
- opts?.signal?.throwIfAborted();
251
- const path = this.#pathFor(key);
252
- let body;
253
- try {
254
- body = await readFile(path);
255
- } catch (error) {
256
- if (isErrnoException(error) && error.code === "ENOENT") return null;
257
- throw new BaerlyError("InvalidResponse", `LocalFsStorage.get(${key}): ${error.message}`, error);
258
- }
259
- const etag = etagOf(body);
260
- if (opts?.ifNoneMatch !== void 0 && opts.ifNoneMatch === etag) return null;
261
- return {
262
- body: toUint8Array(body),
263
- etag
264
- };
265
- }
266
- async put(key, body, opts) {
267
- opts?.signal?.throwIfAborted();
268
- const path = this.#pathFor(key);
269
- const newEtag = etagOf(body);
270
- await mkdir(dirname(path), { recursive: true });
271
- if (opts?.ifNoneMatch === "*") {
272
- const tmp = join(dirname(path), `${TEMP_PREFIX}${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
273
- try {
274
- await writeFile(tmp, body);
275
- await link(tmp, path);
276
- } catch (error) {
277
- if (isErrnoException(error) && error.code === "EEXIST") throw new BaerlyError("Conflict", `PUT ${key}: precondition failed (ifNoneMatch="*" but key exists)`);
278
- throw new BaerlyError("InvalidResponse", `LocalFsStorage.put(${key}): ${error.message}`, error);
279
- } finally {
280
- await rm(tmp, { force: true }).catch(() => {});
281
- }
282
- return {
283
- etag: newEtag,
284
- serverDate: /* @__PURE__ */ new Date()
285
- };
286
- }
287
- if (opts?.ifMatch !== void 0) {
288
- const existing = await readExisting(path);
289
- if (existing === null) throw new BaerlyError("Conflict", `PUT ${key}: precondition failed (ifMatch=${opts.ifMatch} but key does not exist)`);
290
- const currentEtag = etagOf(existing);
291
- if (currentEtag !== opts.ifMatch) throw new BaerlyError("Conflict", `PUT ${key}: precondition failed (ifMatch=${opts.ifMatch} but current ETag is ${currentEtag})`);
292
- }
293
- const tmp = join(tmpdir(), `baerly-localfs-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
294
- await writeFile(tmp, body);
295
- try {
296
- await rename(tmp, path);
297
- } catch (error) {
298
- await rm(tmp, { force: true }).catch(() => {});
299
- throw new BaerlyError("InvalidResponse", `LocalFsStorage.put(${key}): ${error.message}`, error);
300
- }
301
- return {
302
- etag: newEtag,
303
- serverDate: /* @__PURE__ */ new Date()
304
- };
305
- }
306
- async delete(key, opts) {
307
- opts?.signal?.throwIfAborted();
308
- const path = this.#pathFor(key);
309
- try {
310
- await rm(path);
311
- } catch (error) {
312
- if (isErrnoException(error) && error.code === "ENOENT") return;
313
- throw new BaerlyError("InvalidResponse", `LocalFsStorage.delete(${key}): ${error.message}`, error);
314
- }
315
- }
316
- async *list(prefix, opts) {
317
- opts?.signal?.throwIfAborted();
318
- const startAfter = opts?.startAfter ?? "";
319
- const maxKeys = opts?.maxKeys ?? Infinity;
320
- const keys = [];
321
- await walk(this.#root, keys);
322
- keys.sort(compareKeysUtf8);
323
- let yielded = 0;
324
- for (const key of keys) {
325
- if (!key.startsWith(prefix)) continue;
326
- if (compareKeysUtf8(key, startAfter) <= 0) continue;
327
- if (yielded >= maxKeys) return;
328
- opts?.signal?.throwIfAborted();
329
- yield {
330
- key,
331
- etag: etagOf(await readFile(this.#pathFor(key)))
332
- };
333
- yielded += 1;
334
- }
335
- }
336
- /**
337
- * Map an S3-style key to a filesystem path under `#root`, rejecting
338
- * anything that could escape the root (path traversal, absolute
339
- * paths, empty segments, backslashes). All rejections throw
340
- * `BaerlyError("InvalidConfig", …)`.
341
- */
342
- #pathFor(key) {
343
- assertValidStorageKey(key);
344
- if (key.startsWith("/")) throw new BaerlyError("InvalidConfig", `LocalFsStorage: leading "/" in key: ${key}`);
345
- if (key.includes("\\")) throw new BaerlyError("InvalidConfig", `LocalFsStorage: backslash in key: ${key}`);
346
- const segments = key.split("/");
347
- if (segments.some((s) => s === "" || s === "." || s === "..")) throw new BaerlyError("InvalidConfig", `LocalFsStorage: illegal segment in key: ${key}`);
348
- const path = join(this.#root, ...segments);
349
- if (path !== this.#root && !path.startsWith(this.#root + sep)) throw new BaerlyError("InvalidConfig", `LocalFsStorage: resolved path escapes root: ${key}`);
350
- return path;
351
- }
352
- };
353
- const etagOf = (body) => {
354
- return `"${createHash("sha256").update(body).digest("hex")}"`;
355
- };
356
- const toUint8Array = (buf) => new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
357
- const isErrnoException = (e) => typeof e === "object" && e !== null && "code" in e;
358
- const readExisting = async (path) => {
359
- try {
360
- return await readFile(path);
361
- } catch (error) {
362
- if (isErrnoException(error) && error.code === "ENOENT") return null;
363
- throw error;
364
- }
365
- };
366
- /**
367
- * Recursive directory walk. Yields filesystem-relative paths in
368
- * forward-slash form so callers can use them as S3-style keys
369
- * regardless of the host's path separator.
370
- */
371
- const walk = async (root, out) => {
372
- const stack = [root];
373
- while (stack.length > 0) {
374
- const dir = stack.pop();
375
- let entries;
376
- try {
377
- entries = await readdir(dir, { withFileTypes: true });
378
- } catch (error) {
379
- if (isErrnoException(error) && error.code === "ENOENT") continue;
380
- throw error;
381
- }
382
- for (const entry of entries) {
383
- const full = join(dir, entry.name);
384
- if (entry.isDirectory()) stack.push(full);
385
- else if (entry.isFile() && !entry.name.startsWith(TEMP_PREFIX)) out.push(relative(root, full).split(sep).join(posix.sep));
386
- }
387
- }
388
- };
389
- //#endregion
390
- export { require_picocolors_browser as a, printDevBanner as i, ensureTable as n, renderDevLanding as r, LocalFsStorage as t };
391
-
392
- //# sourceMappingURL=src-DYZ4H1aF.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"src-DYZ4H1aF.js","names":["#root","#pathFor"],"sources":["../node_modules/.pnpm/picocolors@1.1.1/node_modules/picocolors/picocolors.browser.js","../packages/dev/src/dev-banner.ts","../packages/dev/src/dev-landing.ts","../packages/dev/src/ensure-table.ts","../packages/dev/src/local-fs.ts"],"sourcesContent":["var x=String;\nvar create=function() {return {isColorSupported:false,reset:x,bold:x,dim:x,italic:x,underline:x,inverse:x,hidden:x,strikethrough:x,black:x,red:x,green:x,yellow:x,blue:x,magenta:x,cyan:x,white:x,gray:x,bgBlack:x,bgRed:x,bgGreen:x,bgYellow:x,bgBlue:x,bgMagenta:x,bgCyan:x,bgWhite:x,blackBright:x,redBright:x,greenBright:x,yellowBright:x,blueBright:x,magentaBright:x,cyanBright:x,whiteBright:x,bgBlackBright:x,bgRedBright:x,bgGreenBright:x,bgYellowBright:x,bgBlueBright:x,bgMagentaBright:x,bgCyanBright:x,bgWhiteBright:x}};\nmodule.exports=create();\nmodule.exports.createColors = create;\n","import { createColors } from \"picocolors\";\n\nexport interface DevBannerHint {\n readonly key: string;\n readonly value: string;\n}\n\nexport interface DevBannerOpts {\n readonly name: string;\n readonly primaryUrl?: { readonly label: string; readonly url: string };\n readonly apiUrl?: { readonly label: string; readonly url: string; readonly note?: string };\n readonly hints?: ReadonlyArray<DevBannerHint>;\n /** Force plain-text output (no color, no `←`). Defaults to !isTTY || CI. */\n readonly plain?: boolean;\n /** Sink. Defaults to process.stderr. */\n readonly write?: (chunk: string) => void;\n}\n\nexport function printDevBanner(opts: DevBannerOpts): void {\n const isPlain =\n opts.plain !== undefined\n ? opts.plain\n : process.env[\"CI\"] !== undefined || !process.stderr.isTTY;\n const write = opts.write ?? ((chunk) => process.stderr.write(chunk));\n const pc = createColors(!isPlain);\n const hints = opts.hints ?? [];\n\n const lines: string[] = [];\n\n if (isPlain) {\n lines.push(`baerly · ${opts.name}`);\n\n if (opts.primaryUrl) {\n lines.push(`${opts.primaryUrl.label}: ${opts.primaryUrl.url}`);\n }\n if (opts.apiUrl) {\n const note = opts.apiUrl.note ? ` (${opts.apiUrl.note})` : \"\";\n lines.push(`${opts.apiUrl.label}: ${opts.apiUrl.url}${note}`);\n }\n for (const hint of hints) {\n lines.push(`${hint.key}: ${hint.value}`);\n }\n write(lines.join(\"\\n\") + \"\\n\");\n } else {\n lines.push(pc.bold(pc.cyan(`▎ baerly · ${opts.name}`)));\n lines.push(\"\");\n\n if (opts.primaryUrl) {\n const marker = ` ${pc.green(\"← open this\")}`;\n lines.push(` ${pc.dim(opts.primaryUrl.label)} → ${opts.primaryUrl.url}${marker}`);\n }\n if (opts.apiUrl) {\n const note = opts.apiUrl.note ? ` ${pc.dim(`(${opts.apiUrl.note})`)}` : \"\";\n lines.push(` ${pc.dim(opts.apiUrl.label)} → ${opts.apiUrl.url}${note}`);\n }\n if ((opts.primaryUrl || opts.apiUrl) && hints.length > 0) {\n lines.push(\"\");\n }\n if (hints.length > 0) {\n const maxKeyLen = Math.max(...hints.map((h) => h.key.length));\n for (const hint of hints) {\n lines.push(` ${pc.dim(hint.key.padEnd(maxKeyLen))} ${hint.value}`);\n }\n }\n lines.push(\"\");\n write(lines.join(\"\\n\"));\n }\n}\n","/**\n * Dev landing page for the API root (`GET /`).\n *\n * The HTTP surface is API-only: every path outside `/v1/*`\n * returns the {@link HttpErrorEnvelope} 404 shape. That's correct for\n * production but confusing in local dev — a user who clicks the\n * `http://localhost:3000` link in their terminal sees a JSON 404 and\n * assumes the server is broken.\n *\n * Adapters that wire the {@link DevLandingOptions} opt-in surface a\n * small HTML page on `GET /` instead: app label, a clickable link to\n * the UI, a `/v1/healthz` probe link, and a note that `/v1/c/*` is\n * auth-gated. `GET /favicon.ico` answers 204 so browsers don't pin a\n * second JSON 404 next to the landing page.\n *\n * Production deployments leave the option unset; the 404 falls\n * through to the existing envelope.\n */\n\n/** Options for {@link renderDevLanding}. */\nexport interface DevLandingOptions {\n /** Bucket-prefix / app name (typically passed through from the adapter's `app` option). */\n readonly app: string;\n /** URL of the human-facing UI (e.g., `\"http://localhost:5173\"`). */\n readonly uiUrl: string;\n}\n\n/**\n * Render the dev landing page HTML. Dependency-free; system fonts\n * only; no JS. All substitutions are HTML-escaped to keep the page\n * inert even when `app` / `uiUrl` come from env vars.\n */\nexport const renderDevLanding = (opts: DevLandingOptions): string => {\n const label = escapeHtml(opts.app);\n const app = escapeHtml(opts.app);\n const uiUrl = escapeHtml(opts.uiUrl);\n return `<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<title>${label} — baerly api</title>\n<style>\n body { font-family: ui-sans-serif, system-ui, -apple-system, sans-serif; max-width: 40rem; margin: 3rem auto; padding: 0 1.5rem; color: #222; line-height: 1.5; }\n h1 { font-size: 1.25rem; margin: 0 0 0.25rem; }\n p.tag { color: #666; margin: 0 0 1.5rem; font-size: 0.9rem; }\n a { color: #06c; }\n ul { padding-left: 1.25rem; }\n li { margin: 0.25rem 0; }\n code { background: #f3f3f3; padding: 0.1em 0.35em; border-radius: 3px; font-size: 0.9em; }\n</style>\n</head>\n<body>\n<h1>${label}</h1>\n<p class=\"tag\">baerly api server · app <code>${app}</code></p>\n<p>This is the API server. The UI lives at <a href=\"${uiUrl}\">${uiUrl}</a>.</p>\n<ul>\n <li>Open the UI: <a href=\"${uiUrl}\">${uiUrl}</a></li>\n <li>Health probe: <a href=\"/v1/healthz\">/v1/healthz</a></li>\n <li>CRUD routes under <code>/v1/c/*</code> require an auth header and aren't clickable from here.</li>\n</ul>\n</body>\n</html>\n`;\n};\n\nconst escapeHtml = (s: string): string =>\n s.replace(/[&<>\"']/g, (c) => {\n switch (c) {\n case \"&\": {\n return \"&amp;\";\n }\n case \"<\": {\n return \"&lt;\";\n }\n case \">\": {\n return \"&gt;\";\n }\n case '\"': {\n return \"&quot;\";\n }\n default: {\n return \"&#39;\";\n }\n }\n });\n","import {\n BaerlyError,\n CURRENT_JSON_SCHEMA_VERSION,\n createCurrentJson,\n type Storage,\n} from \"@baerly/protocol\";\n\n/**\n * Optional pre-warm: idempotently create the `current.json` manifest\n * for a single `(app, tenant, table)` triple. The kernel auto-creates\n * this manifest on the first commit anyway (see `Db.create` and\n * `Writer.commit`), so calling `ensureTable` is **not required** for\n * correctness — it's a one-Class-A-PUT optimization for callers that\n * want the manifest in place before the first request lands (seed\n * scripts, deploy-time provisioning, CI fixtures that snapshot the\n * bucket between phases, etc.).\n *\n * Wraps {@link createCurrentJson} with the canonical key shape\n * (`app/<app>/tenant/<tenant>/manifests/<table>/current.json`) and\n * swallows `BaerlyError{code:\"Conflict\"}` so re-runs are safe. An\n * existing manifest is preserved verbatim — this function never\n * overwrites a populated manifest. The seed shape matches the\n * kernel's auto-create exactly, so a pre-warm and an\n * auto-provisioned bucket are byte-identical.\n *\n * @example\n * ```ts\n * import { LocalFsStorage, ensureTable } from \"@gusto/baerly-storage/dev\";\n *\n * const storage = new LocalFsStorage({ root: \"./.baerly-data\" });\n * // Pre-warm so the first request doesn't pay the bootstrap PUT.\n * await ensureTable(storage, { app: \"helpdesk\", tenant: \"demo\", table: \"tickets\" });\n * // …then `baerlyNode({ config, storage, verifier })`.\n * ```\n */\nexport const ensureTable = async (\n storage: Storage,\n args: { app: string; tenant: string; table: string },\n): Promise<void> => {\n const key = `app/${args.app}/tenant/${args.tenant}/manifests/${args.table}/current.json`;\n try {\n await createCurrentJson(storage, key, {\n schema_version: CURRENT_JSON_SCHEMA_VERSION,\n snapshot: null,\n tail_hint: 0,\n log_seq_start: 0,\n writer_fence: { epoch: 0, owner: \"\", claimed_at: \"\" },\n snapshot_bytes: 0,\n snapshot_rows: 0,\n });\n } catch (error) {\n if (error instanceof BaerlyError && error.code === \"Conflict\") {\n return;\n }\n throw error;\n }\n};\n","import { createHash } from \"node:crypto\";\nimport { link, mkdir, readdir, readFile, rename, rm, writeFile } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { dirname, join, posix, relative, resolve, sep } from \"node:path\";\nimport {\n BaerlyError,\n assertValidStorageKey,\n type Storage,\n type StorageGetOptions,\n type StorageGetResult,\n type StorageListEntry,\n type StoragePutOptions,\n type StoragePutResult,\n} from \"@baerly/protocol\";\n\n/**\n * Reserved prefix for the in-directory create-if-absent temp (see `put`).\n * `walk`/`list` skip it; it is internal/transient and never a real key.\n */\nconst TEMP_PREFIX = \".baerly-tmp-\";\n\nexport interface LocalFsStorageOptions {\n /** Root directory; treated as \"the bucket\". */\n root: string;\n}\n\nconst utf8Encoder = new TextEncoder();\n\n/**\n * Compare two keys by their UTF-8 byte sequences — the order S3 and R2\n * use for `list`. JS's default string sort compares UTF-16 code units,\n * which diverges from UTF-8 byte order for supplementary-plane\n * characters; using this keeps `list` ordering faithful to the real\n * adapters. (All kernel keys are ASCII base-32, where both orders\n * coincide.)\n */\nconst compareKeysUtf8 = (a: string, b: string): number => {\n const ba = utf8Encoder.encode(a);\n const bb = utf8Encoder.encode(b);\n const n = Math.min(ba.length, bb.length);\n for (let i = 0; i < n; i++) {\n if (ba[i] !== bb[i]) {\n return ba[i]! - bb[i]!;\n }\n }\n return ba.length - bb.length;\n};\n\n/**\n * `Storage` backed by a directory tree. Keys may contain `/` and map\n * to nested directories on disk so `ls`/`cat` work as expected.\n *\n * ETags are content-addressed: `\"<sha-256-hex>\"` (the surrounding\n * double-quotes match S3's wire format for non-multipart objects).\n * Identical bodies share an ETag across runs — the property that\n * makes this adapter useful for fixture-based tests.\n *\n * Writes are atomic via `writeFile(temp) + rename(final)`; readers\n * never see a partially-written file.\n *\n * `ifNoneMatch:\"*\"` uses a same-dir temp + `link(2)` (atomic exclusive\n * create; `EEXIST` ⇒ key exists) so concurrent creates have exactly one\n * winner. Same-dir avoids `EXDEV`; temp+`link` over `open(…,\"wx\")` keeps\n * a partially-written new key invisible to a concurrent reader. `ifMatch`\n * keeps the `rename` path (in-process TOCTOU only; cross-process\n * contention uses the S3 / Minio `If-Match` path).\n *\n * Node-only — imports `node:fs`, `node:path`, `node:crypto`. Lives in\n * `@baerly/dev` because the protocol kernel is pure-modules / no I/O\n * and must remain Worker-bundleable.\n */\nexport class LocalFsStorage implements Storage {\n readonly #root: string;\n\n constructor(opts: LocalFsStorageOptions) {\n this.#root = resolve(opts.root);\n }\n\n async get(key: string, opts?: StorageGetOptions): Promise<StorageGetResult | null> {\n opts?.signal?.throwIfAborted();\n const path = this.#pathFor(key);\n let body: Buffer;\n try {\n body = await readFile(path);\n } catch (error) {\n if (isErrnoException(error) && error.code === \"ENOENT\") {\n return null;\n }\n throw new BaerlyError(\n \"InvalidResponse\",\n `LocalFsStorage.get(${key}): ${(error as Error).message}`,\n error,\n );\n }\n const etag = etagOf(body);\n if (opts?.ifNoneMatch !== undefined && opts.ifNoneMatch === etag) {\n // 304 Not Modified — caller's cached copy is current.\n return null;\n }\n return { body: toUint8Array(body), etag };\n }\n\n async put(key: string, body: Uint8Array, opts?: StoragePutOptions): Promise<StoragePutResult> {\n opts?.signal?.throwIfAborted();\n const path = this.#pathFor(key);\n const newEtag = etagOf(body);\n\n await mkdir(dirname(path), { recursive: true });\n\n if (opts?.ifNoneMatch === \"*\") {\n // Atomic exclusive create via link(2) — see class JSDoc.\n const tmp = join(\n dirname(path),\n `${TEMP_PREFIX}${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`,\n );\n try {\n await writeFile(tmp, body);\n await link(tmp, path);\n } catch (error) {\n if (isErrnoException(error) && error.code === \"EEXIST\") {\n throw new BaerlyError(\n \"Conflict\",\n `PUT ${key}: precondition failed (ifNoneMatch=\"*\" but key exists)`,\n );\n }\n throw new BaerlyError(\n \"InvalidResponse\",\n `LocalFsStorage.put(${key}): ${(error as Error).message}`,\n error,\n );\n } finally {\n // Best-effort cleanup — a failed write may leave a partial temp,\n // and a cleanup failure must not mask a Conflict thrown above.\n await rm(tmp, { force: true }).catch(() => {});\n }\n return { etag: newEtag, serverDate: new Date() };\n }\n\n if (opts?.ifMatch !== undefined) {\n // TOCTOU within a process — fine. Cross-process callers should\n // not rely on these guards (see class JSDoc).\n const existing = await readExisting(path);\n if (existing === null) {\n throw new BaerlyError(\n \"Conflict\",\n `PUT ${key}: precondition failed (ifMatch=${opts.ifMatch} but key does not exist)`,\n );\n }\n const currentEtag = etagOf(existing);\n if (currentEtag !== opts.ifMatch) {\n throw new BaerlyError(\n \"Conflict\",\n `PUT ${key}: precondition failed (ifMatch=${opts.ifMatch} but current ETag is ${currentEtag})`,\n );\n }\n }\n\n // Unconditional PUT (or ifMatch already verified above).\n // Write to a unique temp path then rename for atomicity. Temp lives\n // in `os.tmpdir()` so a half-written file never appears under the\n // bucket root where `list` might see it. PID + timestamp + random\n // tail makes the name unique across concurrent writers in the same\n // process.\n const tmp = join(\n tmpdir(),\n `baerly-localfs-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`,\n );\n await writeFile(tmp, body);\n try {\n await rename(tmp, path);\n } catch (error) {\n // Best-effort cleanup of the temp file; swallow any error there\n // so the original failure surfaces unchanged.\n await rm(tmp, { force: true }).catch(() => {});\n throw new BaerlyError(\n \"InvalidResponse\",\n `LocalFsStorage.put(${key}): ${(error as Error).message}`,\n error,\n );\n }\n return { etag: newEtag, serverDate: new Date() };\n }\n\n async delete(key: string, opts?: { signal?: AbortSignal }): Promise<void> {\n opts?.signal?.throwIfAborted();\n const path = this.#pathFor(key);\n try {\n await rm(path);\n } catch (error) {\n if (isErrnoException(error) && error.code === \"ENOENT\") {\n return;\n } // idempotent\n throw new BaerlyError(\n \"InvalidResponse\",\n `LocalFsStorage.delete(${key}): ${(error as Error).message}`,\n error,\n );\n }\n }\n\n async *list(\n prefix: string,\n opts?: {\n startAfter?: string;\n maxKeys?: number;\n signal?: AbortSignal;\n },\n ): AsyncIterable<StorageListEntry> {\n opts?.signal?.throwIfAborted();\n const startAfter = opts?.startAfter ?? \"\";\n const maxKeys = opts?.maxKeys ?? Infinity;\n const keys: string[] = [];\n await walk(this.#root, keys);\n keys.sort(compareKeysUtf8);\n let yielded = 0;\n for (const key of keys) {\n if (!key.startsWith(prefix)) {\n continue;\n }\n if (compareKeysUtf8(key, startAfter) <= 0) {\n continue;\n }\n if (yielded >= maxKeys) {\n return;\n }\n opts?.signal?.throwIfAborted();\n const buf = await readFile(this.#pathFor(key));\n yield { key, etag: etagOf(buf) };\n yielded += 1;\n }\n }\n\n /**\n * Map an S3-style key to a filesystem path under `#root`, rejecting\n * anything that could escape the root (path traversal, absolute\n * paths, empty segments, backslashes). All rejections throw\n * `BaerlyError(\"InvalidConfig\", …)`.\n */\n #pathFor(key: string): string {\n // Shared Storage key grammar (non-empty, no `.`/`..` segments); the\n // FS-specific guards below add traversal/backslash/empty-segment checks.\n assertValidStorageKey(key);\n if (key.startsWith(\"/\")) {\n throw new BaerlyError(\"InvalidConfig\", `LocalFsStorage: leading \"/\" in key: ${key}`);\n }\n if (key.includes(\"\\\\\")) {\n throw new BaerlyError(\"InvalidConfig\", `LocalFsStorage: backslash in key: ${key}`);\n }\n const segments = key.split(\"/\");\n if (segments.some((s) => s === \"\" || s === \".\" || s === \"..\")) {\n throw new BaerlyError(\"InvalidConfig\", `LocalFsStorage: illegal segment in key: ${key}`);\n }\n const path = join(this.#root, ...segments);\n if (path !== this.#root && !path.startsWith(this.#root + sep)) {\n throw new BaerlyError(\"InvalidConfig\", `LocalFsStorage: resolved path escapes root: ${key}`);\n }\n return path;\n }\n}\n\nconst etagOf = (body: Uint8Array): string => {\n const h = createHash(\"sha256\").update(body).digest(\"hex\");\n return `\"${h}\"`;\n};\n\nconst toUint8Array = (buf: Buffer): Uint8Array =>\n new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);\n\nconst isErrnoException = (e: unknown): e is NodeJS.ErrnoException =>\n typeof e === \"object\" && e !== null && \"code\" in e;\n\nconst readExisting = async (path: string): Promise<Buffer | null> => {\n try {\n return await readFile(path);\n } catch (error) {\n if (isErrnoException(error) && error.code === \"ENOENT\") {\n return null;\n }\n throw error;\n }\n};\n\n/**\n * Recursive directory walk. Yields filesystem-relative paths in\n * forward-slash form so callers can use them as S3-style keys\n * regardless of the host's path separator.\n */\nconst walk = async (root: string, out: string[]): Promise<void> => {\n const stack: string[] = [root];\n while (stack.length > 0) {\n const dir = stack.pop()!;\n let entries;\n try {\n entries = await readdir(dir, { withFileTypes: true });\n } catch (error) {\n if (isErrnoException(error) && error.code === \"ENOENT\") {\n continue;\n }\n throw error;\n }\n for (const entry of entries) {\n const full = join(dir, entry.name);\n if (entry.isDirectory()) {\n stack.push(full);\n } else if (entry.isFile() && !entry.name.startsWith(TEMP_PREFIX)) {\n // Skip the transient create-if-absent temps (see TEMP_PREFIX) so a\n // concurrent list during a create never surfaces a half-linked key.\n out.push(relative(root, full).split(sep).join(posix.sep));\n }\n }\n }\n};\n"],"x_google_ignoreList":[0],"mappings":"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"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"subcommand-DoDA-K7d.js","names":[],"sources":["../packages/server/src/names.ts","../packages/server/src/path-segment.ts","../packages/cli/src/subcommand.ts"],"sourcesContent":["import { BaerlyError } from \"@baerly/protocol\";\n\n/** Reject names in the system-reserved leading-\"_\" namespace. See docs/adr/003-layout-versioning-cordon.md. */\nexport const assertNameNotReserved = (name: string, context: string): void => {\n if (name.startsWith(\"_\")) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `${context}: \"${name}\" is reserved — names beginning with \"_\" are reserved for system use. See docs/adr/003-layout-versioning-cordon.md.`,\n );\n }\n};\n","import { BaerlyError } from \"@baerly/protocol\";\nimport { assertNameNotReserved } from \"./names.ts\";\n\n/**\n * Per-segment byte ceiling. S3 and R2 cap a full object key at 1024\n * UTF-8 bytes; a key is several segments, so this 256 leaves real prefix\n * headroom. The assembled multi-segment key sum is bounded separately on\n * the write path, not here. This is an intentional server-local *policy*\n * value (not the protocol-level S3/R2 fact `MAX_KEY_BYTES = 1024` in\n * `@baerly/protocol`'s `constants.ts`); it lives here, co-located with the\n * one rule that uses it, to keep `protocol/constants.ts` out of the\n * validator's bundle closure.\n */\nexport const MAX_SEGMENT_BYTES = 256;\nconst utf8 = new TextEncoder();\n// C0 (U+0000-U+001F) + DEL/C1 (U+007F-U+009F).\n// eslint-disable-next-line no-control-regex -- intentional control-char class\nconst CONTROL_CHARS = /[\\u0000-\\u001f\\u007f-\\u009f]/;\n\n/**\n * The single validation rule for every caller-controlled key segment\n * (`_id`, `collection`, `app`, `tenant`) before it becomes a written\n * key segment or `LocalFsStorage` path. Rejects empty / `\"/\"` /\n * `\".\"`|`\"..\"` / C0-C1 control / leading `\"_\"` (ADR-003) / `> MAX_SEGMENT_BYTES`,\n * all as `BaerlyError{code:\"InvalidConfig\"}`.\n *\n * @param role human label for the segment (\"_id\" | \"collection\" | \"app\" | \"tenant\").\n * @param verb optional calling-context label for the message.\n */\nexport const assertPathSegment = (value: string, role: string, verb = \"\"): void => {\n const where = verb === \"\" ? role : `${verb}: ${role}`;\n if (value.length === 0) {\n throw new BaerlyError(\"InvalidConfig\", `${where} must be a non-empty string`);\n }\n if (value.includes(\"/\")) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `${where} may not contain \"/\": ${JSON.stringify(value)}`,\n );\n }\n if (value === \".\" || value === \"..\") {\n throw new BaerlyError(\n \"InvalidConfig\",\n `${where} may not be \".\" or \"..\": ${JSON.stringify(value)}`,\n );\n }\n if (CONTROL_CHARS.test(value)) {\n throw new BaerlyError(\"InvalidConfig\", `${where} may not contain control characters`);\n }\n if (utf8.encode(value).length > MAX_SEGMENT_BYTES) {\n throw new BaerlyError(\"InvalidConfig\", `${where} is too long (> ${MAX_SEGMENT_BYTES} bytes)`);\n }\n // Leading `_` is the ADR-003 reserved namespace.\n assertNameNotReserved(value, where);\n};\n","/**\n * Shared subcommand scaffolding for `baerly`.\n *\n * Every operator-facing subcommand (`inspect`, `export`, `doctor`, and\n * every `admin/*` command) was independently re-implementing the same\n * five pieces of boilerplate:\n *\n * 1. `setJsonMode(args.json === true)` before any emission.\n * 2. A `KNOWN_KEYS` whitelist asserting unknown `--flag` rejection.\n * 3. An `errorToExitCode(code)` mapping —\n * `InvalidConfig → 1`, `Conflict|Internal|InvalidResponse → 3`,\n * else `2`.\n * 4. `resolveAppTenant(args)` falling back through `baerly.config.*`\n * to either real values or hard-coded `\"app\"` / `\"tenant\"`\n * literals.\n * 5. Two parallel entry points: a citty `defineCommand` block that\n * calls `process.exit(code)` on failure, and a `runXxx(argv)`\n * function for in-process tests that returns the exit code.\n *\n * The five copies drifted: some commands suppressed protocol-level\n * errors (no `Conflict|Internal|InvalidResponse → 3` arm), and the\n * config-fallback silently produced `\"app\"` / `\"tenant\"` literals\n * (confidently-wrong output when no config is present).\n *\n * {@link defineBaerlySubcommand} centralizes the five pieces:\n * - Computes the known-keys set from `Object.keys(args)` itself, so\n * a new flag is picked up automatically.\n * - Applies the full 3-bucket exit-code mapping uniformly.\n * - {@link SubcommandContext.resolveAppTenant} throws\n * `BaerlyError(\"InvalidConfig\", …)` with a `--app` / `--tenant`\n * hint when neither flags nor a loadable `baerly.config.*` supply\n * the values.\n * - Returns a bundle of {@link SubcommandBundle.cmd} (citty wiring)\n * and {@link SubcommandBundle.run} (test entry) sharing one\n * wrapped handler.\n */\n\nimport { type Readable, type Writable } from \"node:stream\";\nimport { defineCommand, parseArgs, type ArgsDef, type ParsedArgs, type CommandDef } from \"citty\";\nimport { BaerlyError } from \"@baerly/protocol\";\nimport { assertPathSegment } from \"@baerly/server/_internal/testing\";\nimport { loadAppConfig } from \"./config.ts\";\nimport { emitError, setJsonMode } from \"./output.ts\";\n\n/**\n * Shared citty arg fragments for the flags every operator command\n * takes with identical wording. Each subcommand spreads the ones it\n * needs into its own `... as const satisfies ArgsDef` literal, so the\n * `--bucket` / `--app` / `--tenant` / `--collection` / `--json`\n * descriptions can't drift copy-to-copy (they did: `--collection` had\n * both \"Collection name\" and \"Collection name.\" variants). Bespoke\n * flags (`--config`, `--indexes`, `--provider`, `--verbose`, …) stay\n * inline in the command that owns them.\n */\nexport const BUCKET_ARG = {\n type: \"string\",\n required: true,\n description: \"Bucket URI (s3://<bucket>[/<prefix>], file:///<abs>, memory://<bucket>)\",\n valueHint: \"bucket-uri\",\n} as const;\n\nexport const APP_ARG = {\n type: \"string\",\n required: false,\n description: \"Application name segment (defaults to baerly.config.ts).\",\n valueHint: \"app\",\n} as const;\n\nexport const TENANT_ARG = {\n type: \"string\",\n required: false,\n description: \"Tenant name segment (defaults to baerly.config.ts).\",\n valueHint: \"tenant\",\n} as const;\n\nexport const COLLECTION_ARG = {\n type: \"string\",\n required: true,\n description: \"Collection name.\",\n valueHint: \"name\",\n} as const;\n\nexport const JSON_ARG = {\n type: \"boolean\",\n description: \"Emit a structured JSON envelope to stdout (success) or stderr (error)\",\n} as const;\n\n/**\n * Optional stdin / stdout streams that a programmatic caller (today:\n * `runDump` / `runRestore` tests, and the export round-trip\n * integration test) can divert in place of `process.stdin` /\n * `process.stdout`. The citty entry point always uses the process\n * streams; only {@link SubcommandBundle.run} accepts these overrides.\n */\nexport interface SubcommandStreams {\n readonly stdin?: Readable;\n readonly stdout?: Writable;\n}\n\n/**\n * Capabilities the subcommand handler receives. Today: app/tenant\n * resolution. Kept narrow so the handler signature stays load-bearing\n * (the helper isn't a god object).\n */\ninterface SubcommandContext {\n /**\n * Returns `{ app, tenant }` resolved from explicit flags or\n * `baerly.config.{ts,js,mjs,json}` in the cwd.\n *\n * @throws BaerlyError code=\"InvalidConfig\" — neither flag was\n * supplied AND no loadable config was found. The error message\n * includes a hint mentioning `--app` / `--tenant`.\n */\n readonly resolveAppTenant: (args: {\n readonly app?: string;\n readonly tenant?: string;\n }) => Promise<{ app: string; tenant: string }>;\n /**\n * Programmatic stdin / stdout overrides. `undefined` (or any\n * missing field) means \"use the process stream\". Only\n * `admin dump` / `admin restore` consume this; other commands\n * ignore the field.\n */\n readonly streams?: SubcommandStreams;\n}\n\n/**\n * Definition fed to {@link defineBaerlySubcommand}. `name` is the JSON\n * envelope tag (`\"inspect\"`, `\"admin.compact\"`, etc.); `args` is the\n * citty ArgsDef; `handler` returns the integer exit code.\n */\nexport interface SubcommandDef<TArgs extends ArgsDef> {\n /** JSON envelope `command` tag and the prefix of every emitted error. */\n readonly name: string;\n readonly meta: { readonly description: string };\n readonly args: TArgs;\n readonly handler: (args: ParsedArgs<TArgs>, ctx: SubcommandContext) => Promise<number>;\n}\n\n/**\n * Output of {@link defineBaerlySubcommand}. `cmd` plugs into\n * `subCommands` in `baerly.ts`; `run` is the in-process entry for\n * unit tests.\n */\nexport interface SubcommandBundle<TArgs extends ArgsDef> {\n readonly cmd: CommandDef<TArgs>;\n readonly run: (\n argv: readonly string[],\n options?: { readonly streams?: SubcommandStreams },\n ) => Promise<number>;\n}\n\n/** Shared exit-code mapping for caught `BaerlyError`s. */\nconst errorToExitCode = (code: string): number => {\n if (code === \"InvalidConfig\") {\n return 1;\n }\n if (code === \"Conflict\" || code === \"Internal\" || code === \"InvalidResponse\") {\n return 3;\n }\n return 2;\n};\n\n/**\n * Validate a `--collection` arg through the same shared rule the\n * server uses for every caller-controlled key segment, before it is\n * interpolated into a bucket key. Throws `BaerlyError(\"InvalidConfig\",\n * …)` on a traversal / empty / control-char / reserved value. `verb`\n * is the operator-facing command name (e.g. `\"baerly admin restore\"`,\n * `\"baerly inspect\"`) so the message names the exact command.\n *\n * (app/tenant are validated at their own chokepoint inside\n * `resolveAppTenant`; this guards the per-command `collection` arg.)\n */\nexport const assertCollectionArg = (collection: string, verb: string): void => {\n assertPathSegment(collection, \"collection\", verb);\n};\n\n/**\n * Build the app/tenant resolver. Captures `name` to surface the\n * calling subcommand in the InvalidConfig hint.\n */\nconst makeResolveAppTenant = (name: string): SubcommandContext[\"resolveAppTenant\"] => {\n return async (args) => {\n const flagApp = typeof args.app === \"string\" && args.app.length > 0 ? args.app : undefined;\n const flagTenant =\n typeof args.tenant === \"string\" && args.tenant.length > 0 ? args.tenant : undefined;\n let app: string;\n let tenant: string;\n if (flagApp !== undefined && flagTenant !== undefined) {\n app = flagApp;\n tenant = flagTenant;\n } else {\n let cfg: { app: string; tenant: string };\n try {\n cfg = await loadAppConfig();\n } catch (error) {\n // Re-throw with our own wording so the operator sees the\n // calling-command name and the hint to pass --app / --tenant\n // explicitly. The underlying loadAppConfig error is preserved\n // as the cause. (Only wraps a config-LOAD failure — the\n // segment validation below is intentionally outside this catch\n // so its own InvalidConfig message survives.)\n const inner = error instanceof BaerlyError ? error.message : (error as Error).message;\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly ${name}: --app / --tenant not supplied and no baerly.config.{ts,js,mjs,json} in cwd (${inner})`,\n error,\n );\n }\n app = flagApp ?? cfg.app;\n tenant = flagTenant ?? cfg.tenant;\n }\n // Single chokepoint covering every command that calls\n // resolveAppTenant: whatever the source (flags or config), the\n // resolved segments must pass the same shared rule before they\n // become bucket-key segments. A bad-but-supplied value throws\n // InvalidConfig, consistent with the \"not supplied\" case above.\n assertPathSegment(app, \"app\", `baerly ${name}`);\n assertPathSegment(tenant, \"tenant\", `baerly ${name}`);\n return { app, tenant };\n };\n};\n\n/**\n * Wrap `def.handler` with the standard JSON-mode toggle, unknown-key\n * rejection, and error-to-exit-code mapping. Shared by both the citty\n * `run({ args })` path and the test `run(argv)` path. The caller\n * supplies the {@link SubcommandContext}; this lets each `run(argv)`\n * invocation attach its own `streams` override without leaking across\n * invocations.\n */\nconst kebabToCamel = (s: string): string => s.replace(/-(\\w)/g, (_, c: string) => c.toUpperCase());\n\nconst wrapHandler = <TArgs extends ArgsDef>(\n def: SubcommandDef<TArgs>,\n): ((args: ParsedArgs<TArgs>, ctx: SubcommandContext) => Promise<number>) => {\n // Compute the allow-list once from the ArgsDef. citty injects `_`\n // for positional captures, so it must stay allowed. citty 0.2.2\n // also auto-injects a camelCase alias for every kebab-case flag\n // (e.g. `--where-comment` produces both `whereComment` and\n // `where-comment` on the parsed args), so each kebab key is\n // expanded to its camelCase variant in the allow-list too.\n const allowedKeys: ReadonlySet<string> = new Set(\n Object.keys(def.args)\n .flatMap((k) => (k.includes(\"-\") ? [k, kebabToCamel(k)] : [k]))\n .concat([\"_\"]),\n );\n return async (args, ctx) => {\n // `json` is conventional but not required — only toggle when it's\n // both declared in the ArgsDef and truthy on the parsed args.\n if (\"json\" in def.args) {\n setJsonMode((args as ParsedArgs<TArgs> & { json?: boolean }).json === true);\n }\n try {\n for (const k of Object.keys(args)) {\n if (!allowedKeys.has(k)) {\n throw new BaerlyError(\"InvalidConfig\", `baerly ${def.name}: unknown flag --${k}`);\n }\n }\n return await def.handler(args, ctx);\n } catch (error) {\n if (error instanceof BaerlyError) {\n emitError(def.name, error.code, error.message);\n return errorToExitCode(error.code);\n }\n emitError(def.name, \"Unknown\", (error as Error).message);\n return 2;\n }\n };\n};\n\n/**\n * Wrap a baerly subcommand. Returns `{ cmd, run }` —\n * - `cmd` is a citty `defineCommand` block; mount it in\n * `baerly.ts`'s `subCommands`. It calls `process.exit(code)` on a\n * non-zero exit so the parent process surfaces the failure.\n * - `run(argv)` is the in-process test entry. It parses `argv` with\n * citty's `parseArgs`, dispatches through the same wrapped\n * handler, and returns the integer exit code (does NOT call\n * `process.exit`).\n *\n * The two paths share `wrapHandler` so JSON-mode toggling,\n * unknown-flag rejection, and error-to-exit-code mapping behave\n * identically.\n */\nexport const defineBaerlySubcommand = <TArgs extends ArgsDef>(\n def: SubcommandDef<TArgs>,\n): SubcommandBundle<TArgs> => {\n const resolveAppTenant = makeResolveAppTenant(def.name);\n const wrapped = wrapHandler(def);\n\n const cmd = defineCommand({\n meta: { name: def.name, description: def.meta.description },\n args: def.args,\n run: async ({ args }) => {\n const code = await wrapped(args as ParsedArgs<TArgs>, { resolveAppTenant });\n if (code !== 0) {\n process.exit(code);\n }\n },\n });\n\n const run = async (\n argv: readonly string[],\n options?: { readonly streams?: SubcommandStreams },\n ): Promise<number> => {\n let parsed: ParsedArgs<TArgs>;\n try {\n parsed = parseArgs<TArgs>(argv as string[], def.args);\n } catch (error) {\n // Parse-time error from citty (missing required flag,\n // malformed value). Toggle JSON mode by sniffing argv since\n // we never reached the handler.\n setJsonMode(argv.includes(\"--json\"));\n emitError(def.name, \"InvalidConfig\", (error as Error).message);\n return 1;\n }\n return wrapped(parsed, { resolveAppTenant, streams: options?.streams });\n };\n\n return { cmd, run };\n};\n"],"mappings":";;;;;AAGA,MAAa,yBAAyB,MAAc,YAA0B;CAC5E,IAAI,KAAK,WAAW,GAAG,GACrB,MAAM,IAAI,YACR,iBACA,GAAG,QAAQ,KAAK,KAAK,oHACvB;AAEJ;ACIA,MAAM,OAAO,IAAI,YAAY;AAG7B,MAAM,gBAAgB;;;;;;;;;;;AAYtB,MAAa,qBAAqB,OAAe,MAAc,OAAO,OAAa;CACjF,MAAM,QAAQ,SAAS,KAAK,OAAO,GAAG,KAAK,IAAI;CAC/C,IAAI,MAAM,WAAW,GACnB,MAAM,IAAI,YAAY,iBAAiB,GAAG,MAAM,4BAA4B;CAE9E,IAAI,MAAM,SAAS,GAAG,GACpB,MAAM,IAAI,YACR,iBACA,GAAG,MAAM,wBAAwB,KAAK,UAAU,KAAK,GACvD;CAEF,IAAI,UAAU,OAAO,UAAU,MAC7B,MAAM,IAAI,YACR,iBACA,GAAG,MAAM,2BAA2B,KAAK,UAAU,KAAK,GAC1D;CAEF,IAAI,cAAc,KAAK,KAAK,GAC1B,MAAM,IAAI,YAAY,iBAAiB,GAAG,MAAM,oCAAoC;CAEtF,IAAI,KAAK,OAAO,KAAK,CAAC,CAAC,SAAA,KACrB,MAAM,IAAI,YAAY,iBAAiB,GAAG,MAAM,2BAA4C;CAG9F,sBAAsB,OAAO,KAAK;AACpC;;;;;;;;;;;;;ACAA,MAAa,aAAa;CACxB,MAAM;CACN,UAAU;CACV,aAAa;CACb,WAAW;AACb;AAEA,MAAa,UAAU;CACrB,MAAM;CACN,UAAU;CACV,aAAa;CACb,WAAW;AACb;AAEA,MAAa,aAAa;CACxB,MAAM;CACN,UAAU;CACV,aAAa;CACb,WAAW;AACb;AAEA,MAAa,iBAAiB;CAC5B,MAAM;CACN,UAAU;CACV,aAAa;CACb,WAAW;AACb;AAEA,MAAa,WAAW;CACtB,MAAM;CACN,aAAa;AACf;;AAoEA,MAAM,mBAAmB,SAAyB;CAChD,IAAI,SAAS,iBACX,OAAO;CAET,IAAI,SAAS,cAAc,SAAS,cAAc,SAAS,mBACzD,OAAO;CAET,OAAO;AACT;;;;;;;;;;;;AAaA,MAAa,uBAAuB,YAAoB,SAAuB;CAC7E,kBAAkB,YAAY,cAAc,IAAI;AAClD;;;;;AAMA,MAAM,wBAAwB,SAAwD;CACpF,OAAO,OAAO,SAAS;EACrB,MAAM,UAAU,OAAO,KAAK,QAAQ,YAAY,KAAK,IAAI,SAAS,IAAI,KAAK,MAAM,KAAA;EACjF,MAAM,aACJ,OAAO,KAAK,WAAW,YAAY,KAAK,OAAO,SAAS,IAAI,KAAK,SAAS,KAAA;EAC5E,IAAI;EACJ,IAAI;EACJ,IAAI,YAAY,KAAA,KAAa,eAAe,KAAA,GAAW;GACrD,MAAM;GACN,SAAS;EACX,OAAO;GACL,IAAI;GACJ,IAAI;IACF,MAAM,MAAM,cAAc;GAC5B,SAAS,OAAO;IAQd,MAAM,IAAI,YACR,iBACA,UAAU,KAAK,gFAHH,iBAAiB,cAAc,MAAM,UAAW,MAAgB,QAGyB,IACrG,KACF;GACF;GACA,MAAM,WAAW,IAAI;GACrB,SAAS,cAAc,IAAI;EAC7B;EAMA,kBAAkB,KAAK,OAAO,UAAU,MAAM;EAC9C,kBAAkB,QAAQ,UAAU,UAAU,MAAM;EACpD,OAAO;GAAE;GAAK;EAAO;CACvB;AACF;;;;;;;;;AAUA,MAAM,gBAAgB,MAAsB,EAAE,QAAQ,WAAW,GAAG,MAAc,EAAE,YAAY,CAAC;AAEjG,MAAM,eACJ,QAC2E;CAO3E,MAAM,cAAmC,IAAI,IAC3C,OAAO,KAAK,IAAI,IAAI,CAAC,CAClB,SAAS,MAAO,EAAE,SAAS,GAAG,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,CAC9D,OAAO,CAAC,GAAG,CAAC,CACjB;CACA,OAAO,OAAO,MAAM,QAAQ;EAG1B,IAAI,UAAU,IAAI,MAChB,YAAa,KAAgD,SAAS,IAAI;EAE5E,IAAI;GACF,KAAK,MAAM,KAAK,OAAO,KAAK,IAAI,GAC9B,IAAI,CAAC,YAAY,IAAI,CAAC,GACpB,MAAM,IAAI,YAAY,iBAAiB,UAAU,IAAI,KAAK,mBAAmB,GAAG;GAGpF,OAAO,MAAM,IAAI,QAAQ,MAAM,GAAG;EACpC,SAAS,OAAO;GACd,IAAI,iBAAiB,aAAa;IAChC,UAAU,IAAI,MAAM,MAAM,MAAM,MAAM,OAAO;IAC7C,OAAO,gBAAgB,MAAM,IAAI;GACnC;GACA,UAAU,IAAI,MAAM,WAAY,MAAgB,OAAO;GACvD,OAAO;EACT;CACF;AACF;;;;;;;;;;;;;;;AAgBA,MAAa,0BACX,QAC4B;CAC5B,MAAM,mBAAmB,qBAAqB,IAAI,IAAI;CACtD,MAAM,UAAU,YAAY,GAAG;CAE/B,MAAM,MAAM,cAAc;EACxB,MAAM;GAAE,MAAM,IAAI;GAAM,aAAa,IAAI,KAAK;EAAY;EAC1D,MAAM,IAAI;EACV,KAAK,OAAO,EAAE,WAAW;GACvB,MAAM,OAAO,MAAM,QAAQ,MAA2B,EAAE,iBAAiB,CAAC;GAC1E,IAAI,SAAS,GACX,QAAQ,KAAK,IAAI;EAErB;CACF,CAAC;CAED,MAAM,MAAM,OACV,MACA,YACoB;EACpB,IAAI;EACJ,IAAI;GACF,SAAS,UAAiB,MAAkB,IAAI,IAAI;EACtD,SAAS,OAAO;GAId,YAAY,KAAK,SAAS,QAAQ,CAAC;GACnC,UAAU,IAAI,MAAM,iBAAkB,MAAgB,OAAO;GAC7D,OAAO;EACT;EACA,OAAO,QAAQ,QAAQ;GAAE;GAAkB,SAAS,SAAS;EAAQ,CAAC;CACxE;CAEA,OAAO;EAAE;EAAK;CAAI;AACpB"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"time-DUqvFMHq.js","names":[],"sources":["../packages/protocol/src/types.ts","../packages/protocol/src/time.ts"],"sourcesContent":["import { COUNT_BIT_WIDTH } from \"./constants.ts\";\n\ndeclare const brand: unique symbol;\ntype Brand<B> = { [brand]: B };\n\n/**\n * Nominal-typing helper. `Branded<string, \"UUID\">` is a `string` at\n * runtime but the type system rejects mixing it with a plain `string` or\n * a string branded as something else. Used to prevent confusion bugs at\n * protocol boundaries (UUIDs vs. content versions are both strings, but\n * using the wrong one corrupts the per-collection log).\n *\n * Construct branded values via the helpers in this file (e.g. {@link uuid})\n * or with a tagged cast at a single, deliberate boundary — never `as string`\n * to widen one back. See `docs/contributing/conventions/src.md`.\n */\nexport type Branded<T, B> = T & Brand<B>;\n\n/**\n * A v4 UUID minted by this client. Used as session IDs and content\n * identifiers in non-versioned mode.\n */\nexport type UUID = Branded<string, \"UUID\">;\n\n/**\n * SHA-256 content digest, lowercase hex truncated to\n * `VERSION_HEX_LENGTH` (32 chars). Minted by\n * `versionFromContent` in `useVersioning=false` mode and used as\n * the `<key>@<version>` suffix in content keys.\n *\n * The synthetic `local-${op}` placeholder used for in-flight\n * optimistic updates also wears this brand — it never round-trips\n * to S3, only flows through local optimistic state.\n */\nexport type ContentVersionId = Branded<string, \"ContentVersionId\">;\n\n/**\n * Mint a fresh {@link UUID}. The cast lives here so callers don't sprinkle\n * `<UUID>crypto.randomUUID()` throughout the codebase.\n */\nexport const uuid = (): UUID => crypto.randomUUID() as UUID;\n\n/**\n * Mint a UUIDv7 — 48-bit Unix-millis prefix + 74 bits of randomness,\n * formatted as a standard 8-4-4-4-12 UUID string per RFC 9562 §5.7.\n * Lex-sortable by mint time, so it pairs well with object-storage\n * list semantics. Returns a branded {@link UUID}.\n *\n * Uses `crypto.getRandomValues` which is universally available\n * (Node 19+, Workerd, Bun, browsers).\n *\n * @example\n * ```ts\n * const id = uuidv7();\n * // e.g. \"01956cad-4cc8-7abc-9def-0123456789ab\"\n * ```\n */\nexport const uuidv7 = (): UUID => {\n const millis = Date.now();\n const rand = new Uint8Array(10);\n crypto.getRandomValues(rand);\n // Version nibble: top 4 bits of rand[0] = 0b0111 (v7). The byte\n // sits at the start of the \"version-and-rand-a\" group below.\n rand[0] = (rand[0]! & 0x0f) | 0x70;\n // Variant bits: top 2 bits of rand[2] = 0b10 (RFC 4122 variant).\n // This byte starts the \"variant-and-rand-b\" group below.\n rand[2] = (rand[2]! & 0x3f) | 0x80;\n const millisHex = millis.toString(16).padStart(12, \"0\");\n const b = Array.from(rand, (n) => n.toString(16).padStart(2, \"0\")).join(\"\");\n return `${millisHex.slice(0, 8)}-${millisHex.slice(8, 12)}-${b.slice(0, 4)}-${b.slice(4, 8)}-${b.slice(8, 20)}` as UUID;\n};\n\n/**\n * Mint the trailing seq segment of an LSN (`<base32-time>_<sess>_<seq>`).\n * Uses `COUNT_BIT_WIDTH` (see `packages/protocol/src/constants.ts`) to\n * produce an 11-char descending base-32 string with a domain of\n * 0 .. `Number.MAX_SAFE_INTEGER` (2^53 − 1).\n *\n * Used together with {@link timestamp} (the descending base-32\n * encoding of millis-since-epoch). See {@link uint2strDesc} for the\n * lex-reversal property both rely on.\n */\nexport const countKey = (number: number): string => uint2strDesc(number, COUNT_BIT_WIDTH);\n\nexport const uint2str = (num: number, bits: number) => {\n const maxBase32Length = Math.ceil(bits / 5); // Change from 4 to 5 because log2(32) is roughly 5.\n const base32Representation = num.toString(32);\n return base32Representation.padStart(maxBase32Length, \"0\");\n};\n\nexport const str2uint = (str: string) => {\n return parseInt(str, 32); // Parse the string as base 32.\n};\n\n/**\n * Lex-reversed base-32 encoder for an unsigned integer in `[0, 2^bits)`.\n * Pads to `Math.ceil(bits/5)` chars so all values in the domain compare\n * lex against each other.\n *\n * **Order-reversal property:** for any pair of integers `a < b` (with\n * `a, b ∈ [0, 2^bits)`), `uint2strDesc(a, bits) > uint2strDesc(b, bits)`\n * lexicographically. Composed into an LSN of shape\n * `<base32-time>_<session>_<seq>` (where both `<base32-time>` and\n * `<seq>` use this encoder), a forward `Storage.list(prefix)`\n * returns log entries in reverse-causal order — newer entries first.\n *\n * This is the structural property the read path leans on:\n * `ListObjectsV2` is forward-only on S3, but the descending encoding\n * makes \"fetch the K newest entries\" a single bounded LIST with\n * `maxKeys=K` instead of a full-population LIST + in-memory reverse.\n *\n * Behaviourally verified across randomized populations in\n * `packages/protocol/src/lsn-reverse-list.test.ts`. Quantified\n * bytes-listed reduction is in\n * `docs/spec/attachments/lsn-reverse-walk-baseline.json`\n * (run `pnpm bench:lsn-reverse-walk` to reproduce). Spec rationale:\n * `docs/spec/sync-protocol.md` §\"LSNs, wall clocks, and downstream\n * consumers\".\n */\nexport const uint2strDesc = (num: number, bits: number): string => {\n const maxValue = Math.pow(2, bits) - 1;\n return uint2str(maxValue - num, bits);\n};\n\nexport const str2uintDesc = (str: string, bits: number): number => {\n const maxValue = Math.pow(2, bits) - 1;\n const num = parseInt(str, 32); // Convert base32 string to number\n return maxValue - num;\n};\n","import { TIMESTAMP_BIT_WIDTH } from \"./constants.ts\";\nimport { BaerlyError } from \"./errors.ts\";\nimport { uint2strDesc } from \"./types.ts\";\n\n/**\n * Encode an epoch-millis instant as a lexicographically-DEScending\n * base-32 key (newer sorts first). The load-bearing LSN ordering\n * primitive — see {@link uint2strDesc}.\n *\n * `epoch` is REQUIRED and validated. There is no default: an argless\n * call used to encode `0`, which descending-sorts as the most-ancient\n * instant and would silently invert ordering. A non-finite, negative,\n * or out-of-range `epoch` (e.g. a broken `Date.now()` returning `NaN`)\n * would corrupt the key silently rather than fail loud, so it throws\n * `Internal` instead — this is an invariant violation, not caller config\n * (the only legitimate argument is `Date.now()`).\n */\nexport const timestamp = (epoch: number): string => {\n if (!Number.isInteger(epoch) || epoch < 0 || epoch >= 2 ** TIMESTAMP_BIT_WIDTH) {\n throw new BaerlyError(\n \"Internal\",\n `timestamp(): epoch must be a non-negative integer < 2^${TIMESTAMP_BIT_WIDTH} (got ${epoch})`,\n );\n }\n return uint2strDesc(epoch, TIMESTAMP_BIT_WIDTH);\n};\n\n/**\n * Delay for `ms` milliseconds, with optional cancellation. If\n * `signal` aborts before the delay elapses, the returned promise\n * rejects with `signal.reason`. Used by `S3HttpStorage`'s retry\n * loop so shutdown can interrupt an in-flight backoff instead of\n * waiting for it to complete.\n */\nexport const delay = (ms: number, signal?: AbortSignal): Promise<void> =>\n new Promise<void>((resolve, reject) => {\n if (signal?.aborted) {\n reject(signal.reason);\n return;\n }\n const timer = setTimeout(resolve, ms);\n signal?.addEventListener(\n \"abort\",\n () => {\n clearTimeout(timer);\n reject(signal.reason);\n },\n // Stryker disable next-line BooleanLiteral,ObjectLiteral: `{ once: true }` removes the\n // listener after the first fire. AbortController fires `abort` only once per signal, so\n // `once: false` / `{}` produce identical observable behaviour — the listener stays attached\n // to an already-fired signal, but calling reject on a settled Promise is a no-op. The\n // BooleanLiteral (once:false) and ObjectLiteral ({}) mutations are genuine equivalences.\n { once: true },\n );\n });\n"],"mappings":";;;;;;AAwCA,MAAa,aAAmB,OAAO,WAAW;;;;;;;;;;;;;;;;AAiBlD,MAAa,eAAqB;CAChC,MAAM,SAAS,KAAK,IAAI;CACxB,MAAM,uBAAO,IAAI,WAAW,EAAE;CAC9B,OAAO,gBAAgB,IAAI;CAG3B,KAAK,KAAM,KAAK,KAAM,KAAQ;CAG9B,KAAK,KAAM,KAAK,KAAM,KAAQ;CAC9B,MAAM,YAAY,OAAO,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,GAAG;CACtD,MAAM,IAAI,MAAM,KAAK,OAAO,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE;CAC1E,OAAO,GAAG,UAAU,MAAM,GAAG,CAAC,EAAE,GAAG,UAAU,MAAM,GAAG,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,EAAE;AAC9G;;;;;;;;;;;AAYA,MAAa,YAAY,WAA2B,aAAa,QAAA,EAAuB;AAExF,MAAa,YAAY,KAAa,SAAiB;CACrD,MAAM,kBAAkB,KAAK,KAAK,OAAO,CAAC;CAE1C,OAD6B,IAAI,SAAS,EAChB,CAAC,CAAC,SAAS,iBAAiB,GAAG;AAC3D;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,MAAa,gBAAgB,KAAa,SAAyB;CAEjE,OAAO,SADU,KAAK,IAAI,GAAG,IAAI,IAAI,IACV,KAAK,IAAI;AACtC;AAEA,MAAa,gBAAgB,KAAa,SAAyB;CAGjE,OAFiB,KAAK,IAAI,GAAG,IAAI,IAAI,IACzB,SAAS,KAAK,EACN;AACtB;;;;;;;;;;;;;;;;AC/GA,MAAa,aAAa,UAA0B;CAClD,IAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,KAAK,SAAS,KAAA,IACpD,MAAM,IAAI,YACR,YACA,iEAAqF,MAAM,EAC7F;CAEF,OAAO,aAAa,OAAA,EAA0B;AAChD;;;;;;;;AASA,MAAa,SAAS,IAAY,WAChC,IAAI,SAAe,SAAS,WAAW;CACrC,IAAI,QAAQ,SAAS;EACnB,OAAO,OAAO,MAAM;EACpB;CACF;CACA,MAAM,QAAQ,WAAW,SAAS,EAAE;CACpC,QAAQ,iBACN,eACM;EACJ,aAAa,KAAK;EAClB,OAAO,OAAO,MAAM;CACtB,GAMA,EAAE,MAAM,KAAK,CACf;AACF,CAAC"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"usage-DBV1eQHC.js","names":[],"sources":["../packages/cli/src/admin/usage.ts"],"sourcesContent":["/**\n * `baerly admin usage` — all-collection writes/min health check.\n *\n * Reads the most recent `SAMPLE_SIZE` log entries for every collection\n * under `app/<app>/tenant/<tenant>/manifests/`, compares the spread of\n * their embedded `commit_ts` timestamps against the M-size operating\n * ceiling (~30 writes/min/collection — see `M_SIZE_WRITES_PER_MIN_PER_COLLECTION`\n * below and `docs/about/thesis.md`), and prints one finding per\n * collection — `info` when well under the ceiling, `warning` when\n * approaching or exceeding it.\n *\n * The ~100 collections/tenant fan-out guideline is bench-grounded:\n * `admin usage` costs ≈ N × (1 LIST + up to 120 GETs per collection)\n * — strictly linear. See `docs/spec/attachments/collection-fanout-baseline.json`\n * (`pnpm bench:collection-fanout`). Neither the ~100 figure nor the\n * >10 GB/tenant storage line is a code constant here; both are cost\n * signals documented in `docs/about/cost-model.md`.\n *\n * Distinct from `baerly cost` (the per-table, $/month projection):\n * `cost` is a developer-facing trajectory for one table, `usage` is an\n * operator-facing M-size graduation health check across all\n * collections.\n *\n * The pure-storage half — {@link estimateWritesPerMin},\n * {@link discoverCollections}, {@link runUsageScan} — takes a\n * `Storage` handle from the caller and never reads `process.env`.\n * The CLI wrapper at the bottom of the file constructs that\n * `Storage` from `--bucket=<uri>` via `parseBucketUri`. The\n * Cloudflare target short-circuits with an info-level \"not yet\n * wired\" finding pending the follow-up work in\n * `docs/followups/agent-friendliness.md` entry 10.\n *\n * Why GET each entry instead of relying on list-time\n * `Last-Modified`: `MemoryStorage` (the test backend) intentionally\n * does NOT surface `lastModified` on `list()`, and the\n * cross-backend story stays uniform if we always read `commit_ts`\n * from the `LogEntry` body. Sample size is bounded (`SAMPLE_SIZE`\n * GETs per collection), so the cost is acceptable for an opt-in\n * operator command.\n *\n * @see docs/about/thesis.md — M-size ceiling rationale.\n * @see docs/spec/log-entry-shape.md — `LogEntry.commit_ts` contract.\n * @see packages/server/src/compactor.ts:224-225 — `collectionPrefix` /\n * `collectionName` derivation pattern reused here.\n */\n\nimport { type ArgsDef } from \"citty\";\nimport { BaerlyError, decodeJsonBytes, type LogEntry, type Storage } from \"@baerly/protocol\";\nimport { parseBucketUri } from \"../bucket-uri.ts\";\nimport { loadAppConfig } from \"../config.ts\";\nimport { emitSuccess, isJsonMode } from \"../output.ts\";\nimport { APP_ARG, defineBaerlySubcommand, JSON_ARG, TENANT_ARG } from \"../subcommand.ts\";\n\n/**\n * Verdict-shaped finding the scan emits. Mirrors the\n * `severity / check / message / fix?` shape that `baerly doctor` uses,\n * but doesn't depend on `doctor/cloudflare.ts` — `admin usage` runs\n * outside the doctor surface.\n */\nexport interface UsageFinding {\n readonly severity: \"ok\" | \"info\" | \"warning\" | \"error\";\n readonly check: string;\n readonly message: string;\n readonly fix?: string;\n}\n\n/**\n * M-size writes-per-minute-per-collection ceiling from\n * `docs/about/thesis.md`. Crossing this with sustained traffic\n * means operators should consider graduating the workload to a\n * graduated store via `baerly export --target=postgres|sqlite|d1`.\n */\nexport const M_SIZE_WRITES_PER_MIN_PER_COLLECTION = 30;\n\n/** Number of trailing log entries the estimator reads per collection. */\nexport const SAMPLE_SIZE = 120;\n\n/** Per-collection verdict surfaced by {@link estimateWritesPerMin}. */\nexport interface UsageVerdict {\n /** Collection name (matches `LogEntry.collection`). */\n readonly collection: string;\n /**\n * Writes per minute estimated over the sample window. `NaN` when\n * fewer than 2 entries were observed (no defensible rate).\n */\n readonly writesPerMin: number;\n /** Percent of {@link M_SIZE_WRITES_PER_MIN_PER_COLLECTION}; `NaN` propagates. */\n readonly percentOfCeiling: number;\n /**\n * Severity scaled by distance to ceiling:\n * - `< 50%` → `\"info\"`\n * - `50–99%` → `\"warning\"` (\"approaching ceiling\")\n * - `≥ 100%` → `\"warning\"` (\"exceeds ceiling — consider export\")\n *\n * Severity `warning` never bumps the doctor's exit code above 0\n * (operators can still deploy / continue while approaching the\n * ceiling).\n */\n readonly severity: \"info\" | \"warning\";\n /** Human-readable one-liner suitable for a {@link UsageFinding}. */\n readonly message: string;\n /** Empty when no remediation is meaningful (under 50%). */\n readonly fix: string;\n}\n\n/** Build the canonical `current.json` key for one collection. */\nexport const currentJsonKeyFor = (app: string, tenant: string, collection: string): string =>\n `app/${app}/tenant/${tenant}/manifests/${collection}/current.json`;\n\n/** Derive the `collectionPrefix` (everything before `/current.json`). */\nexport const collectionPrefixOf = (currentJsonKey: string): string =>\n currentJsonKey.slice(0, currentJsonKey.lastIndexOf(\"/\"));\n\n/**\n * List every log key under `${collectionPrefix}/log/` for one collection.\n * Returns the keys in **chronological order** (oldest seq first).\n *\n * The on-bucket key shape is `<collectionPrefix>/log/<seq>.json` where\n * `<seq>` is a base-10 integer minted by `Writer`. Lex-ascending\n * key order disagrees with numeric seq order past seq=9 (`log/10.json`\n * sorts before `log/2.json`), so we parse the trailing integer out of\n * each key and sort numerically.\n *\n * Caller is expected to slice the trailing N entries — the writes/min\n * estimator only needs the most recent sample.\n */\n// Parse the `<seq>` integer from a `<logPrefix>/<seq>.json` key. Returns\n// `NaN` when the basename isn't a finite integer (the caller filters\n// those out before sorting). Hoisted out of {@link listLogKeysSortedBySeq}\n// so a function instance isn't allocated per list entry.\nconst seqOfLogKey = (key: string): number => {\n const slash = key.lastIndexOf(\"/\");\n const dot = key.lastIndexOf(\".json\");\n if (slash === -1 || dot === -1 || dot <= slash) {\n return Number.NaN;\n }\n const seqStr = key.slice(slash + 1, dot);\n const n = Number.parseInt(seqStr, 10);\n return Number.isFinite(n) ? n : Number.NaN;\n};\n\nconst listLogKeysSortedBySeq = async (\n storage: Storage,\n logPrefix: string,\n): Promise<readonly string[]> => {\n const keys: string[] = [];\n for await (const entry of storage.list(logPrefix)) {\n keys.push(entry.key);\n }\n return keys\n .filter((k) => Number.isFinite(seqOfLogKey(k)))\n .toSorted((a, b) => seqOfLogKey(a) - seqOfLogKey(b));\n};\n\n/**\n * Fetch a `LogEntry` body at `key`, returning its `commit_ts` parsed\n * to epoch-ms. Returns `null` when the object is missing (a peer may\n * have GC'd it between list and get); throws `BaerlyError` on a\n * malformed body so the caller can downgrade the whole collection's\n * scan to an error-level finding.\n */\nconst readCommitTsMs = async (storage: Storage, key: string): Promise<number | null> => {\n const got = await storage.get(key);\n if (got === null) {\n return null;\n }\n let parsed: LogEntry;\n try {\n parsed = decodeJsonBytes<LogEntry>(got.body);\n } catch (error) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `usage scan: log entry at ${key} is not valid JSON`,\n error,\n );\n }\n if (typeof parsed.commit_ts !== \"string\") {\n throw new BaerlyError(\"InvalidResponse\", `usage scan: log entry at ${key} missing commit_ts`);\n }\n const ms = Date.parse(parsed.commit_ts);\n if (!Number.isFinite(ms)) {\n throw new BaerlyError(\n \"InvalidResponse\",\n `usage scan: log entry at ${key} has unparseable commit_ts ${JSON.stringify(parsed.commit_ts)}`,\n );\n }\n return ms;\n};\n\n/**\n * Read each key with bounded concurrency. Mirrors the pattern in\n * `packages/server/src/log-walk.ts` — we cap parallelism to keep a\n * single doctor pass from blowing through the storage backend's\n * connection budget. Keeps a small constant rather than reaching for\n * `MAX_PARALLEL_LOG_READS` (8) so the doctor command is gentle by\n * default.\n */\nconst PARALLEL_READS = 8;\n\nconst readCommitTsBatched = async (\n storage: Storage,\n keys: readonly string[],\n): Promise<readonly (number | null)[]> => {\n const out: (number | null)[] = Array.from({ length: keys.length });\n for (let i = 0; i < keys.length; i += PARALLEL_READS) {\n const chunk = keys.slice(i, i + PARALLEL_READS);\n const results = await Promise.all(chunk.map((k) => readCommitTsMs(storage, k)));\n for (let j = 0; j < results.length; j++) {\n out[i + j] = results[j] ?? null;\n }\n }\n return out;\n};\n\n/**\n * Estimate writes/min for one collection.\n *\n * Reads the last `sampleSize` log entries (default `SAMPLE_SIZE`)\n * for `<app>/<tenant>/<collection>`, computes\n * `(observedEntries - 1) / ((maxTs - minTs) / 60_000)`\n * minutes, compares against {@link M_SIZE_WRITES_PER_MIN_PER_COLLECTION},\n * and returns a {@link UsageVerdict}.\n *\n * Edge cases:\n * - Fewer than 2 entries observable → `writesPerMin = NaN`,\n * severity `info`, no fix. Operators see \"not enough log\n * entries to estimate.\"\n * - All entries share the same `commit_ts` (e.g. a tight batch) →\n * the denominator is clamped to 1 second so the rate degrades\n * gracefully instead of dividing by zero.\n *\n * @throws BaerlyError code=\"NetworkError\" — wrapped storage failure\n * while listing. The caller (Node doctor backend) catches and\n * converts to a warning-severity finding so one bad collection\n * doesn't fail the whole scan.\n * @throws BaerlyError code=\"InvalidResponse\" — a sampled log entry\n * body is malformed; same caller treatment.\n * @param opts.keyPrefix - When the bucket has a non-empty key prefix\n * (e.g. `s3://my-bucket/some/prefix`), pass it here (ending in\n * `/`). Defaults to `\"\"`. Necessary for prefixed-bucket\n * correctness; ignored by `runUsageScan` (Node doctor scans the\n * root). Threaded through by `baerly inspect`.\n */\nexport const estimateWritesPerMin = async (\n storage: Storage,\n app: string,\n tenant: string,\n collection: string,\n opts: { readonly sampleSize?: number; readonly keyPrefix?: string } = {},\n): Promise<UsageVerdict> => {\n const sampleSize = opts.sampleSize ?? SAMPLE_SIZE;\n const keyPrefix = opts.keyPrefix ?? \"\";\n const collectionPrefix = `${keyPrefix}${collectionPrefixOf(currentJsonKeyFor(app, tenant, collection))}`;\n const logPrefix = `${collectionPrefix}/log/`;\n\n let allKeys: readonly string[];\n try {\n allKeys = await listLogKeysSortedBySeq(storage, logPrefix);\n } catch (error) {\n if (error instanceof BaerlyError) {\n throw error;\n }\n throw new BaerlyError(\n \"NetworkError\",\n `usage scan: list ${logPrefix} failed: ${(error as Error).message}`,\n error,\n );\n }\n const sample = allKeys.slice(Math.max(0, allKeys.length - sampleSize));\n if (sample.length < 2) {\n return {\n collection,\n writesPerMin: Number.NaN,\n percentOfCeiling: Number.NaN,\n severity: \"info\",\n message: `collection ${collection}: not enough log entries to estimate (saw ${sample.length}, need >= 2)`,\n fix: \"\",\n };\n }\n const commitTs = await readCommitTsBatched(storage, sample);\n const timestamps = commitTs.filter((v): v is number => v !== null);\n if (timestamps.length < 2) {\n return {\n collection,\n writesPerMin: Number.NaN,\n percentOfCeiling: Number.NaN,\n severity: \"info\",\n message: `collection ${collection}: not enough readable log entries to estimate (resolved ${timestamps.length}, need >= 2)`,\n fix: \"\",\n };\n }\n let minTs = timestamps[0]!;\n let maxTs = timestamps[0]!;\n for (const t of timestamps) {\n if (t < minTs) {\n minTs = t;\n }\n if (t > maxTs) {\n maxTs = t;\n }\n }\n // Guard the denominator: a tight batch may produce identical\n // commit_ts values; degrade to a one-second window so we never\n // divide by zero.\n const minutes = Math.max(1 / 60, (maxTs - minTs) / 60_000);\n const writesPerMin = (timestamps.length - 1) / minutes;\n const pct = (writesPerMin / M_SIZE_WRITES_PER_MIN_PER_COLLECTION) * 100;\n\n let severity: \"info\" | \"warning\" = \"info\";\n let message = `collection ${collection}: ${writesPerMin.toFixed(1)} writes/min (~${pct.toFixed(0)}% of M-size ceiling, sampled ${timestamps.length} entries)`;\n let fix = \"\";\n if (pct >= 100) {\n severity = \"warning\";\n message += \" — exceeds the M-size ceiling.\";\n fix = `consider graduating: \\`baerly export --target=postgres|sqlite|d1 --bucket=<bucket> --app=${app} --tenant=${tenant} --collection=${collection}\\``;\n } else if (pct >= 50) {\n severity = \"warning\";\n message += \" — approaching the M-size ceiling.\";\n fix = \"monitor; plan graduation via `baerly export --target=postgres|sqlite|d1`\";\n }\n return { collection, writesPerMin, percentOfCeiling: pct, severity, message, fix };\n};\n\n/**\n * Discover the set of collections under `<app>/<tenant>/manifests/`\n * by listing the bucket. Each collection is the immediate\n * subdirectory name (the segment after `manifests/` and before the\n * next `/`).\n *\n * Returns a deduped, lex-sorted list. An empty list means there are\n * no committed collections under this app/tenant yet — the caller\n * surfaces a single info finding rather than scanning per-collection.\n *\n * @throws BaerlyError code=\"NetworkError\" — wrapped list failure.\n */\nexport const discoverCollections = async (\n storage: Storage,\n app: string,\n tenant: string,\n): Promise<readonly string[]> => {\n const prefix = `app/${app}/tenant/${tenant}/manifests/`;\n const names = new Set<string>();\n try {\n for await (const entry of storage.list(prefix)) {\n const rest = entry.key.slice(prefix.length);\n const slash = rest.indexOf(\"/\");\n const name = slash === -1 ? rest : rest.slice(0, slash);\n if (name.length > 0) {\n names.add(name);\n }\n }\n } catch (error) {\n if (error instanceof BaerlyError) {\n throw error;\n }\n throw new BaerlyError(\n \"NetworkError\",\n `usage scan: list ${prefix} failed: ${(error as Error).message}`,\n error,\n );\n }\n return [...names].toSorted();\n};\n\n/**\n * Orchestrate the usage scan against a caller-supplied\n * {@link Storage}. The CLI wrapper handles bucket-URI construction;\n * this helper runs the shared discover → per-collection-estimate →\n * finding-push loop.\n *\n * Mutates `findings` in place. Returns when the scan completes\n * (success or per-collection failure all surface as findings). The\n * outer CLI exit code is driven by the rollup over all findings.\n *\n * Errors land as warnings (not errors) so one bad collection doesn't\n * abort the whole scan and so the operator stays deployable while a\n * single object is being investigated.\n */\nexport const runUsageScan = async (\n context: { readonly app: string; readonly tenant: string },\n storage: Storage,\n findings: UsageFinding[],\n): Promise<void> => {\n let collections: readonly string[];\n try {\n collections = await discoverCollections(storage, context.app, context.tenant);\n } catch (error) {\n findings.push({\n severity: \"warning\",\n check: \"usage-discover\",\n message: `could not enumerate collections under app/${context.app}/tenant/${context.tenant}/manifests/: ${error instanceof BaerlyError ? error.message : (error as Error).message}`,\n });\n return;\n }\n if (collections.length === 0) {\n findings.push({\n severity: \"info\",\n check: \"usage-empty\",\n message: `no collections found under app/${context.app}/tenant/${context.tenant}/manifests/; nothing to scan.`,\n });\n return;\n }\n for (const c of collections) {\n try {\n const verdict = await estimateWritesPerMin(storage, context.app, context.tenant, c);\n findings.push({\n severity: verdict.severity,\n check: `usage-${c}`,\n message: verdict.message,\n ...(verdict.fix !== \"\" && { fix: verdict.fix }),\n });\n } catch (error) {\n findings.push({\n severity: \"warning\",\n check: `usage-${c}`,\n message: `failed to estimate writes/min for ${c}: ${error instanceof BaerlyError ? error.message : (error as Error).message}`,\n });\n }\n }\n};\n\n// ---------------------------------------------------------------------------\n// CLI surface — `baerly admin usage`\n// ---------------------------------------------------------------------------\n\nconst USAGE_ARGS = {\n bucket: {\n type: \"string\",\n required: false,\n description:\n \"Bucket URI (s3://<bucket>[/<prefix>], file:///<abs>, memory://<bucket>). Required for --target=node.\",\n valueHint: \"bucket-uri\",\n },\n target: {\n type: \"string\",\n required: false,\n description: 'Override `baerly.config.ts:target`. One of \"cloudflare\" | \"node\".',\n valueHint: \"target\",\n },\n app: APP_ARG,\n tenant: TENANT_ARG,\n json: JSON_ARG,\n} as const satisfies ArgsDef;\n\nconst SEVERITY_GLYPH: Record<UsageFinding[\"severity\"], string> = {\n ok: \"✓\",\n info: \"•\",\n warning: \"⚠\",\n error: \"✗\",\n};\n\nconst renderText = (target: string, findings: readonly UsageFinding[]): string => {\n const lines: string[] = [];\n lines.push(`baerly admin usage --target=${target}`);\n lines.push(\"\");\n for (const f of findings) {\n lines.push(` ${SEVERITY_GLYPH[f.severity]} ${f.message}`);\n if (f.fix !== undefined && f.fix !== \"\") {\n lines.push(` fix: ${f.fix}`);\n }\n }\n let warnings = 0;\n let errors = 0;\n for (const f of findings) {\n if (f.severity === \"warning\") {\n warnings++;\n } else if (f.severity === \"error\") {\n errors++;\n }\n }\n lines.push(\"\");\n lines.push(\n `Status: ${errors} error${errors === 1 ? \"\" : \"s\"}, ${warnings} warning${warnings === 1 ? \"\" : \"s\"}.`,\n );\n return lines.join(\"\\n\") + \"\\n\";\n};\n\nconst bundle = defineBaerlySubcommand({\n name: \"admin.usage\",\n meta: {\n description:\n \"All-collection writes/min health check; flags collections approaching the M-size ceiling.\",\n },\n args: USAGE_ARGS,\n handler: async (args, ctx) => {\n // Avoid loading the config when --target is explicit — the CLI\n // should still work outside an app directory if the operator\n // pins target + app + tenant on the flags.\n const target = args.target ?? (await loadAppConfig().then((c) => c.target));\n if (target !== \"cloudflare\" && target !== \"node\") {\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly admin usage: unsupported --target ${JSON.stringify(target)} (one of \"cloudflare\" | \"node\")`,\n );\n }\n const { app, tenant } = await ctx.resolveAppTenant({ app: args.app, tenant: args.tenant });\n\n const findings: UsageFinding[] = [];\n\n if (target === \"cloudflare\") {\n // The CLI runs in Node and can't reach a Workerd-side R2 binding\n // from `--bucket=<uri>`; full CF wiring is a follow-up — see\n // `docs/followups/agent-friendliness.md` entry 10.\n findings.push({\n severity: \"info\",\n check: \"usage.cloudflare\",\n message:\n \"baerly admin usage is not yet wired for --target=cloudflare. See docs/followups/agent-friendliness.md entry 10.\",\n });\n } else {\n if (args.bucket === undefined || args.bucket.length === 0) {\n throw new BaerlyError(\n \"InvalidConfig\",\n \"baerly admin usage: --bucket=<uri> is required for --target=node\",\n );\n }\n const parsed = await parseBucketUri(args.bucket);\n await runUsageScan({ app, tenant }, parsed.storage, findings);\n }\n\n if (isJsonMode()) {\n emitSuccess({\n command: \"admin.usage\",\n status: \"ok\",\n target,\n findings: findings.map((f) => ({\n severity: f.severity,\n check: f.check,\n message: f.message,\n ...(f.fix !== undefined && f.fix !== \"\" && { fix: f.fix }),\n })),\n });\n } else {\n process.stdout.write(renderText(target, findings));\n }\n return 0;\n },\n});\n\n/** citty `defineCommand` block for `baerly admin usage`. */\nexport const usageCmd = bundle.cmd;\n\n/**\n * Programmatic entry used by tests. Bypasses citty's `run` wrapper\n * (which would call `process.exit` and kill vitest) and returns the\n * integer exit code directly.\n */\nexport const runUsage = bundle.run;\n"],"mappings":";;;;;AA0GA,MAAa,qBAAqB,KAAa,QAAgB,eAC7D,OAAO,IAAI,UAAU,OAAO,aAAa,WAAW;;AAGtD,MAAa,sBAAsB,mBACjC,eAAe,MAAM,GAAG,eAAe,YAAY,GAAG,CAAC;;;;;;;;;;;;;;AAmBzD,MAAM,eAAe,QAAwB;CAC3C,MAAM,QAAQ,IAAI,YAAY,GAAG;CACjC,MAAM,MAAM,IAAI,YAAY,OAAO;CACnC,IAAI,UAAU,MAAM,QAAQ,MAAM,OAAO,OACvC,OAAO;CAET,MAAM,SAAS,IAAI,MAAM,QAAQ,GAAG,GAAG;CACvC,MAAM,IAAI,OAAO,SAAS,QAAQ,EAAE;CACpC,OAAO,OAAO,SAAS,CAAC,IAAI,IAAI;AAClC;AAEA,MAAM,yBAAyB,OAC7B,SACA,cAC+B;CAC/B,MAAM,OAAiB,CAAC;CACxB,WAAW,MAAM,SAAS,QAAQ,KAAK,SAAS,GAC9C,KAAK,KAAK,MAAM,GAAG;CAErB,OAAO,KACJ,QAAQ,MAAM,OAAO,SAAS,YAAY,CAAC,CAAC,CAAC,CAAC,CAC9C,UAAU,GAAG,MAAM,YAAY,CAAC,IAAI,YAAY,CAAC,CAAC;AACvD;;;;;;;;AASA,MAAM,iBAAiB,OAAO,SAAkB,QAAwC;CACtF,MAAM,MAAM,MAAM,QAAQ,IAAI,GAAG;CACjC,IAAI,QAAQ,MACV,OAAO;CAET,IAAI;CACJ,IAAI;EACF,SAAS,gBAA0B,IAAI,IAAI;CAC7C,SAAS,OAAO;EACd,MAAM,IAAI,YACR,mBACA,4BAA4B,IAAI,qBAChC,KACF;CACF;CACA,IAAI,OAAO,OAAO,cAAc,UAC9B,MAAM,IAAI,YAAY,mBAAmB,4BAA4B,IAAI,mBAAmB;CAE9F,MAAM,KAAK,KAAK,MAAM,OAAO,SAAS;CACtC,IAAI,CAAC,OAAO,SAAS,EAAE,GACrB,MAAM,IAAI,YACR,mBACA,4BAA4B,IAAI,6BAA6B,KAAK,UAAU,OAAO,SAAS,GAC9F;CAEF,OAAO;AACT;;;;;;;;;AAUA,MAAM,iBAAiB;AAEvB,MAAM,sBAAsB,OAC1B,SACA,SACwC;CACxC,MAAM,MAAyB,MAAM,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC;CACjE,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK,gBAAgB;EACpD,MAAM,QAAQ,KAAK,MAAM,GAAG,IAAI,cAAc;EAC9C,MAAM,UAAU,MAAM,QAAQ,IAAI,MAAM,KAAK,MAAM,eAAe,SAAS,CAAC,CAAC,CAAC;EAC9E,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAClC,IAAI,IAAI,KAAK,QAAQ,MAAM;CAE/B;CACA,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,MAAa,uBAAuB,OAClC,SACA,KACA,QACA,YACA,OAAsE,CAAC,MAC7C;CAC1B,MAAM,aAAa,KAAK,cAAA;CAGxB,MAAM,YAAY,GAAG,GAFH,KAAK,aAAa,KACI,mBAAmB,kBAAkB,KAAK,QAAQ,UAAU,CAAC,IAC/D;CAEtC,IAAI;CACJ,IAAI;EACF,UAAU,MAAM,uBAAuB,SAAS,SAAS;CAC3D,SAAS,OAAO;EACd,IAAI,iBAAiB,aACnB,MAAM;EAER,MAAM,IAAI,YACR,gBACA,oBAAoB,UAAU,WAAY,MAAgB,WAC1D,KACF;CACF;CACA,MAAM,SAAS,QAAQ,MAAM,KAAK,IAAI,GAAG,QAAQ,SAAS,UAAU,CAAC;CACrE,IAAI,OAAO,SAAS,GAClB,OAAO;EACL;EACA,cAAc;EACd,kBAAkB;EAClB,UAAU;EACV,SAAS,cAAc,WAAW,4CAA4C,OAAO,OAAO;EAC5F,KAAK;CACP;CAGF,MAAM,cAAa,MADI,oBAAoB,SAAS,MAAM,EAAA,CAC9B,QAAQ,MAAmB,MAAM,IAAI;CACjE,IAAI,WAAW,SAAS,GACtB,OAAO;EACL;EACA,cAAc;EACd,kBAAkB;EAClB,UAAU;EACV,SAAS,cAAc,WAAW,0DAA0D,WAAW,OAAO;EAC9G,KAAK;CACP;CAEF,IAAI,QAAQ,WAAW;CACvB,IAAI,QAAQ,WAAW;CACvB,KAAK,MAAM,KAAK,YAAY;EAC1B,IAAI,IAAI,OACN,QAAQ;EAEV,IAAI,IAAI,OACN,QAAQ;CAEZ;CAIA,MAAM,UAAU,KAAK,IAAI,IAAI,KAAK,QAAQ,SAAS,GAAM;CACzD,MAAM,gBAAgB,WAAW,SAAS,KAAK;CAC/C,MAAM,MAAO,eAAA,KAAuD;CAEpE,IAAI,WAA+B;CACnC,IAAI,UAAU,cAAc,WAAW,IAAI,aAAa,QAAQ,CAAC,EAAE,gBAAgB,IAAI,QAAQ,CAAC,EAAE,+BAA+B,WAAW,OAAO;CACnJ,IAAI,MAAM;CACV,IAAI,OAAO,KAAK;EACd,WAAW;EACX,WAAW;EACX,MAAM,4FAA4F,IAAI,YAAY,OAAO,gBAAgB,WAAW;CACtJ,OAAO,IAAI,OAAO,IAAI;EACpB,WAAW;EACX,WAAW;EACX,MAAM;CACR;CACA,OAAO;EAAE;EAAY;EAAc,kBAAkB;EAAK;EAAU;EAAS;CAAI;AACnF;;;;;;;;;;;;;AAcA,MAAa,sBAAsB,OACjC,SACA,KACA,WAC+B;CAC/B,MAAM,SAAS,OAAO,IAAI,UAAU,OAAO;CAC3C,MAAM,wBAAQ,IAAI,IAAY;CAC9B,IAAI;EACF,WAAW,MAAM,SAAS,QAAQ,KAAK,MAAM,GAAG;GAC9C,MAAM,OAAO,MAAM,IAAI,MAAM,OAAO,MAAM;GAC1C,MAAM,QAAQ,KAAK,QAAQ,GAAG;GAC9B,MAAM,OAAO,UAAU,KAAK,OAAO,KAAK,MAAM,GAAG,KAAK;GACtD,IAAI,KAAK,SAAS,GAChB,MAAM,IAAI,IAAI;EAElB;CACF,SAAS,OAAO;EACd,IAAI,iBAAiB,aACnB,MAAM;EAER,MAAM,IAAI,YACR,gBACA,oBAAoB,OAAO,WAAY,MAAgB,WACvD,KACF;CACF;CACA,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,SAAS;AAC7B;;;;;;;;;;;;;;;AAgBA,MAAa,eAAe,OAC1B,SACA,SACA,aACkB;CAClB,IAAI;CACJ,IAAI;EACF,cAAc,MAAM,oBAAoB,SAAS,QAAQ,KAAK,QAAQ,MAAM;CAC9E,SAAS,OAAO;EACd,SAAS,KAAK;GACZ,UAAU;GACV,OAAO;GACP,SAAS,6CAA6C,QAAQ,IAAI,UAAU,QAAQ,OAAO,eAAe,iBAAiB,cAAc,MAAM,UAAW,MAAgB;EAC5K,CAAC;EACD;CACF;CACA,IAAI,YAAY,WAAW,GAAG;EAC5B,SAAS,KAAK;GACZ,UAAU;GACV,OAAO;GACP,SAAS,kCAAkC,QAAQ,IAAI,UAAU,QAAQ,OAAO;EAClF,CAAC;EACD;CACF;CACA,KAAK,MAAM,KAAK,aACd,IAAI;EACF,MAAM,UAAU,MAAM,qBAAqB,SAAS,QAAQ,KAAK,QAAQ,QAAQ,CAAC;EAClF,SAAS,KAAK;GACZ,UAAU,QAAQ;GAClB,OAAO,SAAS;GAChB,SAAS,QAAQ;GACjB,GAAI,QAAQ,QAAQ,MAAM,EAAE,KAAK,QAAQ,IAAI;EAC/C,CAAC;CACH,SAAS,OAAO;EACd,SAAS,KAAK;GACZ,UAAU;GACV,OAAO,SAAS;GAChB,SAAS,qCAAqC,EAAE,IAAI,iBAAiB,cAAc,MAAM,UAAW,MAAgB;EACtH,CAAC;CACH;AAEJ;AAMA,MAAM,aAAa;CACjB,QAAQ;EACN,MAAM;EACN,UAAU;EACV,aACE;EACF,WAAW;CACb;CACA,QAAQ;EACN,MAAM;EACN,UAAU;EACV,aAAa;EACb,WAAW;CACb;CACA,KAAK;CACL,QAAQ;CACR,MAAM;AACR;AAEA,MAAM,iBAA2D;CAC/D,IAAI;CACJ,MAAM;CACN,SAAS;CACT,OAAO;AACT;AAEA,MAAM,cAAc,QAAgB,aAA8C;CAChF,MAAM,QAAkB,CAAC;CACzB,MAAM,KAAK,+BAA+B,QAAQ;CAClD,MAAM,KAAK,EAAE;CACb,KAAK,MAAM,KAAK,UAAU;EACxB,MAAM,KAAK,KAAK,eAAe,EAAE,UAAU,GAAG,EAAE,SAAS;EACzD,IAAI,EAAE,QAAQ,KAAA,KAAa,EAAE,QAAQ,IACnC,MAAM,KAAK,aAAa,EAAE,KAAK;CAEnC;CACA,IAAI,WAAW;CACf,IAAI,SAAS;CACb,KAAK,MAAM,KAAK,UACd,IAAI,EAAE,aAAa,WACjB;MACK,IAAI,EAAE,aAAa,SACxB;CAGJ,MAAM,KAAK,EAAE;CACb,MAAM,KACJ,WAAW,OAAO,QAAQ,WAAW,IAAI,KAAK,IAAI,IAAI,SAAS,UAAU,aAAa,IAAI,KAAK,IAAI,EACrG;CACA,OAAO,MAAM,KAAK,IAAI,IAAI;AAC5B;AAEA,MAAM,SAAS,uBAAuB;CACpC,MAAM;CACN,MAAM,EACJ,aACE,4FACJ;CACA,MAAM;CACN,SAAS,OAAO,MAAM,QAAQ;EAI5B,MAAM,SAAS,KAAK,UAAW,MAAM,cAAc,CAAC,CAAC,MAAM,MAAM,EAAE,MAAM;EACzE,IAAI,WAAW,gBAAgB,WAAW,QACxC,MAAM,IAAI,YACR,iBACA,4CAA4C,KAAK,UAAU,MAAM,EAAE,gCACrE;EAEF,MAAM,EAAE,KAAK,WAAW,MAAM,IAAI,iBAAiB;GAAE,KAAK,KAAK;GAAK,QAAQ,KAAK;EAAO,CAAC;EAEzF,MAAM,WAA2B,CAAC;EAElC,IAAI,WAAW,cAIb,SAAS,KAAK;GACZ,UAAU;GACV,OAAO;GACP,SACE;EACJ,CAAC;OACI;GACL,IAAI,KAAK,WAAW,KAAA,KAAa,KAAK,OAAO,WAAW,GACtD,MAAM,IAAI,YACR,iBACA,kEACF;GAEF,MAAM,SAAS,MAAM,eAAe,KAAK,MAAM;GAC/C,MAAM,aAAa;IAAE;IAAK;GAAO,GAAG,OAAO,SAAS,QAAQ;EAC9D;EAEA,IAAI,WAAW,GACb,YAAY;GACV,SAAS;GACT,QAAQ;GACR;GACA,UAAU,SAAS,KAAK,OAAO;IAC7B,UAAU,EAAE;IACZ,OAAO,EAAE;IACT,SAAS,EAAE;IACX,GAAI,EAAE,QAAQ,KAAA,KAAa,EAAE,QAAQ,MAAM,EAAE,KAAK,EAAE,IAAI;GAC1D,EAAE;EACJ,CAAC;OAED,QAAQ,OAAO,MAAM,WAAW,QAAQ,QAAQ,CAAC;EAEnD,OAAO;CACT;AACF,CAAC;;AAGD,MAAa,WAAW,OAAO;AAOP,OAAO"}