@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
@@ -0,0 +1,812 @@
1
+ import { i as isWriteConflict, t as BaerlyError } from "./errors-7Rk1HGCE.js";
2
+ import { f as mintGeneration, l as createCurrentJson, t as assertNameSegment } from "./path-segment-DBXG26PW.js";
3
+ import { t as assertValidStorageKey } from "./key-C4FPZ9Io.js";
4
+ import { dirname, join, resolve, sep } from "node:path";
5
+ import { createHash } from "node:crypto";
6
+ import { link, mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
7
+ import { styleText } from "node:util";
8
+ // packages/dev/src/key-lock.ts
9
+ /**
10
+ * Live locks, keyed by caller-supplied string.
11
+ *
12
+ * Module-level rather than per-owner on purpose. `LocalFsStorage` is
13
+ * constructed freely — `localFsStorage()` mints a fresh instance on every
14
+ * call over the same default root, and the randomized cascade builds N
15
+ * instances over one directory specifically to make them contend — so a
16
+ * lock map hanging off the instance would serialize nothing in exactly the
17
+ * cases that need it. Callers key on the resolved root plus the storage
18
+ * key, which is the real identity of the thing being mutated.
19
+ */
20
+ const locks = /* @__PURE__ */ new Map();
21
+ /**
22
+ * Run `fn` with exclusive access to `lockKey`, in FIFO order among
23
+ * contenders. Concurrent calls on *different* keys are unaffected.
24
+ *
25
+ * A rejecting `fn` releases the lock like any other completion and the
26
+ * rejection propagates to its own caller only — one failed critical
27
+ * section must not wedge the key or poison the next holder.
28
+ *
29
+ * Scope: one loaded copy of this module, since `locks` is module-level.
30
+ * That is one process in every normal setup. It says nothing about other
31
+ * processes, which need a lock file, a lease, or server-side CAS.
32
+ *
33
+ * `fn` must not itself call `withKeyLock` on the same key — the inner
34
+ * call would wait on the outer call's release and self-deadlock. Nothing
35
+ * in this package does; only one lock is ever held at a time, so there is
36
+ * no lock-ordering cycle either.
37
+ */
38
+ const withKeyLock = async (lockKey, fn) => {
39
+ const lock = locks.getOrInsertComputed(lockKey, () => ({
40
+ tail: Promise.resolve(),
41
+ waiters: 0
42
+ }));
43
+ lock.waiters += 1;
44
+ const predecessor = lock.tail;
45
+ let release;
46
+ lock.tail = new Promise((resolve) => {
47
+ release = resolve;
48
+ });
49
+ await predecessor;
50
+ try {
51
+ return await fn();
52
+ } finally {
53
+ release();
54
+ lock.waiters -= 1;
55
+ if (lock.waiters === 0 && locks.get(lockKey) === lock) locks.delete(lockKey);
56
+ }
57
+ };
58
+ /** Longest component that still fits {@link CONTINUATION} under `NAME_MAX`. */
59
+ const MAX_PART_BYTES = 254;
60
+ const utf8Encoder$1 = new TextEncoder();
61
+ const utf8Decoder = new TextDecoder("utf-8", {
62
+ fatal: true,
63
+ ignoreBOM: true
64
+ });
65
+ /** Bytes that stay literal: `-` `.` `0-9` `_` `a-z`. `.` is special-cased. */
66
+ const isLiteralByte = (b) => b >= 97 && b <= 122 || b >= 48 && b <= 57 || b === 45 || b === 95 || b === 46;
67
+ const DOT = 46;
68
+ const escapeByte = (b) => `%${b.toString(16).padStart(2, "0")}`;
69
+ /** Tokens of one encoded segment: a literal char or a `%xx` triplet. */
70
+ const tokenize = (segment) => {
71
+ const tokens = [];
72
+ for (const b of utf8Encoder$1.encode(segment)) tokens.push(isLiteralByte(b) ? String.fromCharCode(b) : escapeByte(b));
73
+ return tokens;
74
+ };
75
+ /**
76
+ * Pack tokens into on-disk components. A component never starts with a
77
+ * literal `.`: such a token is written as `%2e` instead.
78
+ */
79
+ const pack = (tokens, limit) => {
80
+ const parts = [];
81
+ let current = "";
82
+ for (let token of tokens) {
83
+ if (current.length + token.length > limit) {
84
+ parts.push(current);
85
+ current = "";
86
+ }
87
+ if (current === "" && token === ".") token = escapeByte(DOT);
88
+ current += token;
89
+ }
90
+ parts.push(current);
91
+ return parts;
92
+ };
93
+ /** Encode one non-empty `/`-segment into its on-disk component(s). */
94
+ const encodeSegment = (segment) => {
95
+ const tokens = tokenize(segment);
96
+ const single = pack(tokens, Number.POSITIVE_INFINITY);
97
+ if (single[0].length <= 255) return single;
98
+ const parts = pack(tokens, MAX_PART_BYTES);
99
+ return parts.map((p, i) => i < parts.length - 1 ? p + "~" : p);
100
+ };
101
+ /**
102
+ * Encode a key into on-disk path components. The caller has already
103
+ * validated the key's `/`-structure (no empty, `.`, or `..` segment).
104
+ * Rejects a key that is not well-formed UTF-16: `TextEncoder` maps every
105
+ * lone surrogate to U+FFFD, which would make the encoding non-injective.
106
+ */
107
+ const encodeKey = (key) => {
108
+ if (!key.isWellFormed()) throw new BaerlyError("InvalidConfig", `LocalFsStorage: key is not well-formed UTF-16 (lone surrogate): ${JSON.stringify(key)}`);
109
+ return key.split("/").flatMap(encodeSegment);
110
+ };
111
+ const HEX = /^[0-9a-f]{2}$/;
112
+ /** Decode one component's bytes (continuation marker already stripped). */
113
+ const decodeBytes = (component, out) => {
114
+ for (let i = 0; i < component.length; i++) {
115
+ const c = component.charCodeAt(i);
116
+ if (c === 37) {
117
+ const hex = component.slice(i + 1, i + 3);
118
+ if (!HEX.test(hex)) return false;
119
+ out.push(Number.parseInt(hex, 16));
120
+ i += 2;
121
+ } else if (isLiteralByte(c)) out.push(c);
122
+ else return false;
123
+ }
124
+ return true;
125
+ };
126
+ /**
127
+ * Decode on-disk path components (relative to the root) back to a key.
128
+ * Returns `null` for anything that is not the canonical encoding of some
129
+ * key — a foreign file, a non-canonical escape, a dangling continuation —
130
+ * so the caller can decide how loudly to fail.
131
+ */
132
+ const decodeComponents = (components) => {
133
+ const segments = [];
134
+ let bytes = [];
135
+ for (const component of components) {
136
+ const continued = component.endsWith("~");
137
+ const body = continued ? component.slice(0, -1) : component;
138
+ if (body === "" || !decodeBytes(body, bytes)) return null;
139
+ if (!continued) {
140
+ let segment;
141
+ try {
142
+ segment = utf8Decoder.decode(new Uint8Array(bytes));
143
+ } catch {
144
+ return null;
145
+ }
146
+ if (segment === "." || segment === "..") return null;
147
+ segments.push(segment);
148
+ bytes = [];
149
+ }
150
+ }
151
+ if (bytes.length > 0 || segments.length === 0) return null;
152
+ const key = segments.join("/");
153
+ let canonical;
154
+ try {
155
+ canonical = encodeKey(key);
156
+ } catch {
157
+ return null;
158
+ }
159
+ if (canonical.length !== components.length || canonical.some((c, i) => c !== components[i])) return null;
160
+ return key;
161
+ };
162
+ // packages/dev/src/local-fs.ts
163
+ /**
164
+ * Prefix for the in-directory staging temps (see `put`). Dot-prefixed, so
165
+ * it can never collide with an encoded key (see `local-fs-key-codec.ts`)
166
+ * and `walk` skips it with every other adapter-private name.
167
+ */
168
+ const TEMP_PREFIX = ".baerly-tmp-";
169
+ /**
170
+ * Root marker recording the on-disk key encoding. Dot-prefixed, so it is
171
+ * never a key. A directory without it is scanned once for names written
172
+ * by the pre-encoding layout (see `#ensureFormat`).
173
+ */
174
+ const FORMAT_MARKER = ".baerly-localfs.json";
175
+ /** Version of the key encoding in `local-fs-key-codec.ts`. */
176
+ const KEY_ENCODING = 1;
177
+ /** Legacy paths named in the refusal message before it truncates. */
178
+ const LEGACY_PATHS_SHOWN = 10;
179
+ /**
180
+ * Staging path for a two-phase (write → publish) `put`. Always a sibling
181
+ * of the destination: `rename(2)`/`link(2)` refuse to cross filesystems
182
+ * (`EXDEV`), and the bucket root is routinely on a different volume from
183
+ * `os.tmpdir()`. The leading `.` of `TEMP_PREFIX` is what makes staging
184
+ * in-bucket safe — `walk` skips dot-prefixed names at every depth, and no
185
+ * encoded key starts with one, so a crash before the publish leaves a file
186
+ * invisible to `list` rather than a bogus key.
187
+ *
188
+ * The trade-off that invisibility buys: a temp stranded by a hard crash
189
+ * now sits inside the bucket, and because every enumerator goes through
190
+ * `list`, nothing — not `runGc`, not `admin fsck` — will ever reclaim it.
191
+ * Staging in `os.tmpdir()` at least let the OS reap it. Repeated crashes
192
+ * therefore grow the data directory, and clearing that is a manual
193
+ * `find . -name '.baerly-tmp-*' -delete`. Non-crash failures are cleaned
194
+ * up by `put`'s `finally`.
195
+ */
196
+ const tempPathFor = (finalPath) => join(dirname(finalPath), `${TEMP_PREFIX}${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
197
+ const utf8Encoder = new TextEncoder();
198
+ /**
199
+ * Compare two keys by their UTF-8 byte sequences — the order S3 and R2
200
+ * use for `list`. JS's default string sort compares UTF-16 code units,
201
+ * which diverges from UTF-8 byte order for supplementary-plane
202
+ * characters; using this keeps `list` ordering faithful to the real
203
+ * adapters. (All kernel keys are ASCII base-32, where both orders
204
+ * coincide.)
205
+ */
206
+ const compareKeysUtf8 = (a, b) => {
207
+ const ba = utf8Encoder.encode(a);
208
+ const bb = utf8Encoder.encode(b);
209
+ const n = Math.min(ba.length, bb.length);
210
+ for (let i = 0; i < n; i++) if (ba[i] !== bb[i]) return ba[i] - bb[i];
211
+ return ba.length - bb.length;
212
+ };
213
+ /**
214
+ * `Storage` backed by a directory tree. Keys may contain `/` and map
215
+ * to nested directories on disk so `ls`/`cat` work as expected.
216
+ *
217
+ * Keys are byte-exact, as on S3 and R2: keys that differ only by case or
218
+ * Unicode normalization are distinct objects even on a filesystem that
219
+ * folds both (default macOS APFS). Each segment is escaped into a
220
+ * fold-invariant alphabet on disk — `A` is stored as `%41`, NFC `é` as
221
+ * `%c3%a9` — while kernel-written segments (lowercase ids, base-32 index
222
+ * values, `current.json`) are stored verbatim. See
223
+ * `local-fs-key-codec.ts`.
224
+ *
225
+ * The root carries a `.baerly-localfs.json` marker naming that encoding.
226
+ * A directory written by an older release, before keys were escaped, is
227
+ * adopted as-is when every name in it already reads the same under the
228
+ * encoding; otherwise every operation refuses with `InvalidConfig`.
229
+ * Such a directory is dev data: move it aside or delete it. Collections
230
+ * worth keeping can be dumped with the older release (`baerly admin
231
+ * dump`, rows only) and restored into a fresh directory (`baerly admin
232
+ * restore`). Data a folding filesystem has already merged is not
233
+ * recoverable.
234
+ *
235
+ * ETags are content-addressed: `"<sha-256-hex>"` (the surrounding
236
+ * double-quotes match S3's wire format for non-multipart objects).
237
+ * Identical bodies share an ETag across runs — the property that
238
+ * makes this adapter useful for fixture-based tests.
239
+ *
240
+ * Writes are atomic via `writeFile(temp) + rename(final)`; readers
241
+ * never see a partially-written file. The temp is always a sibling of
242
+ * its destination — `rename(2)`/`link(2)` fail with `EXDEV` across
243
+ * filesystems, and the bucket root is routinely on a different volume
244
+ * from `os.tmpdir()` (see `tempPathFor`).
245
+ *
246
+ * `ifNoneMatch:"*"` uses `link(2)` (atomic exclusive create; `EEXIST` ⇒
247
+ * key exists) so concurrent creates have exactly one winner. temp+`link`
248
+ * over `open(…,"wx")` keeps a partially-written new key invisible to a
249
+ * concurrent reader.
250
+ *
251
+ * `ifMatch` is a read-compare-write, so it is made atomic by serializing
252
+ * every mutation of a key against every other — see `#lockKey`.
253
+ *
254
+ * Scope of that guarantee, precisely: **one loaded copy of this module**.
255
+ * Within it, concurrent CAS on one key admits exactly one winner and the
256
+ * losers get `WriteConflict`, across any number of `LocalFsStorage` instances
257
+ * whose roots resolve — through symlinks — to the same directory. That is
258
+ * one process in every normal setup, but the lock lives in a module-level
259
+ * map, so a process that somehow loads both this source and the bundled
260
+ * copy has two of them.
261
+ *
262
+ * Across processes it guarantees nothing: two `baerly` CLI runs, or two
263
+ * servers, sharing a directory can both win, because nothing in POSIX
264
+ * makes read-compare-write atomic without a lock file or a lease. That is
265
+ * why this adapter is for single-process dev and self-hosting;
266
+ * horizontally-scaled deploys need S3 / R2, whose server-side conditional
267
+ * write is what the no-lease maintenance fold actually relies on.
268
+ *
269
+ * Node-only — imports `node:fs`, `node:path`, `node:crypto`. Lives in
270
+ * `@baerly/dev` because the protocol kernel is pure-modules / no I/O
271
+ * and must remain Worker-bundleable.
272
+ *
273
+ * ⚠️ **Hard termination and temp files.**
274
+ *
275
+ * Writes stage a sibling `.baerly-tmp-*` file before atomic rename/link.
276
+ * Normal failures clean up the temp in `finally`, but hard termination
277
+ * (`SIGKILL`, OOM, power loss) can strand a temp inside the root directory.
278
+ *
279
+ * These files are hidden from `list`, `gc`, `fsck`, and usage reporting
280
+ * by design—the temp filter applies at every depth.
281
+ *
282
+ * **Manual cleanup procedure:**
283
+ * 1. Stop all writers using the root
284
+ * 2. Run: `find <root> -name '.baerly-tmp-*' -delete`
285
+ *
286
+ * Do not clean while writes are in progress—races with in-flight PUTs
287
+ * can delete a file that a concurrent operation is about to rename.
288
+ */
289
+ var LocalFsStorage = class {
290
+ #root;
291
+ /** Memoized `realpath` of {@link #root} — see {@link #canonicalRoot}. */
292
+ #realRoot;
293
+ /** Set once the root's key encoding is known to be current. */
294
+ #formatChecked = false;
295
+ constructor(opts) {
296
+ this.#root = resolve(opts.root);
297
+ }
298
+ async get(key, opts) {
299
+ opts?.signal?.throwIfAborted();
300
+ const path = this.#pathFor(key);
301
+ await this.#ensureFormat(false);
302
+ let body;
303
+ try {
304
+ body = await readFile(path);
305
+ } catch (error) {
306
+ if (isErrnoException(error) && error.code === "ENOENT") return null;
307
+ throw new BaerlyError("InvalidResponse", `LocalFsStorage.get(${key}): ${error.message}`, { cause: error });
308
+ }
309
+ const etag = etagOf(body);
310
+ return {
311
+ body: toUint8Array(body),
312
+ etag
313
+ };
314
+ }
315
+ async put(key, body, opts) {
316
+ opts?.signal?.throwIfAborted();
317
+ const path = this.#pathFor(key);
318
+ await this.#ensureFormat(true);
319
+ await mkdir(dirname(path), { recursive: true });
320
+ return withKeyLock(await this.#lockKey(path), () => this.#putSerialized(key, path, body, opts));
321
+ }
322
+ async #putSerialized(key, path, body, opts) {
323
+ opts?.signal?.throwIfAborted();
324
+ const newEtag = etagOf(body);
325
+ if (opts?.ifNoneMatch === "*") {
326
+ const tmp = tempPathFor(path);
327
+ try {
328
+ await writeFile(tmp, body);
329
+ await link(tmp, path);
330
+ } catch (error) {
331
+ if (isErrnoException(error) && error.code === "EEXIST") throw new BaerlyError("WriteConflict", `PUT ${key}: precondition failed (ifNoneMatch="*" but key exists)`);
332
+ throw new BaerlyError("InvalidResponse", `LocalFsStorage.put(${key}): ${error.message}`, { cause: error });
333
+ } finally {
334
+ await rm(tmp, { force: true }).catch(() => {});
335
+ }
336
+ return {
337
+ etag: newEtag,
338
+ serverDate: /* @__PURE__ */ new Date()
339
+ };
340
+ }
341
+ if (opts?.ifMatch !== void 0) {
342
+ const existing = await readExisting(path);
343
+ if (existing === null) throw new BaerlyError("WriteConflict", `PUT ${key}: precondition failed (ifMatch=${opts.ifMatch} but key does not exist)`);
344
+ const currentEtag = etagOf(existing);
345
+ if (currentEtag !== opts.ifMatch) throw new BaerlyError("WriteConflict", `PUT ${key}: precondition failed (ifMatch=${opts.ifMatch} but current ETag is ${currentEtag})`);
346
+ }
347
+ const tmp = tempPathFor(path);
348
+ try {
349
+ await writeFile(tmp, body);
350
+ await rename(tmp, path);
351
+ } catch (error) {
352
+ throw new BaerlyError("InvalidResponse", `LocalFsStorage.put(${key}): ${error.message}`, { cause: error });
353
+ } finally {
354
+ await rm(tmp, { force: true }).catch(() => {});
355
+ }
356
+ return {
357
+ etag: newEtag,
358
+ serverDate: /* @__PURE__ */ new Date()
359
+ };
360
+ }
361
+ async delete(key, opts) {
362
+ opts?.signal?.throwIfAborted();
363
+ const path = this.#pathFor(key);
364
+ await this.#ensureFormat(false);
365
+ return withKeyLock(await this.#lockKey(path), async () => {
366
+ opts?.signal?.throwIfAborted();
367
+ try {
368
+ await rm(path);
369
+ } catch (error) {
370
+ if (isErrnoException(error) && error.code === "ENOENT") return;
371
+ throw new BaerlyError("InvalidResponse", `LocalFsStorage.delete(${key}): ${error.message}`, { cause: error });
372
+ }
373
+ });
374
+ }
375
+ /**
376
+ * Identity of the thing being mutated, for {@link withKeyLock}.
377
+ *
378
+ * Keyed on the *canonical filesystem path*, not on the key and not on
379
+ * `this`. Not on `this` because separate instances over one directory
380
+ * are the common case (`localFsStorage()` mints a fresh one per call),
381
+ * so an instance-scoped lock would serialize nothing where it matters.
382
+ * Not on the root spelling the caller passed, because several spellings
383
+ * of a root can name one directory, and handing an alias its own lock
384
+ * lets the race straight back in:
385
+ *
386
+ * - Symlinks. `resolve()` collapses `.`/`..` but not links, so
387
+ * `/tmp/data` and `/private/tmp/data` — the same directory on every
388
+ * Mac — look like two (measured at 2 winners before it was closed).
389
+ * Hence `realpath`, memoized per instance and only cached once it
390
+ * succeeds, so a root that does not exist yet cannot poison the entry.
391
+ * - Case and Unicode in the root path. A caller can spell a root on a
392
+ * folding filesystem as `/Users/me/Data` or `/users/me/data`, or in
393
+ * NFC or NFD, and reach one directory.
394
+ *
395
+ * The key-derived tail of `path` cannot alias: it is the fold-invariant
396
+ * encoding from `local-fs-key-codec.ts`, so distinct keys are distinct
397
+ * files on every filesystem and the case/NFC fold below changes nothing
398
+ * there. The fold is kept for the root-spelling case only. It
399
+ * over-approximates on a case-sensitive filesystem, where two roots
400
+ * differing only in case are really different directories and share a
401
+ * lock; that costs a little concurrency, never correctness. And it is
402
+ * not exact Unicode case folding (JS has no `toCaseFold()`), so a root
403
+ * spelled with `Σ` and one with `σ` get separate locks — acceptable for
404
+ * a root path, which the operator chooses once.
405
+ */
406
+ async #lockKey(path) {
407
+ return (await this.#canonicalRoot() + path.slice(this.#root.length)).normalize("NFC").toLowerCase();
408
+ }
409
+ /**
410
+ * {@link #root} with symlinks resolved. Cached only on success: `delete`
411
+ * against a bucket that was never created would otherwise memoize the
412
+ * un-canonicalized spelling and defeat the aliasing guard for every
413
+ * later `put`.
414
+ *
415
+ * Only `ENOENT` falls back. Every other `realpath` failure — `EACCES`,
416
+ * `ELOOP`, `ENAMETOOLONG` — throws, because the fallback is a *different
417
+ * lock key*, and absorbing those would let an instance that cannot
418
+ * canonicalize run unserialized against one that can. That is the
419
+ * exactly-one-winner guarantee this lock exists to provide, failing
420
+ * silently, which is indistinguishable from the defect it fixed. A root
421
+ * that is unreadable is a broken deployment either way; the only choice
422
+ * is whether it says so.
423
+ *
424
+ * Not caching failure bounds that to one call but does not erase it.
425
+ * `put` mkdirs before locking so it always canonicalizes; `delete` does
426
+ * not, so against a not-yet-created symlinked root it locks the
427
+ * unresolved spelling while a concurrent `put` locks the resolved one —
428
+ * two locks, no serialization. That needs only ONE spelling in play, not
429
+ * two: the split is resolved-vs-unresolved form of the same path.
430
+ *
431
+ * Known and kept, not overlooked. The hazard `delete` locks
432
+ * against is slipping inside an `ifMatch` compare→publish, which needs
433
+ * the key to exist, hence the root to exist, hence `realpath` to have
434
+ * succeeded — so both conditions hold only if the root appears between
435
+ * this call and the `rm`, and the next call self-heals. Fixes cost more
436
+ * than that: mkdir-to-get-a-lock-key makes deleting from an absent
437
+ * bucket create it, and walking to the deepest existing ancestor adds
438
+ * real complexity for an unreachable window.
439
+ */
440
+ async #canonicalRoot() {
441
+ if (this.#realRoot !== void 0) return this.#realRoot;
442
+ try {
443
+ this.#realRoot = await realpath(this.#root);
444
+ return this.#realRoot;
445
+ } catch (error) {
446
+ if (isErrnoException(error) && error.code === "ENOENT") return this.#root;
447
+ throw new BaerlyError("InvalidResponse", `LocalFsStorage: cannot canonicalize root (${this.#root}): ${error.message}`, { cause: error });
448
+ }
449
+ }
450
+ async *list(prefix, opts) {
451
+ opts?.signal?.throwIfAborted();
452
+ const startAfter = opts?.startAfter ?? "";
453
+ const maxKeys = opts?.maxKeys ?? 1e400;
454
+ await this.#ensureFormat(false);
455
+ const keys = [];
456
+ for (const components of await walk(this.#root) ?? []) {
457
+ const key = decodeComponents(components);
458
+ if (key !== null) {
459
+ keys.push(key);
460
+ continue;
461
+ }
462
+ const alias = await this.#aliasedKey(components);
463
+ if (alias !== null) throw new BaerlyError("InvalidConfig", `LocalFsStorage.list: ${join(this.#root, ...components)} was not written by this adapter but the filesystem resolves key ${JSON.stringify(alias)} to it; move the file out of the data directory`);
464
+ }
465
+ keys.sort(compareKeysUtf8);
466
+ let yielded = 0;
467
+ for (const key of keys) {
468
+ if (!key.startsWith(prefix)) continue;
469
+ if (compareKeysUtf8(key, startAfter) <= 0) continue;
470
+ if (yielded >= maxKeys) return;
471
+ opts?.signal?.throwIfAborted();
472
+ let buf;
473
+ try {
474
+ buf = await readFile(this.#pathFor(key));
475
+ } catch (error) {
476
+ if (isErrnoException(error) && error.code === "ENOENT") continue;
477
+ throw new BaerlyError("InvalidResponse", `LocalFsStorage.list(${key}): ${error.message}`, { cause: error });
478
+ }
479
+ yield {
480
+ key,
481
+ etag: etagOf(buf)
482
+ };
483
+ yielded += 1;
484
+ }
485
+ }
486
+ /**
487
+ * The key whose on-disk path the filesystem resolves to the stray file at
488
+ * `components`, or `null` if none does. Only a case- or
489
+ * normalization-folding filesystem produces one: the candidate is
490
+ * {@link foldToEncodedAlphabet} of the name, which is a key only if it
491
+ * decodes, and an alias only if both paths name the same inode.
492
+ */
493
+ async #aliasedKey(components) {
494
+ const folded = components.map(foldToEncodedAlphabet);
495
+ const key = decodeComponents(folded);
496
+ if (key === null) return null;
497
+ try {
498
+ const [a, b] = await Promise.all([stat(join(this.#root, ...components)), stat(join(this.#root, ...folded))]);
499
+ return a.dev === b.dev && a.ino === b.ino ? key : null;
500
+ } catch (error) {
501
+ if (isErrnoException(error) && (error.code === "ENOENT" || error.code === "ENOTDIR" || error.code === "ENAMETOOLONG")) return null;
502
+ throw new BaerlyError("InvalidResponse", `LocalFsStorage.list: ${error.message}`, { cause: error });
503
+ }
504
+ }
505
+ /**
506
+ * Make sure the root uses the current key encoding before any operation
507
+ * touches it. With the marker present this is one small read per
508
+ * instance. Without it the root is scanned once:
509
+ *
510
+ * - absent root: nothing to read, so reads return without stamping, and
511
+ * the first `put` (`create`) makes the root and stamps it;
512
+ * - every on-disk name already reads the same under the encoding (true
513
+ * of kernel-written trees with lowercase ids that hold no snapshot;
514
+ * the snapshot segment `L9` is escaped): stamp, nothing moves;
515
+ * - otherwise refuse with `InvalidConfig`. There is no in-place
516
+ * migration — renaming cannot undo merges a folding filesystem has
517
+ * already made — so the remedy is dump with the older release and
518
+ * restore into a fresh directory.
519
+ *
520
+ * Only success is cached, so a refusal repeats on every call.
521
+ */
522
+ async #ensureFormat(create) {
523
+ if (this.#formatChecked) return;
524
+ await this.#canonicalRoot();
525
+ const marker = join(this.#root, FORMAT_MARKER);
526
+ if (await readFormatMarker(marker)) {
527
+ this.#formatChecked = true;
528
+ return;
529
+ }
530
+ if (create) await mkdir(this.#root, { recursive: true });
531
+ const legacy = await findLegacyPaths(this.#root);
532
+ if (legacy === null) return;
533
+ if (legacy.length > 0 && !await readFormatMarker(marker)) {
534
+ const shown = legacy.slice(0, LEGACY_PATHS_SHOWN).map((p) => ` ${p}`);
535
+ if (legacy.length > LEGACY_PATHS_SHOWN) shown.push(` … and ${legacy.length - LEGACY_PATHS_SHOWN} more`);
536
+ throw new BaerlyError("InvalidConfig", `LocalFsStorage: ${this.#root} holds dev data from an older release, which this release cannot read. Move the directory aside or delete it; the next write starts a fresh one. The usual causes are a folded collection (\`snapshot/L9/\`) and an uppercase letter in a collection name or id (a camelCase name such as \`boardInvitees\`). To keep a collection's rows, dump it with the older release (\`baerly admin dump\`) and restore into the fresh directory (\`baerly admin restore\`); a dump holds collection rows only, not other files the app stored here. Paths not valid under the current key encoding (no ${FORMAT_MARKER} marker):\n${shown.join("\n")}\nIf a listed path is a stray file that is not data, move it out of the directory instead. Keys that differed only by case or Unicode normalization may already have been merged by the filesystem.`);
537
+ }
538
+ await stampFormatMarker(marker);
539
+ this.#formatChecked = true;
540
+ }
541
+ /**
542
+ * Map an S3-style key to a filesystem path under `#root`, rejecting
543
+ * anything that could escape the root (path traversal, absolute
544
+ * paths, empty segments, backslashes) or that the encoding cannot
545
+ * represent injectively (lone surrogates). All rejections throw
546
+ * `BaerlyError("InvalidConfig", …)`.
547
+ */
548
+ #pathFor(key) {
549
+ assertValidStorageKey(key);
550
+ if (key.startsWith("/")) throw new BaerlyError("InvalidConfig", `LocalFsStorage: leading "/" in key: ${key}`);
551
+ if (key.includes("\\")) throw new BaerlyError("InvalidConfig", `LocalFsStorage: backslash in key: ${key}`);
552
+ if (key.split("/").some((s) => s === "" || s === "." || s === "..")) throw new BaerlyError("InvalidConfig", `LocalFsStorage: illegal segment in key: ${key}`);
553
+ const path = join(this.#root, ...encodeKey(key));
554
+ if (path !== this.#root && !path.startsWith(this.#root + sep)) throw new BaerlyError("InvalidConfig", `LocalFsStorage: resolved path escapes root: ${key}`);
555
+ return path;
556
+ }
557
+ };
558
+ const etagOf = (body) => {
559
+ return `"${createHash("sha256").update(body).digest("hex")}"`;
560
+ };
561
+ const toUint8Array = (buf) => new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
562
+ const isErrnoException = (e) => typeof e === "object" && e !== null && "code" in e;
563
+ const readExisting = async (path) => {
564
+ try {
565
+ return await readFile(path);
566
+ } catch (error) {
567
+ if (isErrnoException(error) && error.code === "ENOENT") return null;
568
+ throw error;
569
+ }
570
+ };
571
+ /**
572
+ * `true` when the root's format marker exists and names the current
573
+ * encoding, `false` when it is absent. A marker naming another encoding
574
+ * means a newer release wrote this directory, so it is refused.
575
+ */
576
+ const readFormatMarker = async (marker) => {
577
+ const body = await readExisting(marker).catch((error) => {
578
+ throw new BaerlyError("InvalidResponse", `LocalFsStorage: cannot read ${marker}: ${error.message}`, { cause: error });
579
+ });
580
+ if (body === null) return false;
581
+ let encoding;
582
+ try {
583
+ encoding = JSON.parse(new TextDecoder().decode(body)).key_encoding;
584
+ } catch (error) {
585
+ throw new BaerlyError("InvalidResponse", `LocalFsStorage: ${marker} is not valid JSON`, { cause: error });
586
+ }
587
+ if (encoding !== KEY_ENCODING) throw new BaerlyError("InvalidConfig", `LocalFsStorage: ${marker} names key_encoding ${JSON.stringify(encoding)}; this release reads only key_encoding ${KEY_ENCODING}`);
588
+ return true;
589
+ };
590
+ /**
591
+ * Write the format marker with the same temp + `link(2)` exclusive create
592
+ * as `ifNoneMatch:"*"`. Losing that race to a concurrent opener is fine as
593
+ * long as what it wrote is the current encoding.
594
+ */
595
+ const stampFormatMarker = async (marker) => {
596
+ const tmp = tempPathFor(marker);
597
+ try {
598
+ await writeFile(tmp, `${JSON.stringify({ key_encoding: KEY_ENCODING })}\n`);
599
+ await link(tmp, marker);
600
+ } catch (error) {
601
+ if (isErrnoException(error) && error.code === "EEXIST" && await readFormatMarker(marker)) return;
602
+ throw new BaerlyError("InvalidResponse", `LocalFsStorage: cannot write ${marker}: ${error.message}`, { cause: error });
603
+ } finally {
604
+ await rm(tmp, { force: true }).catch(() => {});
605
+ }
606
+ };
607
+ /**
608
+ * Non-ASCII characters that APFS's full case folding maps to ASCII but
609
+ * `toLowerCase` leaves alone (Unicode CaseFolding.txt status `F`, plus the
610
+ * `C` mapping of long `ſ`). Each was checked on an APFS volume: a file
611
+ * named with the left side is reached by the right side.
612
+ */
613
+ const APFS_ASCII_FOLDS = {
614
+ ß: "ss",
615
+ ẞ: "ss",
616
+ ſ: "s",
617
+ ff: "ff",
618
+ fi: "fi",
619
+ fl: "fl",
620
+ ffi: "ffi",
621
+ ffl: "ffl",
622
+ ſt: "st",
623
+ st: "st"
624
+ };
625
+ const APFS_ASCII_FOLDABLE = /[ßẞſff-st]/g;
626
+ /**
627
+ * Fold an on-disk name the way a folding filesystem matches it, as far as
628
+ * the result can land in the encoded alphabet (`a-z0-9-_.%`). A name
629
+ * containing anything else after the fold cannot decode, so only folds to
630
+ * ASCII matter: lowercase (which also maps Kelvin `K` to `k`) plus
631
+ * {@link APFS_ASCII_FOLDS}. Normalization adds none: the only canonical
632
+ * decompositions to ASCII are Kelvin `K`, U+037E (`;`) and U+1FEF (`` ` ``),
633
+ * and the last two are escaped by the encoding.
634
+ */
635
+ const foldToEncodedAlphabet = (name) => name.replace(APFS_ASCII_FOLDABLE, (c) => APFS_ASCII_FOLDS[c]).toLowerCase();
636
+ /**
637
+ * Paths under `root` that the pre-encoding layout wrote and the current
638
+ * encoding would read differently (uppercase, non-ASCII, `%`, `~`, a
639
+ * leading `.` …). Empty when the tree can be adopted as-is; `null` when
640
+ * the root does not exist.
641
+ *
642
+ * Walks dot-prefixed names too: the old layout stored a key segment such
643
+ * as an `_id` or collection named `.foo` verbatim, and the encoding treats
644
+ * that name as adapter-private, so skipping it here would adopt the tree
645
+ * and silently drop or orphan that data.
646
+ */
647
+ const findLegacyPaths = async (root) => {
648
+ const files = await walk(root, isLegacyScanNoise);
649
+ if (files === null) return null;
650
+ return files.filter((components) => decodeComponents(components) !== components.join("/")).map((components) => components.join("/")).toSorted();
651
+ };
652
+ /**
653
+ * Entries the legacy scan may skip: staging temps (both layouts wrote them,
654
+ * and the old one rejected keys with that prefix), and the files Finder
655
+ * and git leave behind. Junk names are skipped as FILES only — a directory
656
+ * called `.DS_Store` would be a legacy collection or tenant, i.e. data.
657
+ * Nothing else is assumed not to be data.
658
+ *
659
+ * The format marker is deliberately not here. The scan runs only when the
660
+ * marker was absent; if a concurrent opener stamps it mid-scan, the scan
661
+ * flags it like any other name and `#ensureFormat`'s re-read of the marker
662
+ * is what accepts the directory. A nested file with the marker's name is
663
+ * legacy data (a key segment that old layout stored verbatim).
664
+ */
665
+ const isLegacyScanNoise = (name, isDirectory) => name.startsWith(TEMP_PREFIX) || !isDirectory && (name === ".DS_Store" || name === ".gitkeep");
666
+ /**
667
+ * In the current layout every dot-prefixed name is not a key: no encoded
668
+ * key component starts with `.`, so those are adapter-private (staging
669
+ * temps, the format marker) or foreign (`.DS_Store`). Skipping temps is
670
+ * what keeps a concurrent `list` from surfacing a half-published key.
671
+ */
672
+ const isDotName = (name, _isDirectory) => name.startsWith(".");
673
+ /**
674
+ * Recursive directory walk. Returns each file's path components relative
675
+ * to `root`, or `null` when `root` does not exist. Entries for which
676
+ * `skip` holds are ignored at every depth, directories included.
677
+ */
678
+ const walk = async (root, skip = isDotName) => {
679
+ const out = [];
680
+ const stack = [{
681
+ dir: root,
682
+ components: []
683
+ }];
684
+ while (stack.length > 0) {
685
+ const { dir, components } = stack.pop();
686
+ let entries;
687
+ try {
688
+ entries = await readdir(dir, { withFileTypes: true });
689
+ } catch (error) {
690
+ if (isErrnoException(error) && error.code === "ENOENT") {
691
+ if (dir === root) return null;
692
+ continue;
693
+ }
694
+ throw error;
695
+ }
696
+ for (const entry of entries) {
697
+ if (skip(entry.name, entry.isDirectory())) continue;
698
+ const next = [...components, entry.name];
699
+ if (entry.isDirectory()) stack.push({
700
+ dir: join(dir, entry.name),
701
+ components: next
702
+ });
703
+ else if (entry.isFile()) out.push(next);
704
+ }
705
+ }
706
+ return out;
707
+ };
708
+ // packages/dev/src/dev-banner.ts
709
+ function printDevBanner(opts) {
710
+ const isPlain = opts.plain !== void 0 ? opts.plain : process.env["CI"] !== void 0 || !process.stderr.isTTY;
711
+ const write = opts.write ?? ((chunk) => process.stderr.write(chunk));
712
+ const paint = (format, text) => isPlain ? text : styleText(format, text, { validateStream: false });
713
+ const pc = {
714
+ boldCyan: (text) => paint(["bold", "cyan"], text),
715
+ green: (text) => paint("green", text),
716
+ dim: (text) => paint("dim", text)
717
+ };
718
+ const hints = opts.hints ?? [];
719
+ const lines = [];
720
+ if (isPlain) {
721
+ lines.push(`baerly · ${opts.name}`);
722
+ if (opts.primaryUrl) lines.push(`${opts.primaryUrl.label}: ${opts.primaryUrl.url}`);
723
+ if (opts.apiUrl) {
724
+ const note = opts.apiUrl.note ? ` (${opts.apiUrl.note})` : "";
725
+ lines.push(`${opts.apiUrl.label}: ${opts.apiUrl.url}${note}`);
726
+ }
727
+ for (const hint of hints) lines.push(`${hint.key}: ${hint.value}`);
728
+ write(lines.join("\n") + "\n");
729
+ } else {
730
+ lines.push(pc.boldCyan(`▎ baerly · ${opts.name}`));
731
+ lines.push("");
732
+ if (opts.primaryUrl) {
733
+ const marker = ` ${pc.green("← open this")}`;
734
+ lines.push(` ${pc.dim(opts.primaryUrl.label)} → ${opts.primaryUrl.url}${marker}`);
735
+ }
736
+ if (opts.apiUrl) {
737
+ const note = opts.apiUrl.note ? ` ${pc.dim(`(${opts.apiUrl.note})`)}` : "";
738
+ lines.push(` ${pc.dim(opts.apiUrl.label)} → ${opts.apiUrl.url}${note}`);
739
+ }
740
+ if ((opts.primaryUrl || opts.apiUrl) && hints.length > 0) lines.push("");
741
+ if (hints.length > 0) {
742
+ const maxKeyLen = Math.max(...hints.map((h) => h.key.length));
743
+ for (const hint of hints) lines.push(` ${pc.dim(hint.key.padEnd(maxKeyLen))} ${hint.value}`);
744
+ }
745
+ lines.push("");
746
+ write(lines.join("\n"));
747
+ }
748
+ }
749
+ // packages/dev/src/ensure-table.ts
750
+ /**
751
+ * Optional pre-warm: idempotently create the `current.json` manifest
752
+ * for a single `(app, tenant, collection)` triple. The kernel auto-creates
753
+ * this manifest on the first commit anyway (see `Db.create` and
754
+ * `Writer.commit`), so calling `ensureTable` is **not required** for
755
+ * correctness — it's a one-Class-A-PUT optimization for callers that
756
+ * want the manifest in place before the first request lands (seed
757
+ * scripts, deploy-time provisioning, CI fixtures that snapshot the
758
+ * bucket between phases, etc.).
759
+ *
760
+ * Wraps {@link createCurrentJson} with the canonical key shape
761
+ * (`app/<app>/tenant/<tenant>/manifests/<collection>/current.json`) and
762
+ * swallows `BaerlyError{code:"WriteConflict"}` so re-runs are safe. The
763
+ * three names follow the same rule as `Db.create` / `db.collection`
764
+ * (including Unicode Normalization Form C), refused with
765
+ * `BaerlyError{code:"InvalidConfig"}` before any write. An
766
+ * existing manifest is preserved verbatim — this function never
767
+ * overwrites a populated manifest. The seed shape matches the kernel's
768
+ * auto-create, with one deliberate exception: `generation` is a fresh
769
+ * nonce, so a pre-warm and an auto-provision are equivalent rather than
770
+ * byte-identical. Only one of them can win the `If-None-Match` create,
771
+ * and a generation is only ever compared against a cursor minted from
772
+ * it, so the difference is unobservable.
773
+ *
774
+ * @example
775
+ * ```ts
776
+ * import { LocalFsStorage, ensureTable } from "@gusto/baerly-storage/dev";
777
+ *
778
+ * const storage = new LocalFsStorage({ root: "./.baerly-data" });
779
+ * // Pre-warm so the first request doesn't pay the bootstrap PUT.
780
+ * await ensureTable(storage, { app: "helpdesk", tenant: "demo", collection: "tickets" });
781
+ * // …then `baerlyNode({ config, storage, verifier })`.
782
+ * ```
783
+ */
784
+ const ensureTable = async (storage, args) => {
785
+ if (typeof args.collection !== "string") throw new BaerlyError("InvalidConfig", "table" in args ? "ensureTable: the `table` key is now `collection`; pass { app, tenant, collection }" : "ensureTable: collection must be a string");
786
+ assertNameSegment(args.app, "app", "ensureTable");
787
+ assertNameSegment(args.tenant, "tenant", "ensureTable");
788
+ assertNameSegment(args.collection, "collection", "ensureTable");
789
+ const key = `app/${args.app}/tenant/${args.tenant}/manifests/${args.collection}/current.json`;
790
+ try {
791
+ await createCurrentJson(storage, key, {
792
+ schema_version: 3,
793
+ snapshot: null,
794
+ tail_hint: 0,
795
+ log_seq_start: 0,
796
+ writer_fence: {
797
+ epoch: 0,
798
+ owner: "",
799
+ claimed_at: ""
800
+ },
801
+ snapshot_bytes: 0,
802
+ snapshot_rows: 0,
803
+ generation: mintGeneration()
804
+ });
805
+ } catch (error) {
806
+ if (isWriteConflict(error)) return;
807
+ throw error;
808
+ }
809
+ };
810
+ export { printDevBanner as n, LocalFsStorage as r, ensureTable as t };
811
+
812
+ //# sourceMappingURL=src-D0MQfvOp.js.map