@decocms/blocks 8.1.2 → 8.2.1

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 (91) hide show
  1. package/dist/protocol/client.d.ts +17 -4
  2. package/dist/protocol/client.d.ts.map +1 -1
  3. package/dist/protocol/client.js +46 -10
  4. package/dist/protocol/client.js.map +1 -1
  5. package/dist/protocol/conformance/cases/changes.d.ts +3 -0
  6. package/dist/protocol/conformance/cases/changes.d.ts.map +1 -0
  7. package/dist/protocol/conformance/cases/changes.js +295 -0
  8. package/dist/protocol/conformance/cases/changes.js.map +1 -0
  9. package/dist/protocol/conformance/context.d.ts +14 -0
  10. package/dist/protocol/conformance/context.d.ts.map +1 -1
  11. package/dist/protocol/conformance/context.js.map +1 -1
  12. package/dist/protocol/conformance/index.d.ts.map +1 -1
  13. package/dist/protocol/conformance/index.js +4 -1
  14. package/dist/protocol/conformance/index.js.map +1 -1
  15. package/dist/protocol/errors.d.ts +26 -0
  16. package/dist/protocol/errors.d.ts.map +1 -1
  17. package/dist/protocol/errors.js.map +1 -1
  18. package/dist/protocol/index.d.ts +4 -2
  19. package/dist/protocol/index.d.ts.map +1 -1
  20. package/dist/protocol/index.js +4 -2
  21. package/dist/protocol/index.js.map +1 -1
  22. package/dist/protocol/params.d.ts +4 -2
  23. package/dist/protocol/params.d.ts.map +1 -1
  24. package/dist/protocol/params.js +11 -1
  25. package/dist/protocol/params.js.map +1 -1
  26. package/dist/protocol/server/assets.d.ts +1 -1
  27. package/dist/protocol/server/assets.js +1 -1
  28. package/dist/protocol/server/core.d.ts +12 -1
  29. package/dist/protocol/server/core.d.ts.map +1 -1
  30. package/dist/protocol/server/core.js +8 -0
  31. package/dist/protocol/server/core.js.map +1 -1
  32. package/dist/protocol/server/index.d.ts +1 -1
  33. package/dist/protocol/server/index.js +1 -1
  34. package/dist/protocol/server/methods/apply.d.ts +37 -0
  35. package/dist/protocol/server/methods/apply.d.ts.map +1 -1
  36. package/dist/protocol/server/methods/apply.js +4 -3
  37. package/dist/protocol/server/methods/apply.js.map +1 -1
  38. package/dist/protocol/server/methods/changes.d.ts +6 -0
  39. package/dist/protocol/server/methods/changes.d.ts.map +1 -0
  40. package/dist/protocol/server/methods/changes.js +385 -0
  41. package/dist/protocol/server/methods/changes.js.map +1 -0
  42. package/dist/protocol/server/rpc.d.ts.map +1 -1
  43. package/dist/protocol/server/rpc.js +7 -0
  44. package/dist/protocol/server/rpc.js.map +1 -1
  45. package/dist/protocol/storage/fs/git.d.ts +63 -0
  46. package/dist/protocol/storage/fs/git.d.ts.map +1 -0
  47. package/dist/protocol/storage/fs/git.js +376 -0
  48. package/dist/protocol/storage/fs/git.js.map +1 -0
  49. package/dist/protocol/storage/fs/index.d.ts +2 -0
  50. package/dist/protocol/storage/fs/index.d.ts.map +1 -1
  51. package/dist/protocol/storage/fs/index.js +53 -1
  52. package/dist/protocol/storage/fs/index.js.map +1 -1
  53. package/dist/protocol/storage/memory.d.ts +10 -0
  54. package/dist/protocol/storage/memory.d.ts.map +1 -1
  55. package/dist/protocol/storage/memory.js +45 -0
  56. package/dist/protocol/storage/memory.js.map +1 -1
  57. package/dist/protocol/storage.d.ts +53 -1
  58. package/dist/protocol/storage.d.ts.map +1 -1
  59. package/dist/protocol/storage.js.map +1 -1
  60. package/dist/protocol/types.d.ts +105 -4
  61. package/dist/protocol/types.d.ts.map +1 -1
  62. package/dist/protocol/types.js +16 -3
  63. package/dist/protocol/types.js.map +1 -1
  64. package/dist/v8/cli/run.d.ts.map +1 -1
  65. package/dist/v8/cli/run.js +2 -1
  66. package/dist/v8/cli/run.js.map +1 -1
  67. package/dist/v8/cli/serve/server.d.ts +2 -0
  68. package/dist/v8/cli/serve/server.d.ts.map +1 -1
  69. package/dist/v8/cli/serve/server.js +37 -2
  70. package/dist/v8/cli/serve/server.js.map +1 -1
  71. package/package.json +1 -1
  72. package/src/protocol/client.ts +81 -13
  73. package/src/protocol/conformance/cases/changes.ts +362 -0
  74. package/src/protocol/conformance/context.ts +12 -0
  75. package/src/protocol/conformance/index.ts +4 -1
  76. package/src/protocol/errors.ts +17 -0
  77. package/src/protocol/index.ts +4 -2
  78. package/src/protocol/params.ts +26 -3
  79. package/src/protocol/server/assets.ts +1 -1
  80. package/src/protocol/server/core.ts +9 -0
  81. package/src/protocol/server/index.ts +1 -1
  82. package/src/protocol/server/methods/apply.ts +8 -4
  83. package/src/protocol/server/methods/changes.ts +493 -0
  84. package/src/protocol/server/rpc.ts +7 -0
  85. package/src/protocol/storage/fs/git.ts +424 -0
  86. package/src/protocol/storage/fs/index.ts +59 -1
  87. package/src/protocol/storage/memory.ts +57 -0
  88. package/src/protocol/storage.ts +55 -1
  89. package/src/protocol/types.ts +106 -4
  90. package/src/v8/cli/run.ts +2 -1
  91. package/src/v8/cli/serve/server.ts +46 -2
