@decocms/blocks 7.72.0 → 8.1.0-next.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 (148) hide show
  1. package/bin/deco.js +13 -0
  2. package/package.json +32 -3
  3. package/src/cms/schema.ts +1 -1
  4. package/src/hooks/LiveControls.tsx +2 -0
  5. package/src/hooks/useLoadMore.ts +2 -0
  6. package/src/index.ts +37 -0
  7. package/src/protocol/assets.ts +124 -0
  8. package/src/protocol/canonical.ts +7 -0
  9. package/src/protocol/ciphertext.ts +6 -0
  10. package/src/protocol/client.ts +170 -0
  11. package/src/protocol/conformance/cases/assets.ts +81 -0
  12. package/src/protocol/conformance/cases/guards.ts +314 -0
  13. package/src/protocol/conformance/cases/reads.ts +168 -0
  14. package/src/protocol/conformance/cases/types.ts +9 -0
  15. package/src/protocol/conformance/cases/wire.ts +138 -0
  16. package/src/protocol/conformance/cases/writes.ts +345 -0
  17. package/src/protocol/conformance/contentHashFixtures.ts +79 -0
  18. package/src/protocol/conformance/context.ts +222 -0
  19. package/src/protocol/conformance/index.ts +140 -0
  20. package/src/protocol/errors.ts +142 -0
  21. package/src/protocol/index.ts +39 -0
  22. package/src/protocol/keys.ts +279 -0
  23. package/src/protocol/params.ts +67 -0
  24. package/src/protocol/secrets.ts +231 -0
  25. package/src/protocol/server/assets.ts +119 -0
  26. package/src/protocol/server/auth.ts +49 -0
  27. package/src/protocol/server/bodyCache.ts +84 -0
  28. package/src/protocol/server/content.ts +175 -0
  29. package/src/protocol/server/core.ts +112 -0
  30. package/src/protocol/server/handler.ts +102 -0
  31. package/src/protocol/server/http.ts +139 -0
  32. package/src/protocol/server/index.ts +11 -0
  33. package/src/protocol/server/methods/apply.ts +341 -0
  34. package/src/protocol/server/methods/read.ts +156 -0
  35. package/src/protocol/server/rpc.ts +136 -0
  36. package/src/protocol/storage/fs/hash.ts +21 -0
  37. package/src/protocol/storage/fs/index.ts +338 -0
  38. package/src/protocol/storage/fs/lock.ts +68 -0
  39. package/src/protocol/storage/fs/transaction.ts +183 -0
  40. package/src/protocol/storage/fs/unsupported.ts +15 -0
  41. package/src/protocol/storage/memory.ts +238 -0
  42. package/src/protocol/storage.ts +182 -0
  43. package/src/protocol/types.ts +172 -0
  44. package/src/v8/analytics.ts +50 -0
  45. package/src/v8/background.ts +107 -0
  46. package/src/v8/builtins/data.ts +23 -0
  47. package/src/v8/builtins/index.ts +26 -0
  48. package/src/v8/builtins/lazy.ts +23 -0
  49. package/src/v8/builtins/legacy.ts +65 -0
  50. package/src/v8/builtins/matchers.ts +31 -0
  51. package/src/v8/builtins/multivariate.ts +25 -0
  52. package/src/v8/builtins/secret.ts +82 -0
  53. package/src/v8/canonical.ts +117 -0
  54. package/src/v8/ciphertext.ts +158 -0
  55. package/src/v8/cli/builtins.ts +20 -0
  56. package/src/v8/cli/check/index.ts +774 -0
  57. package/src/v8/cli/check/messages.ts +168 -0
  58. package/src/v8/cli/content.ts +287 -0
  59. package/src/v8/cli/index.ts +17 -0
  60. package/src/v8/cli/log.ts +18 -0
  61. package/src/v8/cli/main.ts +12 -0
  62. package/src/v8/cli/root.ts +66 -0
  63. package/src/v8/cli/run.ts +236 -0
  64. package/src/v8/cli/schema/builtinSchemas.ts +236 -0
  65. package/src/v8/cli/schema/generate.ts +507 -0
  66. package/src/v8/cli/schema/index.ts +63 -0
  67. package/src/v8/cli/schema/tsProgram.ts +497 -0
  68. package/src/v8/cli/schema/typeToSchema.ts +689 -0
  69. package/src/v8/cli/serve/server.ts +303 -0
  70. package/src/v8/cli/watch.ts +86 -0
  71. package/src/v8/client.ts +147 -0
  72. package/src/v8/cms.ts +237 -0
  73. package/src/v8/content.ts +195 -0
  74. package/src/v8/draft.ts +136 -0
  75. package/src/v8/errors.ts +59 -0
  76. package/src/v8/fetch.ts +152 -0
  77. package/src/v8/identity.ts +65 -0
  78. package/src/v8/index.ts +39 -0
  79. package/src/v8/json.ts +74 -0
  80. package/src/v8/matchRoute.ts +204 -0
  81. package/src/v8/remoteLoader.ts +282 -0
  82. package/src/v8/resolver.ts +278 -0
  83. package/src/v8/secrets.ts +17 -0
  84. package/src/v8/telemetry.ts +533 -0
  85. package/src/v8/types.ts +240 -0
  86. package/src/cms/blockSource.test.ts +0 -76
  87. package/src/cms/client.browserBundle.test.ts +0 -44
  88. package/src/cms/deferredTrigger.test.ts +0 -32
  89. package/src/cms/draftSource.test.ts +0 -519
  90. package/src/cms/layoutCacheRace.test.ts +0 -181
  91. package/src/cms/loadDecofileDirectory.test.ts +0 -109
  92. package/src/cms/loader.test.ts +0 -557
  93. package/src/cms/registry.test.ts +0 -110
  94. package/src/cms/renderJson.test.ts +0 -167
  95. package/src/cms/resolve.test.ts +0 -1492
  96. package/src/cms/schema.test.ts +0 -356
  97. package/src/cms/sectionLoaderContext.test.ts +0 -111
  98. package/src/cms/sectionLoaders.test.ts +0 -625
  99. package/src/cms/sectionMixins.test.ts +0 -167
  100. package/src/cms/stickyFlags.test.ts +0 -117
  101. package/src/flags/flags.test.ts +0 -148
  102. package/src/hooks/Image.test.ts +0 -239
  103. package/src/hooks/RenderSection.test.tsx +0 -81
  104. package/src/hooks/Stats.test.ts +0 -112
  105. package/src/hooks/useLoadMore.test.ts +0 -205
  106. package/src/matchers/builtins.test.ts +0 -318
  107. package/src/matchers/override.test.ts +0 -205
  108. package/src/middleware/hydrationContext.test.ts +0 -61
  109. package/src/middleware/observability.test.ts +0 -335
  110. package/src/middleware/validateSection.test.ts +0 -147
  111. package/src/preview/DraftPreviewBadge.render.test.tsx +0 -67
  112. package/src/preview/DraftPreviewBadge.test.ts +0 -55
  113. package/src/sdk/abTesting.test.ts +0 -381
  114. package/src/sdk/cacheHeaders.test.ts +0 -258
  115. package/src/sdk/cacheStorage.test.ts +0 -242
  116. package/src/sdk/cachedLoader.test.ts +0 -122
  117. package/src/sdk/cachedLoaderMaxBytes.test.ts +0 -23
  118. package/src/sdk/cachedLoaderModule.test.ts +0 -209
  119. package/src/sdk/cachedLoaderSizeMetric.test.ts +0 -93
  120. package/src/sdk/cn.test.ts +0 -34
  121. package/src/sdk/composite.test.ts +0 -121
  122. package/src/sdk/cookie.test.ts +0 -108
  123. package/src/sdk/crypto.test.ts +0 -65
  124. package/src/sdk/deepOmit.test.ts +0 -45
  125. package/src/sdk/encoding.test.ts +0 -71
  126. package/src/sdk/env.test.ts +0 -33
  127. package/src/sdk/experiments.test.ts +0 -328
  128. package/src/sdk/fetchCache.test.ts +0 -164
  129. package/src/sdk/flags.test.ts +0 -91
  130. package/src/sdk/http.test.ts +0 -71
  131. package/src/sdk/inflightTimeout.test.ts +0 -35
  132. package/src/sdk/instrumentedFetch.test.ts +0 -559
  133. package/src/sdk/invoke.test.ts +0 -115
  134. package/src/sdk/logger.test.ts +0 -432
  135. package/src/sdk/otel.test.ts +0 -691
  136. package/src/sdk/otelAdapters.test.ts +0 -89
  137. package/src/sdk/otelHttpLog.test.ts +0 -457
  138. package/src/sdk/otelHttpMeter.test.ts +0 -395
  139. package/src/sdk/otelHttpTracer.test.ts +0 -474
  140. package/src/sdk/replaceStream.test.ts +0 -117
  141. package/src/sdk/requestContextStorage.browser.test.ts +0 -29
  142. package/src/sdk/splitExactRedirects.test.ts +0 -154
  143. package/src/sdk/urlRedaction.test.ts +0 -73
  144. package/src/sdk/urlUtils.test.ts +0 -34
  145. package/src/sdk/useDevice.test.ts +0 -130
  146. package/src/sdk/useScript.test.ts +0 -128
  147. package/src/sdk/useSuggestions.test.ts +0 -230
  148. package/tsconfig.json +0 -7
