@decocms/blocks 8.1.2 → 8.2.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.
- package/dist/protocol/client.d.ts +17 -4
- package/dist/protocol/client.d.ts.map +1 -1
- package/dist/protocol/client.js +46 -10
- package/dist/protocol/client.js.map +1 -1
- package/dist/protocol/conformance/cases/changes.d.ts +3 -0
- package/dist/protocol/conformance/cases/changes.d.ts.map +1 -0
- package/dist/protocol/conformance/cases/changes.js +295 -0
- package/dist/protocol/conformance/cases/changes.js.map +1 -0
- package/dist/protocol/conformance/context.d.ts +14 -0
- package/dist/protocol/conformance/context.d.ts.map +1 -1
- package/dist/protocol/conformance/context.js.map +1 -1
- package/dist/protocol/conformance/index.d.ts.map +1 -1
- package/dist/protocol/conformance/index.js +4 -1
- package/dist/protocol/conformance/index.js.map +1 -1
- package/dist/protocol/errors.d.ts +26 -0
- package/dist/protocol/errors.d.ts.map +1 -1
- package/dist/protocol/errors.js.map +1 -1
- package/dist/protocol/index.d.ts +4 -2
- package/dist/protocol/index.d.ts.map +1 -1
- package/dist/protocol/index.js +4 -2
- package/dist/protocol/index.js.map +1 -1
- package/dist/protocol/params.d.ts +4 -2
- package/dist/protocol/params.d.ts.map +1 -1
- package/dist/protocol/params.js +11 -1
- package/dist/protocol/params.js.map +1 -1
- package/dist/protocol/server/assets.d.ts +1 -1
- package/dist/protocol/server/assets.js +1 -1
- package/dist/protocol/server/core.d.ts +12 -1
- package/dist/protocol/server/core.d.ts.map +1 -1
- package/dist/protocol/server/core.js +8 -0
- package/dist/protocol/server/core.js.map +1 -1
- package/dist/protocol/server/index.d.ts +1 -1
- package/dist/protocol/server/index.js +1 -1
- package/dist/protocol/server/methods/apply.d.ts +37 -0
- package/dist/protocol/server/methods/apply.d.ts.map +1 -1
- package/dist/protocol/server/methods/apply.js +4 -3
- package/dist/protocol/server/methods/apply.js.map +1 -1
- package/dist/protocol/server/methods/changes.d.ts +6 -0
- package/dist/protocol/server/methods/changes.d.ts.map +1 -0
- package/dist/protocol/server/methods/changes.js +381 -0
- package/dist/protocol/server/methods/changes.js.map +1 -0
- package/dist/protocol/server/rpc.d.ts.map +1 -1
- package/dist/protocol/server/rpc.js +7 -0
- package/dist/protocol/server/rpc.js.map +1 -1
- package/dist/protocol/storage/fs/git.d.ts +51 -0
- package/dist/protocol/storage/fs/git.d.ts.map +1 -0
- package/dist/protocol/storage/fs/git.js +274 -0
- package/dist/protocol/storage/fs/git.js.map +1 -0
- package/dist/protocol/storage/fs/index.d.ts +2 -0
- package/dist/protocol/storage/fs/index.d.ts.map +1 -1
- package/dist/protocol/storage/fs/index.js +34 -0
- package/dist/protocol/storage/fs/index.js.map +1 -1
- package/dist/protocol/storage/memory.d.ts +10 -0
- package/dist/protocol/storage/memory.d.ts.map +1 -1
- package/dist/protocol/storage/memory.js +45 -0
- package/dist/protocol/storage/memory.js.map +1 -1
- package/dist/protocol/storage.d.ts +49 -1
- package/dist/protocol/storage.d.ts.map +1 -1
- package/dist/protocol/storage.js.map +1 -1
- package/dist/protocol/types.d.ts +105 -4
- package/dist/protocol/types.d.ts.map +1 -1
- package/dist/protocol/types.js +16 -3
- package/dist/protocol/types.js.map +1 -1
- package/dist/v8/cli/run.d.ts.map +1 -1
- package/dist/v8/cli/run.js +2 -1
- package/dist/v8/cli/run.js.map +1 -1
- package/dist/v8/cli/serve/server.d.ts +2 -0
- package/dist/v8/cli/serve/server.d.ts.map +1 -1
- package/dist/v8/cli/serve/server.js +37 -2
- package/dist/v8/cli/serve/server.js.map +1 -1
- package/package.json +1 -1
- package/src/protocol/client.ts +81 -13
- package/src/protocol/conformance/cases/changes.ts +362 -0
- package/src/protocol/conformance/context.ts +12 -0
- package/src/protocol/conformance/index.ts +4 -1
- package/src/protocol/errors.ts +17 -0
- package/src/protocol/index.ts +4 -2
- package/src/protocol/params.ts +26 -3
- package/src/protocol/server/assets.ts +1 -1
- package/src/protocol/server/core.ts +9 -0
- package/src/protocol/server/index.ts +1 -1
- package/src/protocol/server/methods/apply.ts +8 -4
- package/src/protocol/server/methods/changes.ts +489 -0
- package/src/protocol/server/rpc.ts +7 -0
- package/src/protocol/storage/fs/git.ts +307 -0
- package/src/protocol/storage/fs/index.ts +40 -0
- package/src/protocol/storage/memory.ts +57 -0
- package/src/protocol/storage.ts +51 -1
- package/src/protocol/types.ts +106 -4
- package/src/v8/cli/run.ts +2 -1
- package/src/v8/cli/serve/server.ts +46 -2
package/src/protocol/types.ts
CHANGED
|
@@ -1,12 +1,23 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The content protocol's method types: JSON-RPC 2.0 over one HTTP endpoint,
|
|
3
|
-
*
|
|
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
|
-
/**
|
|
9
|
-
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
-
|
|
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 {
|