@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
@@ -2,7 +2,9 @@
2
2
  * The storage interface a content-protocol backend implements.
3
3
  *
4
4
  * A storage is deliberately small: a snapshot of file names and versions,
5
- * reading file bodies, reading the schema, and one atomic commit attempt.
5
+ * reading file bodies, reading the schema, one atomic commit attempt, and its
6
+ * base (what `changes.*` compares the content with: the files that differ
7
+ * from it, and reading base bodies).
6
8
  * The protocol core (`createContentHandler`) owns everything else: the
7
9
  * JSON-RPC layer, validation, the file-name rule, the secret guard, limits and
8
10
  * retries. Storages deal in *files* inside `<root>/.deco/blocks`; entry names
@@ -84,6 +86,45 @@ export interface CommitAttempt {
84
86
  * commit time differs, checked atomically with `expected`.
85
87
  */
86
88
  expectedSchemaVersion?: string | null;
89
+ /**
90
+ * The base revision (`StorageBase.revision`) the core computed the write
91
+ * from, when the write depends on it (`changes.discard` restores base
92
+ * bytes). When set, a storage MUST reject the attempt as stale if its base
93
+ * revision at commit time differs, checked atomically with `expected`.
94
+ */
95
+ expectedBase?: string;
96
+ /**
97
+ * Why the core commits: `apply` (default) or `discard`. For logs, and a
98
+ * storage with a staging area (the fs storage's git index) also unstages
99
+ * the files a `discard` writes or deletes, in the same commit.
100
+ */
101
+ reason?: "apply" | "discard";
102
+ }
103
+
104
+ /** What a storage's content is compared against (`changes.*`). */
105
+ export interface StorageBase {
106
+ /** An opaque revision of the base, compared only for equality (a commit sha). */
107
+ revision: string;
108
+ /** The branch the base was read from; `null` when there's none. */
109
+ resolvedRef: string | null;
110
+ }
111
+
112
+ /** The files of a snapshot that differ from the base. */
113
+ export interface StorageChanges {
114
+ /**
115
+ * Saved-block file names that differ from the base: in the snapshot and not
116
+ * in the base, in the base and not in the snapshot, or in both with
117
+ * different content. A file whose content equals the base's (the storage
118
+ * decides equality, such as honouring git's eol conversion) MUST NOT be
119
+ * listed, so a file a discard just restored is never listed again.
120
+ */
121
+ files: string[];
122
+ /**
123
+ * The base's files, with their versions in the base: at least every file
124
+ * whose spelling group (`spellingKey`) a file in `files` belongs to; more
125
+ * is fine.
126
+ */
127
+ baseFiles: StorageFile[];
87
128
  }
88
129
 
89
130
  export type CommitResult =
@@ -115,6 +156,19 @@ export interface ContentStorage {
115
156
  readSecretsPublicKey(): Promise<string | null>;
116
157
  /** One all-or-nothing commit attempt; durable when it resolves. */
117
158
  commit(attempt: CommitAttempt): Promise<CommitResult>;
159
+ /**
160
+ * The current base, cheaply: the core calls it on every `changes.list`
161
+ * poll. Throws `StorageUnavailableError` when the base can't be read now.
162
+ */
163
+ base(): Promise<StorageBase>;
164
+ /** The files of `snapshot` that differ from `base`, and the base files they touch. */
165
+ changes(base: StorageBase, snapshot: StorageSnapshot): Promise<StorageChanges>;
166
+ /**
167
+ * Reads base file bodies, as a checkout would write them (a leading BOM
168
+ * kept: a discard writes the text back as is), each with its version in the
169
+ * base. A file the base doesn't have is left out.
170
+ */
171
+ readBaseFiles(base: StorageBase, files: string[]): Promise<Record<string, StoredFileBody>>;
118
172
  /** Stores an uploaded file, never overwriting one; returns the stored file name. */
119
173
  putAsset?(name: string, body: Uint8Array): Promise<{ name: string }>;
120
174
  }
@@ -1,12 +1,23 @@
1
1
  /**
2
2
  * The content protocol's method types: JSON-RPC 2.0 over one HTTP endpoint,
3
- * four methods (`describe`, `schema.get`, `blocks.list`, `blocks.apply`).
3
+ * seven methods (`describe`, `schema.get`, `blocks.list`, `blocks.apply`,
4
+ * `changes.list`, `changes.get`, `changes.discard`).
4
5
  */