@@ -0,0 +1,424 @@
1
+ /**
2
+ * The filesystem storage's base: the git `HEAD` of the repository the app
3
+ * root is in. It runs `git` (no new dependency, no shell, argv arrays only)
4
+ * and writes git state in one place only: a discard brings the index entries
5
+ * of exactly the paths it restores (plus both sides of a staged rename that
6
+ * involves one of them) back to `HEAD` (`unstage`), so a block staged with
7
+ * `git add`, `git mv` or `git rm` isn't committed later. Never commits, never
8
+ * touches another path's staging. A discard writes the files themselves,
9
+ * through the storage's own commit.
10
+ *
11
+ * Changes are the working tree against `HEAD` (the index is never
12
+ * consulted), with git's own idea of equal: a file whose bytes differ only by
13
+ * the checkout filters (`eol=crlf`, `autocrlf`, LFS) isn't a change.
14
+ */
15
+ import { execFile } from "node:child_process";
16
+ import { join } from "node:path";
17
+ import { isBlockFileName } from "../../keys.ts";
18
+ import { type StorageBase, type StorageFile, StorageUnavailableError } from "../../storage.ts";
19
+
20
+ /** The base revision reported for a repository with no commits yet (an empty base). */
21
+ export const UNBORN_REVISION = "unborn";
22
+
23
+ /** Environment that would point git at another repository, index or object store. */
24
+ const INHERITED_GIT_ENV = [
25
+ "GIT_DIR",
26
+ "GIT_WORK_TREE",
27
+ "GIT_INDEX_FILE",
28
+ "GIT_OBJECT_DIRECTORY",
29
+ "GIT_ALTERNATE_OBJECT_DIRECTORIES",
30
+ "GIT_NAMESPACE",
31
+ "GIT_PREFIX",
32
+ "GIT_COMMON_DIR",
33
+ ];
34
+
35
+ const COMMIT_ID = /^[0-9a-f]{40,64}$/;
36
+
37
+ /** Files per `git hash-object` call, so an argv stays far below any OS limit. */
38
+ const HASH_CHUNK = 100;
39
+
40
+ /** Base bodies read at once. */
41
+ const READ_CONCURRENCY = 4;
42
+
43
+ export interface GitOptions {
44
+ /** The git binary (default `git`, from `PATH`). */
45
+ git?: string;
46
+ }
47
+
48
+ interface RunOptions extends GitOptions {
49
+ /** Bytes written to git's stdin. */
50
+ input?: string;
51
+ }
52
+
53
+ /** A git call that failed: `missing` when the binary isn't there. */
54
+ export class GitError extends Error {
55
+ constructor(
56
+ message: string,
57
+ readonly reason: "missing" | "failed",
58
+ readonly exitCode: number | null,
59
+ readonly stderr: string,
60
+ ) {
61
+ super(message);
62
+ this.name = "GitError";
63
+ }
64
+ }
65
+
66
+ function gitEnv(): NodeJS.ProcessEnv {
67
+ const env: NodeJS.ProcessEnv = { ...process.env };
68
+ for (const key of INHERITED_GIT_ENV) delete env[key];
69
+ return {
70
+ ...env,
71
+ // Pathspecs are literal: a file named `:(glob)x.json` is just a file.
72
+ GIT_LITERAL_PATHSPECS: "1",
73
+ // Never refresh (write) the index while reading.
74
+ GIT_OPTIONAL_LOCKS: "0",
75
+ GIT_TERMINAL_PROMPT: "0",
76
+ LC_ALL: "C",
77
+ };
78
+ }
79
+
80
+ /** Runs git and resolves with its stdout bytes; rejects with a `GitError`. */
81
+ export function runGit(cwd: string, args: string[], options: RunOptions = {}): Promise<Buffer> {
82
+ const git = options.git ?? "git";
83
+ return new Promise((resolve, reject) => {
84
+ const child = execFile(
85
+ git,
86
+ args,
87
+ {
88
+ cwd,
89
+ env: gitEnv(),
90
+ encoding: "buffer",
91
+ maxBuffer: 64 * 1024 * 1024,
92
+ timeout: 30_000,
93
+ windowsHide: true,
94
+ },
95
+ (error, stdout, stderr) => {
96
+ if (!error) return resolve(stdout);
97
+ const code = (error as NodeJS.ErrnoException).code;
98
+ const text = Buffer.isBuffer(stderr) ? stderr.toString("utf8") : String(stderr ?? "");
99
+ if (code === "ENOENT") {
100
+ return reject(new GitError(`${git} isn't installed`, "missing", null, text));
101
+ }
102
+ const exitCode = typeof code === "number" ? code : null;
103
+ const line = text.split("\n").find((l) => l.trim() !== "") ?? error.message;
104
+ reject(new GitError(line.trim(), "failed", exitCode, text));
105
+ },
106
+ );
107
+ if (options.input !== undefined) {
108
+ // A git that exits early closes its stdin; the exit callback reports it.
109
+ child.stdin?.on("error", () => {});
110
+ child.stdin?.end(options.input);
111
+ }
112
+ });
113
+ }
114
+
115
+ const firstLine = (bytes: Buffer) => bytes.toString("utf8").split("\n")[0]!.trim();
116
+
117
+ /** Where `dir` stands in git: inside a work tree, not, or git is missing. */
118
+ export type GitWorkTreeCheck =
119
+ | { status: "ok" }
120
+ | { status: "missing" }
121
+ | { status: "not-a-repository" }
122
+ | { status: "failed"; message: string };
123
+
124
+ /** Checks that `dir` is inside a git work tree (not a bare repository, not inside `.git`). */
125
+ export async function checkGitWorkTree(
126
+ dir: string,
127
+ options: GitOptions = {},
128
+ ): Promise<GitWorkTreeCheck> {
129
+ try {
130
+ const inside = firstLine(await runGit(dir, ["rev-parse", "--is-inside-work-tree"], options));
131
+ return inside === "true" ? { status: "ok" } : { status: "not-a-repository" };
132
+ } catch (error) {
133
+ if (!(error instanceof GitError)) throw error;
134
+ if (error.reason === "missing") return { status: "missing" };
135
+ if (/not a git repository/i.test(error.stderr)) return { status: "not-a-repository" };
136
+ return { status: "failed", message: error.message };
137
+ }
138
+ }
139
+
140
+ function unavailable(error: unknown): never {
141
+ if (error instanceof GitError) throw new StorageUnavailableError(`git: ${error.message}`);
142
+ throw error;
143
+ }
144
+
145
+ /** A blob of the base: the file name inside `.deco/blocks` and its blob id. */
146
+ type BaseBlob = StorageFile;
147
+
148
+ /** The git side of one app root: its base, what differs from it, and base bodies. */
149
+ export interface GitBase {
150
+ base(): Promise<StorageBase>;
151
+ /** The saved-block files in the base, with their blob ids as versions. */
152
+ baseFiles(base: StorageBase): Promise<BaseBlob[]>;
153
+ /**
154
+ * The working-tree files (by name, with their raw blob hash) that differ
155
+ * from `baseFiles`: missing on one side, or different after git's filters.
156
+ */
157
+ differing(base: StorageBase, current: StorageFile[]): Promise<string[]>;
158
+ /** Base bodies as a checkout writes them (smudge and eol filters applied). */
159
+ readBase(base: StorageBase, files: string[]): Promise<Map<string, Buffer>>;
160
+ /**
161
+ * Brings the index entries of these saved-block files (names inside
162
+ * `.deco/blocks`), plus both sides of any staged rename that involves one
163
+ * of them, back to `HEAD`: a path `HEAD` has gets `HEAD`'s entry, any other
164
+ * path leaves the index (an unborn `HEAD` has none). The working tree is
165
+ * left alone. Resolves with an undo that puts the previous entries back.
166
+ */
167
+ unstage(files: string[]): Promise<() => Promise<void>>;
168
+ }
169
+
170
+ /**
171
+ * The git base of the app root `root` (the folder that contains `.deco`),
172
+ * whose saved blocks are `.deco/blocks/*.json`.
173
+ */
174
+ export function createGitBase(root: string, options: GitOptions = {}): GitBase {
175
+ const blocksDir = join(root, ".deco", "blocks");
176
+ let prefix: Promise<string> | undefined;
177
+ /** Base listings by commit: a commit's tree never changes. */
178
+ let listing: { revision: string; files: Promise<BaseBlob[]> } | undefined;
179
+
180
+ const git = (args: string[], cwd = root) => runGit(cwd, args, options);
181
+
182
+ async function base(): Promise<StorageBase> {
183
+ try {
184
+ let revision = UNBORN_REVISION;
185
+ try {
186
+ const sha = firstLine(await git(["rev-parse", "-q", "--verify", "HEAD^{commit}"]));
187
+ if (COMMIT_ID.test(sha)) revision = sha;
188
+ } catch (error) {
189
+ // `--verify -q` exits 1 without output on an unborn HEAD (a fresh `git init`).
190
+ if (!(error instanceof GitError) || error.reason !== "failed" || error.stderr.trim()) {
191
+ throw error;
192
+ }
193
+ }
194
+ let resolvedRef: string | null = null;
195
+ try {
196
+ resolvedRef = firstLine(await git(["symbolic-ref", "-q", "--short", "HEAD"])) || null;
197
+ } catch (error) {
198
+ // Exits 1 on a detached HEAD.
199
+ if (!(error instanceof GitError) || error.reason !== "failed" || error.stderr.trim()) {
200
+ throw error;
201
+ }
202
+ }
203
+ return { revision, resolvedRef };
204
+ } catch (error) {
205
+ unavailable(error);
206
+ }
207
+ }
208
+
209
+ async function listBase(revision: string): Promise<BaseBlob[]> {
210
+ if (!COMMIT_ID.test(revision)) return [];
211
+ // Relative to the app root (cwd): `.deco/blocks/<file>`. Only regular
212
+ // files directly in the folder; subfolders, symlinks and submodules aren't blocks.
213
+ const out = await git(["ls-tree", "-z", "--long", revision, "--", ".deco/blocks/"]);
214
+ const files: BaseBlob[] = [];
215
+ for (const record of out.toString("utf8").split("\0")) {
216
+ const tab = record.indexOf("\t");
217
+ if (tab === -1) continue;
218
+ const [mode, type, id, size] = record.slice(0, tab).trim().split(/\s+/);
219
+ const path = record.slice(tab + 1);
220
+ if (type !== "blob" || (mode !== "100644" && mode !== "100755")) continue;
221
+ if (!path.startsWith(".deco/blocks/")) continue;
222
+ const file = path.slice(".deco/blocks/".length);
223
+ if (!isBlockFileName(file) || !id || !COMMIT_ID.test(id)) continue;
224
+ const bytes = Number(size);
225
+ files.push(
226
+ Number.isFinite(bytes) ? { file, version: id, size: bytes } : { file, version: id },
227
+ );
228
+ }
229
+ return files;
230
+ }
231
+
232
+ function baseFiles(current: StorageBase): Promise<BaseBlob[]> {
233
+ if (listing?.revision !== current.revision) {
234
+ const files = listBase(current.revision).catch(unavailable);
235
+ listing = { revision: current.revision, files };
236
+ files.catch(() => {
237
+ if (listing?.files === files) listing = undefined;
238
+ });
239
+ }
240
+ return listing.files;
241
+ }
242
+
243
+ /** The blob ids git would store for these working-tree files (filters applied). */
244
+ async function hashWorking(files: string[]): Promise<string[]> {
245
+ const ids: string[] = [];
246
+ for (let i = 0; i < files.length; i += HASH_CHUNK) {
247
+ const chunk = files.slice(i, i + HASH_CHUNK);
248
+ const out = await git(["hash-object", "--", ...chunk], blocksDir);
249
+ const lines = out.toString("utf8").split("\n").filter(Boolean);
250
+ if (lines.length !== chunk.length) {
251
+ throw new GitError("hash-object answered an unexpected listing", "failed", null, "");
252
+ }
253
+ ids.push(...lines);
254
+ }
255
+ return ids;
256
+ }
257
+
258
+ async function differing(current: StorageBase, now: StorageFile[]): Promise<string[]> {
259
+ try {
260
+ const inBase = new Map((await baseFiles(current)).map((f) => [f.file, f.version]));
261
+ const changed = new Set<string>();
262
+ const toConfirm: string[] = [];
263
+ const present = new Set<string>();
264
+ for (const file of now) {
265
+ present.add(file.file);
266
+ const id = inBase.get(file.file);
267
+ if (id === undefined) changed.add(file.file);
268
+ // The raw bytes' hash equals the blob id: the same content, no filter involved.
269
+ else if (id !== file.version) toConfirm.push(file.file);
270
+ }
271
+ for (const file of inBase.keys()) if (!present.has(file)) changed.add(file);
272
+ if (toConfirm.length > 0) {
273
+ let ids: string[];
274
+ try {
275
+ ids = await hashWorking(toConfirm);
276
+ } catch (error) {
277
+ // A file vanished meanwhile: count every candidate as changed; the
278
+ // core's next snapshot reports the truth.
279
+ if (
280
+ error instanceof GitError &&
281
+ /No such file|cannot open|unable to/i.test(error.stderr)
282
+ ) {
283
+ ids = toConfirm.map(() => "");
284
+ } else throw error;
285
+ }
286
+ toConfirm.forEach((file, i) => {
287
+ if (ids[i] !== inBase.get(file)) changed.add(file);
288
+ });
289
+ }
290
+ return [...changed].sort();
291
+ } catch (error) {
292
+ unavailable(error);
293
+ }
294
+ }
295
+
296
+ async function readBase(current: StorageBase, files: string[]): Promise<Map<string, Buffer>> {
297
+ try {
298
+ const out = new Map<string, Buffer>();
299
+ if (files.length === 0) return out;
300
+ const inBase = new Map((await baseFiles(current)).map((f) => [f.file, f.version]));
301
+ prefix ??= git(["rev-parse", "--show-prefix"]).then((b) => firstLine(b));
302
+ const repoPrefix = await prefix;
303
+ const wanted = files.filter((file) => isBlockFileName(file) && inBase.has(file));
304
+ for (let i = 0; i < wanted.length; i += READ_CONCURRENCY) {
305
+ await Promise.all(
306
+ wanted.slice(i, i + READ_CONCURRENCY).map(async (file) => {
307
+ const id = inBase.get(file)!;
308
+ // Per file: `cat-file --batch --filters` frames its output with the
309
+ // unfiltered size, so a filtered stream can't be split reliably.
310
+ const body = await git([
311
+ "cat-file",
312
+ "--filters",
313
+ `--path=${repoPrefix}.deco/blocks/${file}`,
314
+ id,
315
+ ]);
316
+ out.set(file, body);
317
+ }),
318
+ );
319
+ }
320
+ return out;
321
+ } catch (error) {
322
+ prefix = undefined;
323
+ unavailable(error);
324
+ }
325
+ }
326
+
327
+ let topLevel: Promise<{ top: string; prefix: string }> | undefined;
328
+
329
+ /** The work tree's top folder, and the app root's path inside it (`apps/web/` or ``). */
330
+ function where() {
331
+ topLevel ??= git(["rev-parse", "--show-toplevel", "--show-prefix"]).then((out) => {
332
+ const [top = "", repoPrefix = ""] = out.toString("utf8").split("\n");
333
+ return { top: top.trim(), prefix: repoPrefix.trim() };
334
+ });
335
+ topLevel.catch(() => {
336
+ topLevel = undefined;
337
+ });
338
+ return topLevel;
339
+ }
340
+
341
+ /** Runs `args -- <paths>` in chunks, so an argv stays far below any OS limit. */
342
+ async function forPaths(top: string, args: string[], paths: string[]): Promise<Buffer[]> {
343
+ const outs: Buffer[] = [];
344
+ for (let i = 0; i < paths.length; i += HASH_CHUNK) {
345
+ outs.push(await git([...args, "--", ...paths.slice(i, i + HASH_CHUNK)], top));
346
+ }
347
+ return outs;
348
+ }
349
+
350
+ /** Both sides of every rename staged against `HEAD`, as repo-relative paths. */
351
+ async function stagedRenames(top: string): Promise<[string, string][]> {
352
+ const out = await git(
353
+ ["diff-index", "--cached", "-z", "--name-status", "-M", "--no-ext-diff", "HEAD"],
354
+ top,
355
+ );
356
+ const fields = out.toString("utf8").split("\0");
357
+ const renames: [string, string][] = [];
358
+ for (let i = 0; i < fields.length; ) {
359
+ const status = fields[i++]!;
360
+ if (status === "") continue;
361
+ if (status.startsWith("R") || status.startsWith("C")) {
362
+ const from = fields[i++]!;
363
+ const to = fields[i++]!;
364
+ if (status.startsWith("R")) renames.push([from, to]);
365
+ } else i++;
366
+ }
367
+ return renames;
368
+ }
369
+
370
+ async function unstage(files: string[]): Promise<() => Promise<void>> {
371
+ try {
372
+ const noop = async () => {};
373
+ if (files.length === 0) return noop;
374
+ for (const file of files) {
375
+ if (!isBlockFileName(file)) throw new Error(`not a saved-block file: ${file}`);
376
+ }
377
+ const { top, prefix: appPrefix } = await where();
378
+ const paths = new Set(files.map((file) => `${appPrefix}.deco/blocks/${file}`));
379
+ const born = (await base()).revision !== UNBORN_REVISION;
380
+ if (born) {
381
+ for (const [from, to] of await stagedRenames(top)) {
382
+ if (paths.has(from) || paths.has(to)) {
383
+ paths.add(from);
384
+ paths.add(to);
385
+ }
386
+ }
387
+ }
388
+ const all = [...paths].sort();
389
+ // The entries as they are now, every stage, for the undo.
390
+ const before = (await forPaths(top, ["ls-files", "-s", "-z", "--full-name"], all))
391
+ .map((b) => b.toString("utf8"))
392
+ .join("");
393
+ const inHead = new Set<string>();
394
+ if (born) {
395
+ const listed = await forPaths(
396
+ top,
397
+ ["ls-tree", "-z", "--name-only", "--full-name", "HEAD"],
398
+ all,
399
+ );
400
+ for (const out of listed) {
401
+ for (const path of out.toString("utf8").split("\0")) if (path) inHead.add(path);
402
+ }
403
+ }
404
+ const tracked = all.filter((path) => inHead.has(path));
405
+ const untracked = all.filter((path) => !inHead.has(path));
406
+ if (tracked.length > 0) await forPaths(top, ["reset", "-q", "HEAD"], tracked);
407
+ if (untracked.length > 0) {
408
+ // `-f`: a staged new file edited again matches neither HEAD nor the disk.
409
+ await forPaths(top, ["rm", "--cached", "-f", "--quiet", "--ignore-unmatch"], untracked);
410
+ }
411
+ return async () => {
412
+ // Drop whatever entry each path has now, then put the old ones back.
413
+ await forPaths(top, ["update-index", "--force-remove"], all);
414
+ if (before) {
415
+ await runGit(top, ["update-index", "-z", "--index-info"], { ...options, input: before });
416
+ }
417
+ };
418
+ } catch (error) {
419
+ unavailable(error);
420
+ }
421
+ }
422
+
423
+ return { base, baseFiles, differing, readBase, unstage };
424
+ }
@@ -10,6 +10,16 @@
10
10
  * - Uploads go to `public/assets` (or `assetsDir`), never overwriting a file.