@@ -0,0 +1,140 @@
1
+ /**
2
+ * `@decocms/blocks/protocol/conformance`: a black-box test suite any
3
+ * content-protocol endpoint runs over HTTP, which is how the filesystem
4
+ * storage, the site editor's GitHub backend and any other backend are kept to
5
+ * the same contract.
6
+ *
7
+ * Run it with any test runner:
8
+ *
9
+ * ```ts
10
+ * import { describe, it } from "vitest";
11
+ * import { defineConformanceSuite } from "@decocms/blocks/protocol/conformance";
12
+ *
13
+ * defineConformanceSuite({ describe, it }, { endpoint: "http://127.0.0.1:4545/rpc", token });
14
+ * ```
15
+ *
16
+ * or collect a report with `runConformance(options)`. The suite writes only
17
+ * names under its own prefix and deletes them after each case (uploads, which
18
+ * the protocol can't delete, stay in the asset folder). Cases that
19
+ * don't apply to an endpoint (a read-only one, one without request keys)
20
+ * skip themselves. Browser-safe: it only needs `fetch`.
21
+ */
22
+ import { assetCases } from "./cases/assets";
23
+ import { guardCases } from "./cases/guards";
24
+ import { readCases } from "./cases/reads";
25
+ import type { ConformanceCase } from "./cases/types";
26
+ import { wireCases } from "./cases/wire";
27
+ import { writeCases } from "./cases/writes";
28
+ import { ConformanceContext, type ConformanceOptions, SkipCase } from "./context";
29
+
30
+ export type { ConformanceCase } from "./cases/types";
31
+ export { type ContentHashFixture, contentHashFixtures } from "./contentHashFixtures";
32
+ export type { ConformanceOptions } from "./context";
33
+
34
+ /** Every conformance case, in the order they run. */
35
+ export const conformanceCases: readonly ConformanceCase[] = [
36
+ ...wireCases,
37
+ ...readCases,
38
+ ...writeCases,
39
+ ...guardCases,
40
+ ...assetCases,
41
+ ];
42
+
43
+ function defaultPrefix(): string {
44
+ return `conformance-${Math.random().toString(36).slice(2, 8)}`;
45
+ }
46
+
47
+ export interface CaseOutcome {
48
+ id: string;
49
+ title: string;
50
+ status: "passed" | "failed" | "skipped";
51
+ /** Why it failed or was skipped. */
52
+ message?: string;
53
+ }
54
+
55
+ /** Runs one case with its own names, cleaning them up afterwards. */
56
+ async function runCase(
57
+ testCase: ConformanceCase,
58
+ options: ConformanceOptions,
59
+ prefix: string,
60
+ ): Promise<CaseOutcome> {
61
+ const ctx = new ConformanceContext(options, prefix);
62
+ try {
63
+ await testCase.run(ctx);
64
+ return { id: testCase.id, title: testCase.title, status: "passed" };
65
+ } catch (error) {
66
+ if (error instanceof SkipCase) {
67
+ return { id: testCase.id, title: testCase.title, status: "skipped", message: error.message };
68
+ }
69
+ return {
70
+ id: testCase.id,
71
+ title: testCase.title,
72
+ status: "failed",
73
+ message: error instanceof Error ? error.message : String(error),
74
+ };
75
+ } finally {
76
+ await ctx.cleanup();
77
+ }
78
+ }
79
+
80
+ export interface ConformanceReport {
81
+ passed: number;
82
+ failed: number;
83
+ skipped: number;
84
+ outcomes: CaseOutcome[];
85
+ }
86
+
87
+ /** Runs every case (or the ones `filter` keeps) in order and reports the outcomes. */
88
+ export async function runConformance(
89
+ options: ConformanceOptions,
90
+ filter: (testCase: ConformanceCase) => boolean = () => true,
91
+ ): Promise<ConformanceReport> {
92
+ const prefix = options.namePrefix ?? defaultPrefix();
93
+ const outcomes: CaseOutcome[] = [];
94
+ let index = 0;
95
+ for (const testCase of conformanceCases.filter(filter)) {
96
+ outcomes.push(await runCase(testCase, options, `${prefix}-${++index}`));
97
+ }
98
+ const count = (status: CaseOutcome["status"]) =>
99
+ outcomes.filter((o) => o.status === status).length;
100
+ return { passed: count("passed"), failed: count("failed"), skipped: count("skipped"), outcomes };
101
+ }
102
+
103
+ /** The parts of a test runner the suite registers itself with (vitest, jest, node:test, bun:test). */
104
+ export interface TestRegistrar {
105
+ describe(name: string, body: () => void): void;
106
+ it(
107
+ name: string,
108
+ body: (context?: { skip?: (note?: string) => void }) => Promise<void>,
109
+ timeout?: number,
110
+ ): void;
111
+ }
112
+
113
+ /** Registers one test per conformance case with a test runner. */
114
+ export function defineConformanceSuite(
115
+ runner: TestRegistrar,
116
+ options: ConformanceOptions | (() => ConformanceOptions),
117
+ suiteName = "content protocol conformance",
118
+ filter: (testCase: ConformanceCase) => boolean = () => true,
119
+ ): void {
120
+ const resolve = typeof options === "function" ? options : () => options;
121
+ const prefix = defaultPrefix();
122
+ runner.describe(suiteName, () => {
123
+ conformanceCases.filter(filter).forEach((testCase, index) => {
124
+ runner.it(
125
+ `${testCase.id}: ${testCase.title}`,
126
+ async (context) => {
127
+ const resolved = resolve();
128
+ const outcome = await runCase(
129
+ testCase,
130
+ resolved,
131
+ `${resolved.namePrefix ?? prefix}-${index + 1}`,
132
+ );
133
+ if (outcome.status === "failed") throw new Error(outcome.message);
134
+ if (outcome.status === "skipped") context?.skip?.(outcome.message);
135
+ },
136
+ 60_000,
137
+ );
138
+ });
139
+ });
140
+ }
@@ -0,0 +1,142 @@
1
+ /**
2
+ * Content-protocol errors. Every failure travels as a JSON-RPC 2.0 `error`
3
+ * object (HTTP 200), except a missing or invalid bearer token (401) and a body
4
+ * over the size limit (413), which apply to the whole batch.
5
+ */
6
+
7
+ export const ErrorCode = {
8
+ // Standard JSON-RPC 2.0 codes.
9
+ ParseError: -32700,
10
+ InvalidRequest: -32600,
11
+ MethodNotFound: -32601,
12
+ InvalidParams: -32602,
13
+ InternalError: -32603,
14
+ // Content-protocol codes.
15
+ NotFound: -32001,
16
+ Conflict: -32002,
17
+ InvalidBlock: -32003,
18
+ ReadOnly: -32005,
19
+ Unsupported: -32006,
20
+ LimitExceeded: -32007,
21
+ Unavailable: -32008,
22
+ Unauthorized: -32010,
23
+ Forbidden: -32011,
24
+ } as const;
25
+
26
+ export type ErrorCodeName = keyof typeof ErrorCode;
27
+ export type ErrorCodeValue = (typeof ErrorCode)[ErrorCodeName];
28
+
29
+ /** The JSON-RPC `error` object. */
30
+ export interface RpcErrorObject {
31
+ code: number;
32
+ message: string;
33
+ data?: unknown;
34
+ }
35
+
36
+ /** One entry's failed `ifMatch` guard. */
37
+ export interface VersionMismatch {
38
+ expected: string | null;
39
+ actual: string | null;
40
+ }
41
+
42
+ /** `error.data` of a Conflict (-32002). */
43
+ export interface ConflictData {
44
+ entries?: Record<string, VersionMismatch>;
45
+ schema?: { expected: string; actual: string | null };
46
+ }
47
+
48
+ /** One rule a `blocks.apply` breaks. */
49
+ export interface BlockViolation {
50
+ /** The entry name the violation is about. */
51
+ name: string;
52
+ /** A JSON Pointer inside the entry, when the violation is about one value. */
53
+ pointer?: string;
54
+ rule: string;
55
+ message: string;
56
+ }
57
+
58
+ /** `error.data` of an InvalidBlock (-32003). */
59
+ export interface InvalidBlockData {
60
+ violations: BlockViolation[];
61
+ }
62
+
63
+ /** `error.data` of an Unavailable (-32008). */
64
+ export interface UnavailableData {
65
+ retryAfterMs?: number;
66
+ }
67
+
68
+ /**
69
+ * An error a method fails with. The server turns it into the JSON-RPC
70
+ * `error` object; the client throws it back.
71
+ */
72
+ export class ContentProtocolError extends Error {
73
+ readonly code: number;
74
+ readonly data: unknown;
75
+
76
+ constructor(code: number, message: string, data?: unknown) {
77
+ super(message);
78
+ this.name = "ContentProtocolError";
79
+ this.code = code;
80
+ this.data = data;
81
+ }
82
+
83
+ toJSON(): RpcErrorObject {
84
+ return this.data === undefined
85
+ ? { code: this.code, message: this.message }
86
+ : { code: this.code, message: this.message, data: this.data };
87
+ }
88
+
89
+ static from(error: RpcErrorObject): ContentProtocolError {
90
+ return new ContentProtocolError(error.code, error.message, error.data);
91
+ }
92
+ }
93
+
94
+ export const notFound = (message: string) => new ContentProtocolError(ErrorCode.NotFound, message);
95
+
96
+ export const conflict = (data: ConflictData) =>
97
+ new ContentProtocolError(ErrorCode.Conflict, "a precondition failed", data);
98
+
99
+ export const invalidBlock = (violations: BlockViolation[]) =>
100
+ new ContentProtocolError(
101
+ ErrorCode.InvalidBlock,
102
+ violations.length === 1
103
+ ? `invalid block "${violations[0]!.name}": ${violations[0]!.message}`
104
+ : `${violations.length} invalid blocks`,
105
+ { violations } satisfies InvalidBlockData,
106
+ );
107
+
108
+ export const readOnly = () =>
109
+ new ContentProtocolError(ErrorCode.ReadOnly, "this endpoint is read-only");
110
+
111
+ export const unsupported = (message: string) =>
112
+ new ContentProtocolError(ErrorCode.Unsupported, message);
113
+
114
+ export const limitExceeded = (message: string, data?: Record<string, unknown>) =>
115
+ new ContentProtocolError(ErrorCode.LimitExceeded, message, data);
116
+
117
+ export const unavailable = (message: string, retryAfterMs?: number) =>
118
+ new ContentProtocolError(
119
+ ErrorCode.Unavailable,
120
+ message,
121
+ retryAfterMs === undefined ? undefined : ({ retryAfterMs } satisfies UnavailableData),
122
+ );
123
+
124
+ export const invalidParams = (message: string, data?: unknown) =>
125
+ new ContentProtocolError(ErrorCode.InvalidParams, message, data);
126
+
127
+ export const invalidRequest = (message: string) =>
128
+ new ContentProtocolError(ErrorCode.InvalidRequest, message);
129
+
130
+ export const methodNotFound = (method: string) =>
131
+ new ContentProtocolError(ErrorCode.MethodNotFound, `unknown method "${method}"`);
132
+
133
+ export const parseError = () => new ContentProtocolError(ErrorCode.ParseError, "invalid JSON");
134
+
135
+ export const internalError = () =>
136
+ new ContentProtocolError(ErrorCode.InternalError, "internal error");
137
+
138
+ export const unauthorized = () =>
139
+ new ContentProtocolError(ErrorCode.Unauthorized, "missing or invalid bearer token");
140
+
141
+ export const forbidden = () =>
142
+ new ContentProtocolError(ErrorCode.Forbidden, "not allowed for this project");
@@ -0,0 +1,39 @@
1
+ /**
2
+ * `@decocms/blocks/protocol`: the content protocol's method types, errors,
3
+ * client and file-name rule. Browser-safe.
4
+ *
5
+ * The protocol is how the site editor reads and writes saved blocks without
6
+ * running a site's code: JSON-RPC 2.0 over one HTTP endpoint with four
7
+ * methods — `describe`, `schema.get`, `blocks.list` and `blocks.apply`.
8
+ *
9
+ * Subpaths:
10
+ * - `@decocms/blocks/protocol/keys` — the file-name rule (also re-exported here)
11
+ * - `@decocms/blocks/protocol/server` — `createContentHandler(storage)`
12
+ * - `@decocms/blocks/protocol/storage/fs` — the filesystem storage (Node only)
13
+ * - `@decocms/blocks/protocol/conformance` — a black-box test suite over HTTP
14
+ *
15
+ * The SDK's runtime never imports the protocol, so it never reaches an app
16
+ * bundle. The canonical hash it re-exports is the SDK's own dependency-free
17
+ * leaf module (see ./canonical.ts).
18
+ */
19
+ export {
20
+ APPLY_DIGEST_DOMAIN,
21
+ applyRequestDigest,
22
+ CanonicalJsonError,
23
+ CONTENT_HASH_FORMAT,
24
+ canonicalJson,
25
+ computeContentRevision,
26
+ sha256Hex,
27
+ } from "./canonical";
28
+ export {
29
+ assertSupportedEndpoint,
30
+ type BatchCall,
31
+ type BatchOutcome,
32
+ type ContentClient,
33
+ type ContentClientOptions,
34
+ createContentClient,
35
+ } from "./client";
36
+ export * from "./errors";
37
+ export * from "./keys";
38
+ export * from "./storage";
39
+ export * from "./types";
@@ -0,0 +1,279 @@
1
+ /**
2
+ * The one file-name rule for saved blocks (`@decocms/blocks/protocol/keys`).
3
+ *
4
+ * The site editor, `deco serve` and `deco content` all import this module, so
5
+ * an entry the site editor edits is the entry the app renders:
6
+ *
7
+ * - **Name to file:** `encodeURIComponent(name) + ".json"`, directly in
8
+ * `.deco/blocks` (no subfolders).
9
+ * - **File to name:** decode the file name, without `.json`, exactly once. If
10
+ * decoding fails, the raw name is the entry name.
11
+ * - **Two spellings of one name** (files that decode to the same name after
12
+ * repeated decoding): one wins — the file whose entry has a `path`, then the
13
+ * one that took more decoding, then the lowest file name. The others are
14
+ * reported as diagnostics; a write overwrites the winning spelling and
15
+ * deletes the others in the same commit.
16
+ * - **File content:** `JSON.stringify(entry, null, 2)` plus a newline, UTF-8.
17
+ *
18
+ * Ported from the v7 `blocks-cli/scripts/lib/blocks-dedupe.ts` and
19
+ * `blocks/src/cms/loadDecofileDirectory.ts` (`parseBlockId`), with the mtime
20
+ * tie-break dropped: a fresh clone gives every file the same mtime, and the
21
+ * rule must give the same answer on GitHub, where there is no mtime.
22
+ *
23
+ * Browser-safe: no Node APIs.
24
+ */
25
+
26
+ /** The extension every saved-block file carries. */
27
+ export const BLOCK_FILE_EXTENSION = ".json";
28
+
29
+ /**
30
+ * The longest encoded name (without `.json`) the site editor can save, so the
31
+ * file fits a 255-byte file-name limit.
32
+ */
33
+ export const MAX_ENCODED_NAME_BYTES = 250;
34
+
35
+ /** Windows device names: a file whose stem is one of these can't be created on Windows. */
36
+ const WINDOWS_DEVICE_NAMES = new Set([
37
+ "CON",
38
+ "PRN",
39
+ "AUX",
40
+ "NUL",
41
+ ...Array.from({ length: 9 }, (_, i) => `COM${i + 1}`),
42
+ ...Array.from({ length: 9 }, (_, i) => `LPT${i + 1}`),
43
+ ]);
44
+
45
+ /** Extensions of source modules: a saved block ending in one would shadow a module. */
46
+ const SOURCE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
47
+
48
+ const utf8 = new TextEncoder();
49
+
50
+ /** `encodeURIComponent(name) + ".json"`: the file a saved block named `name` is stored in. */
51
+ export function blockFileName(name: string): string {
52
+ return `${encodeURIComponent(name)}${BLOCK_FILE_EXTENSION}`;
53
+ }
54
+
55
+ /**
56
+ * True when `file` is a saved-block file name: it ends in `.json`, has a stem,
57
+ * isn't in a folder and isn't a dotfile (hidden files are never entries).
58
+ */
59
+ export function isBlockFileName(file: string): boolean {
60
+ return (
61
+ file.endsWith(BLOCK_FILE_EXTENSION) &&
62
+ !file.startsWith(".") &&
63
+ file.length > BLOCK_FILE_EXTENSION.length &&
64
+ !file.includes("/") &&
65
+ !file.includes("\\")
66
+ );
67
+ }
68
+
69
+ function stem(file: string): string {
70
+ return file.endsWith(BLOCK_FILE_EXTENSION) ? file.slice(0, -BLOCK_FILE_EXTENSION.length) : file;
71
+ }
72
+
73
+ /**
74
+ * The entry name stored in `file`: the stem decoded exactly once. A stem that
75
+ * isn't valid percent-encoding (a page literally named `50% off`) is the name
76
+ * as it stands.
77
+ */
78
+ export function blockNameFromFile(file: string): string {
79
+ const raw = stem(file);
80
+ try {
81
+ return decodeURIComponent(raw);
82
+ } catch {
83
+ return raw;
84
+ }
85
+ }
86
+
87
+ /**
88
+ * Decodes `file`'s stem repeatedly until it stops changing, returning the
89
+ * fully decoded name (the spelling-group key) and how many decodes it took.
90
+ */
91
+ export function fullyDecodeFileName(file: string): { name: string; passes: number } {
92
+ let name = stem(file);
93
+ let passes = 0;
94
+ while (name.includes("%")) {
95
+ let next: string;
96
+ try {
97
+ next = decodeURIComponent(name);
98
+ } catch {
99
+ break;
100
+ }
101
+ if (next === name) break;
102
+ name = next;
103
+ passes++;
104
+ }
105
+ return { name, passes };
106
+ }
107
+
108
+ /** The spelling-group key of a saved-block name: every file of the group decodes to it. */
109
+ export function spellingKey(name: string): string {
110
+ return fullyDecodeFileName(blockFileName(name)).name;
111
+ }
112
+
113
+ /** `JSON.stringify(entry, null, 2)` plus a newline: the bytes a saved block is stored as. */
114
+ export function serializeBlock(entry: unknown): string {
115
+ return `${JSON.stringify(entry, null, 2)}\n`;
116
+ }
117
+
118
+ /** True when a parsed entry is a page-like entry: it has a non-empty string `path`. */
119
+ export function entryHasPath(entry: unknown): boolean {
120
+ return (
121
+ typeof entry === "object" &&
122
+ entry !== null &&
123
+ !Array.isArray(entry) &&
124
+ typeof (entry as { path?: unknown }).path === "string" &&
125
+ (entry as { path: string }).path.length > 0
126
+ );
127
+ }
128
+
129
+ /** One file that holds (a spelling of) a saved block. */
130
+ export interface SpellingCandidate {
131
+ file: string;
132
+ /** Whether the file's entry has a non-empty `path`. */
133
+ hasPath: boolean;
134
+ }
135
+
136
+ /** Orders two spellings of one name: negative when `a` wins. */
137
+ export function compareSpellings(a: SpellingCandidate, b: SpellingCandidate): number {
138
+ if (a.hasPath !== b.hasPath) return a.hasPath ? -1 : 1;
139
+ const passesA = fullyDecodeFileName(a.file).passes;
140
+ const passesB = fullyDecodeFileName(b.file).passes;
141
+ if (passesA !== passesB) return passesB - passesA;
142
+ if (a.file === b.file) return 0;
143
+ return a.file < b.file ? -1 : 1;
144
+ }
145
+
146
+ /** The winner of one spelling group and the files it shadows. */
147
+ export interface ResolvedSpelling<T extends SpellingCandidate = SpellingCandidate> {
148
+ /** The entry name: the winning file's stem decoded exactly once. */
149
+ name: string;
150
+ winner: T;
151
+ /** The other spellings, best first. */
152
+ shadowed: T[];
153
+ }
154
+
155
+ /**
156
+ * Groups candidate files by spelling key and picks one winner per group.
157
+ * Returns the groups keyed by entry name, in file-name order of the winners.
158
+ */
159
+ export function resolveSpellings<T extends SpellingCandidate>(
160
+ candidates: readonly T[],
161
+ ): Map<string, ResolvedSpelling<T>> {
162
+ const groups = new Map<string, T[]>();
163
+ for (const candidate of candidates) {
164
+ const key = fullyDecodeFileName(candidate.file).name;
165
+ const group = groups.get(key);
166
+ if (group) group.push(candidate);
167
+ else groups.set(key, [candidate]);
168
+ }
169
+ const winners: ResolvedSpelling<T>[] = [];
170
+ for (const group of groups.values()) {
171
+ const [winner, ...shadowed] = [...group].sort(compareSpellings);
172
+ if (!winner) continue;
173
+ winners.push({ name: blockNameFromFile(winner.file), winner, shadowed });
174
+ }
175
+ winners.sort((a, b) =>
176
+ a.winner.file < b.winner.file ? -1 : a.winner.file > b.winner.file ? 1 : 0,
177
+ );
178
+ return new Map(winners.map((w) => [w.name, w]));
179
+ }
180
+
181
+ /** Why a name can't be saved. */
182
+ export type NameViolationReason =
183
+ | "empty"
184
+ | "invalid-character"
185
+ | "dot-dot"
186
+ | "leading-dot"
187
+ | "too-long"
188
+ | "case-collision"
189
+ | "device-name"
190
+ | "reserved"
191
+ | "source-extension";
192
+
193
+ export interface NameViolation {
194
+ reason: NameViolationReason;
195
+ message: string;
196
+ }
197
+
198
+ export interface NameCheckOptions {
199
+ /**
200
+ * The names of the entries that already exist. A name that isn't one of
201
+ * them is new, and a new name that differs from an existing one only in
202
+ * letter case is refused.
203
+ */
204
+ existingNames?: Iterable<string>;
205
+ }
206
+
207
+ /**
208
+ * Checks whether the site editor may save an entry under `name`. Returns
209
+ * every rule the name breaks (empty when it can be saved).
210
+ */
211
+ export function checkBlockName(name: string, options: NameCheckOptions = {}): NameViolation[] {
212
+ const violations: NameViolation[] = [];
213
+ if (name.length === 0) {
214
+ return [{ reason: "empty", message: "the name is empty" }];
215
+ }
216
+ if (name.includes("\\") || name.includes("\0")) {
217
+ violations.push({
218
+ reason: "invalid-character",
219
+ message: "the name contains a backslash or a NUL character",
220
+ });
221
+ }
222
+ if (name.includes("..")) {
223
+ violations.push({ reason: "dot-dot", message: 'the name contains ".."' });
224
+ }
225
+ if (name.startsWith(".")) {
226
+ violations.push({
227
+ reason: "leading-dot",
228
+ message: 'the name starts with ".", which would make its file hidden',
229
+ });
230
+ }
231
+ if (name === "__proto__") {
232
+ violations.push({ reason: "reserved", message: 'the name "__proto__" is reserved' });
233
+ }
234
+ const encoded = encodeURIComponent(name);
235
+ if (utf8.encode(encoded).byteLength > MAX_ENCODED_NAME_BYTES) {
236
+ violations.push({
237
+ reason: "too-long",
238
+ message: `the encoded name is over ${MAX_ENCODED_NAME_BYTES} bytes`,
239
+ });
240
+ }
241
+ const deviceStem = encoded.split(".")[0]!.toUpperCase();
242
+ if (WINDOWS_DEVICE_NAMES.has(deviceStem)) {
243
+ violations.push({
244
+ reason: "device-name",
245
+ message: `"${deviceStem}" is a Windows device name`,
246
+ });
247
+ }
248
+ const lower = name.toLowerCase();
249
+ const extension = SOURCE_EXTENSIONS.find((ext) => lower.endsWith(ext));
250
+ if (extension) {
251
+ violations.push({
252
+ reason: "source-extension",
253
+ message: `the name ends in "${extension}", which would shadow a source module`,
254
+ });
255
+ }
256
+ if (options.existingNames) {
257
+ let isNew = true;
258
+ let collidesWith: string | undefined;
259
+ for (const existing of options.existingNames) {
260
+ if (existing === name) {
261
+ isNew = false;
262
+ break;
263
+ }
264
+ if (collidesWith === undefined && existing.toLowerCase() === lower) collidesWith = existing;
265
+ }
266
+ if (isNew && collidesWith !== undefined) {
267
+ violations.push({
268
+ reason: "case-collision",
269
+ message: `the name differs from the existing entry "${collidesWith}" only in letter case`,
270
+ });
271
+ }
272
+ }
273
+ return violations;
274
+ }
275
+
276
+ /** Checks a name a write deletes: anything non-empty can be deleted. */
277
+ export function checkDeletedName(name: string): NameViolation[] {
278
+ return name.length === 0 ? [{ reason: "empty", message: "the name is empty" }] : [];
279
+ }
@@ -0,0 +1,67 @@
1
+ /**
2
+ * Parameter validation for the four methods. `params` is always an object;
3
+ * unknown parameters are rejected, so a guard the server doesn't understand
4
+ * never turns into an unguarded write.
5
+ *
6
+ * zod only checks the shape: callers keep using the raw object, because a
7
+ * parsed copy of a record would turn an own `__proto__` key into a prototype.
8
+ */
9
+ import { z } from "zod";
10
+ import { invalidParams } from "./errors";
11
+ import type { BlocksApplyParams, MethodName, ReadParams } from "./types";
12
+
13
+ const opaque = z.string().min(1).max(1024);
14
+
15
+ const readParams = z.strictObject({
16
+ ref: z.string().min(1).max(255).optional(),
17
+ ifNoneMatch: opaque.optional(),
18
+ });
19
+
20
+ const applyParams = z.strictObject({
21
+ ref: z.string().min(1).max(255).optional(),
22
+ requestKey: z.string().min(1).max(256).optional(),
23
+ ifSchemaMatch: opaque.optional(),
24
+ // Entry shapes are checked later and reported as InvalidBlock, all at once.
25
+ set: z.record(z.string(), z.unknown()).optional(),
26
+ delete: z.array(z.string()).optional(),
27
+ ifMatch: z.record(z.string(), opaque.nullable()).optional(),
28
+ });
29
+
30
+ const schemas: Record<MethodName, z.ZodType> = {
31
+ describe: z.strictObject({}),
32
+ "schema.get": readParams,
33
+ "blocks.list": readParams,
34
+ "blocks.apply": applyParams,
35
+ };
36
+
37
+ function describeIssues(error: z.ZodError): string {
38
+ return error.issues
39
+ .map((issue) => {
40
+ const path = issue.path.length ? issue.path.join(".") : "params";
41
+ if (issue.code === "unrecognized_keys") {
42
+ return `unknown parameter${issue.keys.length > 1 ? "s" : ""} ${issue.keys
43
+ .map((k) => `"${k}"`)
44
+ .join(", ")}`;
45
+ }
46
+ return `${path}: ${issue.message}`;
47
+ })
48
+ .join("; ");
49
+ }
50
+
51
+ /**
52
+ * Checks `params` for `method` and returns it as given (never a copy).
53
+ * Throws Invalid params (-32602) when it doesn't fit.
54
+ */
55
+ export function validateParams(method: "describe", params: unknown): Record<string, never>;
56
+ export function validateParams(method: "schema.get" | "blocks.list", params: unknown): ReadParams;
57
+ export function validateParams(method: "blocks.apply", params: unknown): BlocksApplyParams;
58
+ export function validateParams(method: MethodName, params: unknown): unknown;
59
+ export function validateParams(method: MethodName, params: unknown): unknown {
60
+ const value = params === undefined ? {} : params;
61
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
62
+ throw invalidParams("params must be an object");
63
+ }
64
+ const result = schemas[method].safeParse(value);
65
+ if (!result.success) throw invalidParams(describeIssues(result.error));
66
+ return value;
67
+ }