5
6
 
6
7
  export const PROTOCOL_NAME = "deco-content";
7
8
 
8
- /** Minors only add; a client refuses an unknown major. */
9
- export const PROTOCOL_VERSION = { major: 1, minor: 0 } as const;
9
+ /**
10
+ * Minors only add. A client refuses another major, and a server older than
11
+ * `REQUIRED_PROTOCOL_MINOR` (1.1 added `changes.*`; 1.0 is `@decocms/blocks`
12
+ * 8.1.x and older).
13
+ */
14
+ export const PROTOCOL_VERSION = { major: 1, minor: 1 } as const;
15
+
16
+ /**
17
+ * The oldest minor this package's client talks to. Bump it only when the
18
+ * client needs a newer method.
19
+ */
20
+ export const REQUIRED_PROTOCOL_MINOR = 1;
10
21
 
11
22
  export const SCHEMA_FORMAT = "deco-meta@1";
12
23
 
@@ -123,12 +134,100 @@ export interface BlocksApplyResult {
123
134
  versions: Record<string, string | null>;
124
135
  }
125
136
 
126
- /** The four methods, by wire name. */
137
+ /**
138
+ * What a source's content is compared against. A source's content is its
139
+ * base plus its changes: `deco serve`'s base is the local git `HEAD`, the
140
+ * site editor's hosted drafts compare with the published branch.
141
+ */
142
+ export interface ChangesBase {
143
+ /** An opaque revision of the base, compared only for equality (`deco serve`: the `HEAD` commit). */
144
+ revision: string;
145
+ /** The branch the base was read from; `null` when there's none (a detached `HEAD`). */
146
+ resolvedRef: string | null;
147
+ }
148
+
149
+ /** One entry that differs from the base. */
150
+ export interface Change {
151
+ /** `set`: the entry exists and differs from the base, or is new. `delete`: it's in the base and gone now. */
152
+ kind: "set" | "delete";
153
+ /** The entry's current version, as `blocks.list` reports it (usable in `ifMatch`); `null` for a `delete`. */
154
+ version: string | null;
155
+ /**
156
+ * The entry's version in the base; `null` when the base doesn't have it (a
157
+ * new entry). Opaque: don't compare it with `version`; an entry is changed
158
+ * because it's listed.
159
+ */
160
+ baseVersion: string | null;
161
+ }
162
+
163
+ export type ChangesListParams = ReadParams;
164
+
165
+ export type ChangesListResult =
166
+ | { notModified: true; revision: string; base: ChangesBase }
167
+ | {
168
+ notModified: false;
169
+ /**
170
+ * The changes' own revision, for `ifNoneMatch`: it moves when the
171
+ * content or the base moves. Not comparable with `blocks.list`'s.
172
+ */
173
+ revision: string;
174
+ base: ChangesBase;
175
+ /** Every entry that differs from the base, by name; an unchanged entry is absent. */
176
+ changes: Record<string, Change>;
177
+ };
178
+
179
+ export interface ChangesGetParams {
180
+ /** The entries to read both sides of (at most 20). */
181
+ names: string[];
182
+ }
183
+
184
+ /** Both sides of one entry. */
185
+ export interface ChangeDetail {
186
+ /** `null`: the entry doesn't differ from the base, and `before` is `after`. */
187
+ kind: "set" | "delete" | null;
188
+ /** The entry in the base; `null` when the base doesn't have it, or it can't be read (see `diagnostics`). */
189
+ before: Record<string, unknown> | null;
190
+ /** The entry now; `null` when it's deleted, or it can't be read (see `diagnostics`). */
191
+ after: Record<string, unknown> | null;
192
+ version: string | null;
193
+ /** For an unchanged entry, equal to `version`. */
194
+ baseVersion: string | null;
195
+ }
196
+
197
+ /** A side `changes.get` couldn't read: as in `blocks.list`, plus which side. */
198
+ export type ChangeDiagnostic = Diagnostic & { side: "before" | "after" };
199
+
200
+ export interface ChangesGetResult {
201
+ base: ChangesBase;
202
+ /** Every requested name that exists in the base or now; any other name is absent. */
203
+ entries: Record<string, ChangeDetail>;
204
+ diagnostics: ChangeDiagnostic[];
205
+ }
206
+
207
+ export interface ChangesDiscardParams {
208
+ /** Entries to drop back to the base. A name without a change is a no-op. */
209
+ names: string[];
210
+ /** A version the entry must have now; `null` = must not exist. As in `blocks.apply`. */
211
+ ifMatch?: Record<string, string | null>;
212
+ }
213
+
214
+ /**
215
+ * As `blocks.apply`'s result: `revision` is the content's (`blocks.list`'s)
216
+ * revision after the discard, and `versions` every named entry's version
217
+ * after it (`null`: not in the base), plus `null` for any other spelling the
218
+ * discard deleted.
219
+ */
220
+ export type ChangesDiscardResult = BlocksApplyResult;
221
+
222
+ /** The seven methods, by wire name. */
127
223
  export interface Methods {
128
224
  describe: { params: Record<string, never> | undefined; result: DescribeResult };
129
225
  "schema.get": { params: SchemaGetParams | undefined; result: SchemaGetResult };
130
226
  "blocks.list": { params: BlocksListParams | undefined; result: BlocksListResult };
131
227
  "blocks.apply": { params: BlocksApplyParams; result: BlocksApplyResult };
228
+ "changes.list": { params: ChangesListParams | undefined; result: ChangesListResult };
229
+ "changes.get": { params: ChangesGetParams; result: ChangesGetResult };
230
+ "changes.discard": { params: ChangesDiscardParams; result: ChangesDiscardResult };
132
231
  }