11
11
  *
12
12
  * A file's version is its git blob hash, as `git hash-object` prints it.
13
+ *
14
+ * Its base (what `changes.*` compares with) is the git `HEAD` of the
15
+ * repository the app root is in, read with the `git` binary (./git.ts):
16
+ * `changes.list`, `changes.get` and `changes.discard` need the app root to be
17
+ * inside a git work tree, and answer Unavailable otherwise. `deco serve`
18
+ * refuses to start outside one. The other methods don't need git.
19
+ * `changes.discard` also brings the git index entries of the files it
20
+ * restores (and both sides of a staged rename involving one) back to `HEAD`,
21
+ * so a block staged with `git add`/`git mv`/`git rm` isn't left staged; no
22
+ * other path's staging is touched.
13
23
  * Commits are serialized per `.deco` folder (in process and across processes)
14
24
  * and applied with staged files and atomic renames, rolled back on failure,
15
25
  * with the folder fsynced before a commit returns.
@@ -35,6 +45,7 @@ import {
35
45
  type StoredFileBody,
36
46
  type StoredSchema,
37
47
  } from "../../storage.ts";
48
+ import { createGitBase } from "./git.ts";
38
49
  import { gitBlobHash, revisionOf } from "./hash.ts";
39
50
  import { withCommitLock } from "./lock.ts";