133
232
 
134
233
  export type MethodName = keyof Methods;
@@ -138,6 +237,9 @@ export const METHOD_NAMES: readonly MethodName[] = [
138
237
  "schema.get",
139
238
  "blocks.list",
140
239
  "blocks.apply",
240
+ "changes.list",
241
+ "changes.get",
242
+ "changes.discard",
141
243
  ];
142
244
 
143
245
  /** A JSON-RPC request id. The protocol requires one on every request. */
package/src/v8/cli/run.ts CHANGED
@@ -42,7 +42,8 @@ Commands:
42
42
  schema turn the types in .deco/index.ts into .deco/schema.gen.json
43
43
  content turn .deco/blocks into the content module, .deco/blocks.gen.ts
44
44
  check check that every saved block fits the schema (writes nothing)
45
- serve serve .deco to the site editor on this machine, at http://localhost:4545/rpc
45
+ serve serve .deco to the site editor on this machine, at http://localhost:4545/rpc;
46
+ run it inside the site's git repository (the change list compares with HEAD)
46
47
 
47
48
  ${Object.values(COMMANDS)
48
49
  .map((c) => ` ${c.usage}`)
@@ -16,6 +16,10 @@
16
16
  * - CORS is answered for any `Origin` (reflected, with `Vary: Origin`), and
17
17
  * so are Chrome's Private/Local Network Access preflights.
18
18
  * - Every save regenerates `.deco/blocks.gen.ts`.
19
+ * - It runs only inside the site's git repository: the content's base (what
20
+ * the site editor's change list compares with, and what a discard
21
+ * restores) is the local git `HEAD`. Outside a git work tree, or without
22
+ * git installed, it refuses to start and says what to run.
19
23
  */
20
24
  import fs from "node:fs";
21
25
  import http from "node:http";
@@ -26,6 +30,7 @@ import { ErrorCode } from "../../../protocol/errors.ts";
26
30
  import { blockNameFromFile } from "../../../protocol/keys.ts";
27
31
  import { createAssetHandler } from "../../../protocol/server/assets.ts";
28
32
  import { createContentHandler } from "../../../protocol/server/index.ts";
33
+ import { checkGitWorkTree, UNBORN_REVISION } from "../../../protocol/storage/fs/git.ts";
29
34
  import { createFsStorage } from "../../../protocol/storage/fs/index.ts";
30
35
  import type { ContentStorage } from "../../../protocol/storage.ts";
31
36
  import { readSavedBlocks, writeContent } from "../content.ts";
@@ -52,6 +57,8 @@ export interface ServeOptions {
52
57
  assets?: string;
53
58
  readOnly?: boolean;
54
59
  reporter?: Reporter;
60
+ /** The git binary (default `git`, from `PATH`); tests point it elsewhere. */
61
+ git?: string;
55
62
  }
56
63
 
57
64
  export interface RunningServer {
@@ -100,6 +107,28 @@ function previewUrl(input: string): string {
100
107
  return url.pathname === "/" && !url.search && !url.hash ? url.origin : url.href;
101
108
  }
102
109
 
110
+ /**
111
+ * Refuses to serve a folder that isn't inside a git work tree: every source
112
+ * of the protocol has a base, and `deco serve`'s is the local `HEAD`.
113
+ */
114
+ async function requireGitWorkTree(root: string, git: string | undefined): Promise<void> {
115
+ const check = await checkGitWorkTree(root, { git });
116
+ if (check.status === "ok") return;
117
+ if (check.status === "missing") {
118
+ throw new CliError(
119
+ "deco serve needs git, and it isn't installed here. Install git (https://git-scm.com/downloads), " +
120
+ "then run deco serve again inside your site's git repository.",
121
+ );
122
+ }
123
+ if (check.status === "not-a-repository") {
124
+ throw new CliError(
125
+ `deco serve runs inside your site's git repository, and ${root} isn't in one. ` +
126
+ "Run it in the folder where you cloned the site, or run git init there first, then start deco serve again.",
127
+ );
128
+ }
129
+ throw new CliError(`deco serve couldn't use the git repository at ${root}: ${check.message}`);
130
+ }
131
+
103
132
  /** Start the server; resolves once it listens. */
104
133
  export async function startServer(options: ServeOptions = {}): Promise<RunningServer> {
105
134
  const reporter = options.reporter ?? consoleReporter;
@@ -113,15 +142,23 @@ export async function startServer(options: ServeOptions = {}): Promise<RunningSe
113
142
  throw new CliError(`--port must be a port number, got ${requestedPort}`);
114
143
  }
115
144
 
116
- const fsStorage = createFsStorage({ root: paths.root, readOnly, assetsDir: options.assets });
145
+ await requireGitWorkTree(paths.root, options.git);
146
+
147
+ const fsStorage = createFsStorage({
148
+ root: paths.root,
149
+ readOnly,
150
+ assetsDir: options.assets,
151
+ git: options.git,
152
+ });
117
153
  const storage: ContentStorage = {
118
154
  ...fsStorage,
119
155
  async commit(attempt) {
120
156
  const result = await fsStorage.commit(attempt);
121
157
  if (result.status !== "committed") return result;
122
158
  const names = [...Object.keys(attempt.put), ...attempt.delete].map(blockNameFromFile);
159
+ const blocks = `${names.length} block${names.length === 1 ? "" : "s"}: ${names.join(", ")}`;
123
160
  reporter.info(
124
- `saved ${names.length} block${names.length === 1 ? "" : "s"}: ${names.join(", ")}`,
161
+ attempt.reason === "discard" ? `discarded changes to ${blocks}` : `saved ${blocks}`,
125
162
  );
126
163
  // Every save changes the content, so the content module's revision
127
164
  // changes too (a revision is never reused for different content). An
@@ -210,6 +247,7 @@ export async function startServer(options: ServeOptions = {}): Promise<RunningSe
210
247
  : "no schema yet: run deco schema for typed forms";
211
248
  const count = Object.keys(readSavedBlocks(paths.blocks).blocks).length;
212
249
  const description = await storage.describe();
250
+ const base = await storage.base().catch(() => null);
213
251
  const label = (name: string) => name.padEnd(21);
214
252
  reporter.info(`${label("Deco server")}${endpoint}`);
215
253
  reporter.info(`${label("Root")}${description.root} (${schemaFile}, ${count} blocks)`);
@@ -219,6 +257,12 @@ export async function startServer(options: ServeOptions = {}): Promise<RunningSe
219
257
  : `${label("Assets")}read-only: uploads are off`,
220
258
  );
221
259
  reporter.info(`${label("Preview")}${preview}`);
260
+ if (base) {
261
+ const commit = base.revision === UNBORN_REVISION ? "no commits yet" : base.revision.slice(0, 7);
262
+ reporter.info(
263
+ `${label("Changes")}compared with ${base.resolvedRef ?? "detached HEAD"} (${commit})`,
264
+ );
265
+ }
222
266
  reporter.info(`${label("Site editor")}${siteEditorUrl}`);
223
267
 
224
268
  return {