40
51
  import { applyFileChange, sweepStaleTransactions } from "./transaction.ts";
@@ -58,6 +69,8 @@ export interface FsStorageOptions {
58
69
  pollIntervalMs?: number;
59
70
  /** How long a commit waits for another process's lock (default 10 s). */
60
71
  lockTimeoutMs?: number;
72
+ /** The git binary the base is read with (default `git`, from `PATH`). */
73
+ git?: string;
61
74
  }
62
75
 
63
76
  export type FsStorage = ContentStorage & {
@@ -134,6 +147,7 @@ export function createFsStorage(options: FsStorageOptions): FsStorage {
134
147
  const lockOptions = { timeoutMs: options.lockTimeoutMs ?? 10_000, staleMs: 30_000 };
135
148
  let repoRoot: Promise<string> | undefined;
136
149
  let swept = false;
150
+ const gitBase = createGitBase(root, { git: options.git });
137
151
 
138
152
  /** file -> stat fingerprint and its hash, so a poll only rehashes changed files. */
139
153
  const hashCache = new Map<string, { fingerprint: string; version: string }>();
@@ -279,6 +293,12 @@ export function createFsStorage(options: FsStorageOptions): FsStorage {
279
293
  await sweepStaleTransactions(decoDir);
280
294
  swept = true;
281
295
  }
296
+ if (
297
+ attempt.expectedBase !== undefined &&
298
+ (await gitBase.base()).revision !== attempt.expectedBase
299
+ ) {
300
+ return { status: "stale" } as const;
301
+ }
282
302
  if (attempt.expectedSchemaVersion !== undefined) {
283
303
  const schema = await readSchema();
284
304
  if ((schema?.version ?? null) !== attempt.expectedSchemaVersion) {
@@ -288,7 +308,21 @@ export function createFsStorage(options: FsStorageOptions): FsStorage {
288
308
  for (const [file, expected] of Object.entries(attempt.expected)) {
289
309
  if ((await freshVersion(file)) !== expected) return { status: "stale" } as const;
290
310
  }
291
- await applyFileChange(blocksDir, decoDir, { put: attempt.put, delete: attempt.delete });
311
+ // A discard also unstages what it restores, before writing, so a
312
+ // failed write puts the index back too: all or nothing.
313
+ const restaged =
314
+ attempt.reason === "discard"
315
+ ? await gitBase.unstage([...Object.keys(attempt.put), ...attempt.delete])
316
+ : undefined;
317
+ try {
318
+ await applyFileChange(blocksDir, decoDir, {
319
+ put: attempt.put,
320
+ delete: attempt.delete,
321
+ });
322
+ } catch (error) {
323
+ await restaged?.().catch(() => {});
324
+ throw error;
325
+ }
292
326
  const versions: Record<string, string> = {};
293
327
  for (const [file, content] of Object.entries(attempt.put))
294
328
  versions[file] = gitBlobHash(content);
@@ -300,6 +334,30 @@ export function createFsStorage(options: FsStorageOptions): FsStorage {
300
334
  }
301
335
  },
302
336
 
337
+ base: () => gitBase.base(),
338
+
339
+ async changes(base, current) {
340
+ const [files, baseFiles] = await Promise.all([
341
+ gitBase.differing(base, current.files),
342
+ gitBase.baseFiles(base),
343
+ ]);
344
+ return { files, baseFiles };
345
+ },
346
+
347
+ async readBaseFiles(base, files) {
348
+ for (const file of files) assertBlockFile(file);
349
+ const versions = new Map((await gitBase.baseFiles(base)).map((f) => [f.file, f.version]));
350
+ const bodies = await gitBase.readBase(base, files);
351
+ // Exactly as a checkout writes them, a leading BOM included: a discard
352
+ // writes this text back, and anything else would still differ from HEAD.
353
+ const decoder = new TextDecoder("utf-8", { ignoreBOM: true });
354
+ const out: Record<string, StoredFileBody> = Object.create(null);
355
+ for (const [file, bytes] of bodies) {
356
+ out[file] = { text: decoder.decode(bytes), version: versions.get(file)! };
357
+ }
358
+ return out;
359
+ },
360
+
303
361
  async putAsset(name, body) {
304
362
  if (readOnly) throw new StorageUnavailableError("the storage is read-only");
305
363
  if (!name || name.includes("/") || name.includes("\\") || name.startsWith(".")) {
@@ -32,6 +32,12 @@ export interface MemoryStorageState {
32
32
  assets: Record<string, string>;
33
33
  /** `false` simulates an app root with no `.deco` folder at all. */
34
34
  hasDecoFolder: boolean;
35
+ /** The base's saved-block files (what `changes.*` compares with), by file name. Default: none. */
36
+ base: Record<string, string>;
37
+ /** The base's revision; moves with every `setBase`/`commitBase`. */
38
+ baseRevision: string;
39
+ /** The base's branch. Default `null`. */
40
+ baseRef: string | null;
35
41
  }
36
42
 
37
43
  export interface MemoryStorageOptions {
@@ -51,6 +57,10 @@ export interface MemoryStorage extends ContentStorage {
51
57
  setFile(file: string, content: string | null): void;
52
58
  /** Replaces `schema.gen.json` (`null` removes it). */
53
59
  setSchema(schema: string | object | null): void;
60
+ /** Replaces the base's files, as a publish (or an outside commit) would. */
61
+ setBase(files: Record<string, string>): void;
62
+ /** Makes the current files the base, as a commit of every change would. */
63
+ commitBase(): void;
54
64
  /** How many commits landed. */
55
65
  readonly commits: number;
56
66
  }
@@ -65,8 +75,13 @@ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryS
65
75
  secretsPublicKey: null,
66
76
  assets: {},
67
77
  hasDecoFolder: true,
78
+ base: {},
79
+ baseRevision: "base-0",
80
+ baseRef: null,
68
81
  ...options.state,
69
82
  });
83
+ // structuredClone keeps shared references: the base is never the files object.
84
+ state.base = { ...state.base };
70
85
  const description: StorageDescription = {
71
86
  kind: "git",
72
87
  root: ".",
@@ -107,6 +122,9 @@ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryS
107
122
  if (!isBlockFileName(file)) throw new StorageInvalidFileError(file);
108
123
  }
109
124
  if (!state.hasDecoFolder) throw new StorageNotFoundError("no .deco folder");
125
+ if (attempt.expectedBase !== undefined && attempt.expectedBase !== state.baseRevision) {
126
+ return { status: "stale" };
127
+ }
110
128
  if (
111
129
  attempt.expectedSchemaVersion !== undefined &&
112
130
  (await schemaVersion()) !== attempt.expectedSchemaVersion
@@ -173,6 +191,36 @@ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryS
173
191
  return state.secretsPublicKey;
174
192
  },
175
193
 
194
+ async base() {
195
+ return { revision: state.baseRevision, resolvedRef: state.baseRef };
196
+ },
197
+
198
+ async changes(_base, snapshot) {
199
+ const baseFiles = await Promise.all(
200
+ Object.entries(state.base).map(async ([file, content]) => ({
201
+ file,
202
+ version: await version(content),
203
+ size: new TextEncoder().encode(content).byteLength,
204
+ })),
205
+ );
206
+ const baseVersion = new Map(baseFiles.map((f) => [f.file, f.version]));
207
+ const current = new Map(snapshot.files.map((f) => [f.file, f.version]));
208
+ const files = new Set<string>();
209
+ for (const [file, v] of current) if (baseVersion.get(file) !== v) files.add(file);
210
+ for (const file of baseVersion.keys()) if (!current.has(file)) files.add(file);
211
+ return { files: [...files], baseFiles };
212
+ },
213
+
214
+ async readBaseFiles(_base, files) {
215
+ const out: Record<string, StoredFileBody> = Object.create(null);
216
+ for (const file of files) {
217
+ if (!(file in state.base)) continue;
218
+ const text = state.base[file]!;
219
+ out[file] = { text, version: await version(text) };
220
+ }
221
+ return out;
222
+ },
223
+
176
224
  commit(attempt): Promise<CommitResult> {
177
225
  // Serialized, so a commit's checks and its mutation are one atomic step.
178
226
  const run = commitQueue.then(() => commitNow(attempt));
@@ -194,6 +242,15 @@ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryS
194
242
  else state.files[file] = content;
195
243
  },
196
244
 
245
+ setBase(files) {
246
+ state.base = { ...files };
247
+ state.baseRevision = `base-${Math.random().toString(36).slice(2, 10)}`;
248
+ },
249
+
250
+ commitBase() {
251
+ storage.setBase(state.files);
252
+ },
253
+
197
254
  setSchema(schema) {
198
255
  state.schema =
199
256
  schema === null || typeof schema === "string" ? schema : JSON.stringify(schema);