@decocms/blocks 8.9.1 → 8.10.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 (257) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/index.js.map +1 -1
  5. package/dist/protocol/channel.d.ts +98 -0
  6. package/dist/protocol/channel.d.ts.map +1 -0
  7. package/dist/protocol/channel.js +58 -0
  8. package/dist/protocol/channel.js.map +1 -0
  9. package/dist/protocol/client.js +2 -2
  10. package/dist/protocol/client.js.map +1 -1
  11. package/dist/protocol/conformance/blockMetaVectors.json +214 -0
  12. package/dist/protocol/conformance/contentHashFixtures.d.ts +22 -0
  13. package/dist/protocol/conformance/contentHashFixtures.d.ts.map +1 -1
  14. package/dist/protocol/conformance/contentHashFixtures.js +55 -0
  15. package/dist/protocol/conformance/contentHashFixtures.js.map +1 -1
  16. package/dist/protocol/conformance/index.d.ts +2 -1
  17. package/dist/protocol/conformance/index.d.ts.map +1 -1
  18. package/dist/protocol/conformance/index.js +2 -1
  19. package/dist/protocol/conformance/index.js.map +1 -1
  20. package/dist/protocol/conformance/vectors.d.ts +33 -0
  21. package/dist/protocol/conformance/vectors.d.ts.map +1 -0
  22. package/dist/protocol/conformance/vectors.js +3 -0
  23. package/dist/protocol/conformance/vectors.js.map +1 -0
  24. package/dist/protocol/index.d.ts +11 -1
  25. package/dist/protocol/index.d.ts.map +1 -1
  26. package/dist/protocol/index.js +11 -1
  27. package/dist/protocol/index.js.map +1 -1
  28. package/dist/protocol/keys.d.ts +1 -1
  29. package/dist/protocol/keys.js +1 -1
  30. package/dist/v8/background.d.ts +13 -0
  31. package/dist/v8/background.d.ts.map +1 -1
  32. package/dist/v8/background.js +41 -0
  33. package/dist/v8/background.js.map +1 -1
  34. package/dist/v8/blockMeta.d.ts +27 -0
  35. package/dist/v8/blockMeta.d.ts.map +1 -0
  36. package/dist/v8/blockMeta.js +75 -0
  37. package/dist/v8/blockMeta.js.map +1 -0
  38. package/dist/v8/blockStore.d.ts +43 -0
  39. package/dist/v8/blockStore.d.ts.map +1 -0
  40. package/dist/v8/blockStore.js +95 -0
  41. package/dist/v8/blockStore.js.map +1 -0
  42. package/dist/v8/boundedJson.d.ts +5 -0
  43. package/dist/v8/boundedJson.d.ts.map +1 -1
  44. package/dist/v8/boundedJson.js +10 -2
  45. package/dist/v8/boundedJson.js.map +1 -1
  46. package/dist/v8/boundedMap.d.ts +19 -0
  47. package/dist/v8/boundedMap.d.ts.map +1 -0
  48. package/dist/v8/boundedMap.js +52 -0
  49. package/dist/v8/boundedMap.js.map +1 -0
  50. package/dist/v8/builtins/data.d.ts +18 -2
  51. package/dist/v8/builtins/data.d.ts.map +1 -1
  52. package/dist/v8/builtins/data.js +17 -1
  53. package/dist/v8/builtins/data.js.map +1 -1
  54. package/dist/v8/builtins/index.d.ts.map +1 -1
  55. package/dist/v8/builtins/index.js +2 -1
  56. package/dist/v8/builtins/index.js.map +1 -1
  57. package/dist/v8/builtins/legacy.d.ts +6 -3
  58. package/dist/v8/builtins/legacy.d.ts.map +1 -1
  59. package/dist/v8/builtins/legacy.js +6 -3
  60. package/dist/v8/builtins/legacy.js.map +1 -1
  61. package/dist/v8/canonical.d.ts +8 -0
  62. package/dist/v8/canonical.d.ts.map +1 -1
  63. package/dist/v8/canonical.js +15 -0
  64. package/dist/v8/canonical.js.map +1 -1
  65. package/dist/v8/cli/builtins.d.ts.map +1 -1
  66. package/dist/v8/cli/builtins.js +1 -0
  67. package/dist/v8/cli/builtins.js.map +1 -1
  68. package/dist/v8/cli/check/index.d.ts +10 -0
  69. package/dist/v8/cli/check/index.d.ts.map +1 -1
  70. package/dist/v8/cli/check/index.js +91 -7
  71. package/dist/v8/cli/check/index.js.map +1 -1
  72. package/dist/v8/cli/content.d.ts +12 -25
  73. package/dist/v8/cli/content.d.ts.map +1 -1
  74. package/dist/v8/cli/content.js +46 -75
  75. package/dist/v8/cli/content.js.map +1 -1
  76. package/dist/v8/cli/index.d.ts +1 -2
  77. package/dist/v8/cli/index.d.ts.map +1 -1
  78. package/dist/v8/cli/index.js +1 -2
  79. package/dist/v8/cli/index.js.map +1 -1
  80. package/dist/v8/cli/remote/commands.d.ts +71 -0
  81. package/dist/v8/cli/remote/commands.d.ts.map +1 -0
  82. package/dist/v8/cli/remote/commands.js +644 -0
  83. package/dist/v8/cli/remote/commands.js.map +1 -0
  84. package/dist/v8/cli/remote/diff.d.ts +15 -0
  85. package/dist/v8/cli/remote/diff.d.ts.map +1 -0
  86. package/dist/v8/cli/remote/diff.js +102 -0
  87. package/dist/v8/cli/remote/diff.js.map +1 -0
  88. package/dist/v8/cli/remote/env.d.ts +35 -0
  89. package/dist/v8/cli/remote/env.d.ts.map +1 -0
  90. package/dist/v8/cli/remote/env.js +84 -0
  91. package/dist/v8/cli/remote/env.js.map +1 -0
  92. package/dist/v8/cli/remote/http.d.ts +149 -0
  93. package/dist/v8/cli/remote/http.d.ts.map +1 -0
  94. package/dist/v8/cli/remote/http.js +381 -0
  95. package/dist/v8/cli/remote/http.js.map +1 -0
  96. package/dist/v8/cli/remote/local.d.ts +90 -0
  97. package/dist/v8/cli/remote/local.d.ts.map +1 -0
  98. package/dist/v8/cli/remote/local.js +309 -0
  99. package/dist/v8/cli/remote/local.js.map +1 -0
  100. package/dist/v8/cli/root.d.ts +29 -0
  101. package/dist/v8/cli/root.d.ts.map +1 -1
  102. package/dist/v8/cli/root.js +28 -0
  103. package/dist/v8/cli/root.js.map +1 -1
  104. package/dist/v8/cli/run.d.ts +11 -1
  105. package/dist/v8/cli/run.d.ts.map +1 -1
  106. package/dist/v8/cli/run.js +281 -124
  107. package/dist/v8/cli/run.js.map +1 -1
  108. package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
  109. package/dist/v8/cli/schema/builtinSchemas.js +28 -10
  110. package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
  111. package/dist/v8/cli/schema/generate.js +1 -1
  112. package/dist/v8/cli/schema/generate.js.map +1 -1
  113. package/dist/v8/client.d.ts +9 -9
  114. package/dist/v8/client.d.ts.map +1 -1
  115. package/dist/v8/client.js +138 -50
  116. package/dist/v8/client.js.map +1 -1
  117. package/dist/v8/cms.d.ts +2 -1
  118. package/dist/v8/cms.d.ts.map +1 -1
  119. package/dist/v8/cms.js +55 -46
  120. package/dist/v8/cms.js.map +1 -1
  121. package/dist/v8/content.d.ts +39 -78
  122. package/dist/v8/content.d.ts.map +1 -1
  123. package/dist/v8/content.js +155 -195
  124. package/dist/v8/content.js.map +1 -1
  125. package/dist/v8/contentIndex.d.ts +71 -0
  126. package/dist/v8/contentIndex.d.ts.map +1 -0
  127. package/dist/v8/contentIndex.js +137 -0
  128. package/dist/v8/contentIndex.js.map +1 -0
  129. package/dist/v8/draft.d.ts +7 -7
  130. package/dist/v8/draft.d.ts.map +1 -1
  131. package/dist/v8/draft.js +10 -9
  132. package/dist/v8/draft.js.map +1 -1
  133. package/dist/v8/draftChanges.d.ts +59 -32
  134. package/dist/v8/draftChanges.d.ts.map +1 -1
  135. package/dist/v8/draftChanges.js +139 -75
  136. package/dist/v8/draftChanges.js.map +1 -1
  137. package/dist/v8/errors.d.ts +21 -0
  138. package/dist/v8/errors.d.ts.map +1 -1
  139. package/dist/v8/errors.js +22 -0
  140. package/dist/v8/errors.js.map +1 -1
  141. package/dist/v8/hostedSource.d.ts +57 -0
  142. package/dist/v8/hostedSource.d.ts.map +1 -0
  143. package/dist/v8/hostedSource.js +18 -0
  144. package/dist/v8/hostedSource.js.map +1 -0
  145. package/dist/v8/identity.d.ts +1 -1
  146. package/dist/v8/identity.js +1 -1
  147. package/dist/v8/index.d.ts +1 -0
  148. package/dist/v8/index.d.ts.map +1 -1
  149. package/dist/v8/index.js +1 -0
  150. package/dist/v8/index.js.map +1 -1
  151. package/dist/v8/matchRoute.js +7 -4
  152. package/dist/v8/matchRoute.js.map +1 -1
  153. package/dist/v8/pin.d.ts +34 -0
  154. package/dist/v8/pin.d.ts.map +1 -0
  155. package/dist/v8/pin.js +156 -0
  156. package/dist/v8/pin.js.map +1 -0
  157. package/dist/v8/preview/StudioBridge.d.ts +8 -8
  158. package/dist/v8/preview/StudioBridge.d.ts.map +1 -1
  159. package/dist/v8/preview/StudioBridge.js +8 -10
  160. package/dist/v8/preview/StudioBridge.js.map +1 -1
  161. package/dist/v8/preview/StudioChannel.d.ts +51 -0
  162. package/dist/v8/preview/StudioChannel.d.ts.map +1 -0
  163. package/dist/v8/preview/StudioChannel.js +104 -0
  164. package/dist/v8/preview/StudioChannel.js.map +1 -0
  165. package/dist/v8/preview/index.d.ts +3 -0
  166. package/dist/v8/preview/index.d.ts.map +1 -1
  167. package/dist/v8/preview/index.js +3 -0
  168. package/dist/v8/preview/index.js.map +1 -1
  169. package/dist/v8/remoteLoader.d.ts +42 -5
  170. package/dist/v8/remoteLoader.d.ts.map +1 -1
  171. package/dist/v8/remoteLoader.js +317 -259
  172. package/dist/v8/remoteLoader.js.map +1 -1
  173. package/dist/v8/resolver.d.ts +22 -8
  174. package/dist/v8/resolver.d.ts.map +1 -1
  175. package/dist/v8/resolver.js +37 -32
  176. package/dist/v8/resolver.js.map +1 -1
  177. package/dist/v8/revisionId.d.ts +11 -0
  178. package/dist/v8/revisionId.d.ts.map +1 -0
  179. package/dist/v8/revisionId.js +13 -0
  180. package/dist/v8/revisionId.js.map +1 -0
  181. package/dist/v8/settings.d.ts +6 -6
  182. package/dist/v8/settings.d.ts.map +1 -1
  183. package/dist/v8/settings.js +8 -7
  184. package/dist/v8/settings.js.map +1 -1
  185. package/dist/v8/telemetry.d.ts +4 -2
  186. package/dist/v8/telemetry.d.ts.map +1 -1
  187. package/dist/v8/telemetry.js +2 -2
  188. package/dist/v8/telemetry.js.map +1 -1
  189. package/dist/v8/types.d.ts +52 -40
  190. package/dist/v8/types.d.ts.map +1 -1
  191. package/dist/v8/variants.d.ts +7 -2
  192. package/dist/v8/variants.d.ts.map +1 -1
  193. package/dist/v8/variants.js +21 -24
  194. package/dist/v8/variants.js.map +1 -1
  195. package/dist/v8/vite/index.d.ts +2 -2
  196. package/dist/v8/vite/index.js +1 -1
  197. package/dist/v8/vite/index.js.map +1 -1
  198. package/package.json +1 -1
  199. package/src/index.ts +2 -0
  200. package/src/protocol/channel.ts +127 -0
  201. package/src/protocol/client.ts +2 -2
  202. package/src/protocol/conformance/blockMetaVectors.json +214 -0
  203. package/src/protocol/conformance/contentHashFixtures.ts +74 -0
  204. package/src/protocol/conformance/index.ts +9 -1
  205. package/src/protocol/conformance/vectors.ts +36 -0
  206. package/src/protocol/index.ts +32 -0
  207. package/src/protocol/keys.ts +1 -1
  208. package/src/v8/background.ts +42 -0
  209. package/src/v8/blockMeta.ts +100 -0
  210. package/src/v8/blockStore.ts +124 -0
  211. package/src/v8/boundedJson.ts +20 -2
  212. package/src/v8/boundedMap.ts +53 -0
  213. package/src/v8/builtins/data.ts +26 -2
  214. package/src/v8/builtins/index.ts +2 -1
  215. package/src/v8/builtins/legacy.ts +6 -3
  216. package/src/v8/canonical.ts +15 -0
  217. package/src/v8/cli/builtins.ts +1 -0
  218. package/src/v8/cli/check/index.ts +97 -7
  219. package/src/v8/cli/content.ts +49 -91
  220. package/src/v8/cli/index.ts +1 -2
  221. package/src/v8/cli/remote/commands.ts +834 -0
  222. package/src/v8/cli/remote/diff.ts +100 -0
  223. package/src/v8/cli/remote/env.ts +107 -0
  224. package/src/v8/cli/remote/http.ts +484 -0
  225. package/src/v8/cli/remote/local.ts +343 -0
  226. package/src/v8/cli/root.ts +40 -0
  227. package/src/v8/cli/run.ts +333 -136
  228. package/src/v8/cli/schema/builtinSchemas.ts +29 -10
  229. package/src/v8/cli/schema/generate.ts +1 -1
  230. package/src/v8/client.ts +162 -60
  231. package/src/v8/cms.ts +62 -53
  232. package/src/v8/content.ts +179 -229
  233. package/src/v8/contentIndex.ts +183 -0
  234. package/src/v8/draft.ts +15 -14
  235. package/src/v8/draftChanges.ts +151 -85
  236. package/src/v8/errors.ts +37 -0
  237. package/src/v8/hostedSource.ts +67 -0
  238. package/src/v8/identity.ts +1 -1
  239. package/src/v8/index.ts +1 -0
  240. package/src/v8/matchRoute.ts +7 -4
  241. package/src/v8/pin.ts +176 -0
  242. package/src/v8/preview/StudioBridge.ts +8 -10
  243. package/src/v8/preview/StudioChannel.ts +116 -0
  244. package/src/v8/preview/index.ts +3 -0
  245. package/src/v8/remoteLoader.ts +350 -286
  246. package/src/v8/resolver.ts +56 -33
  247. package/src/v8/revisionId.ts +14 -0
  248. package/src/v8/settings.ts +10 -9
  249. package/src/v8/telemetry.ts +3 -3
  250. package/src/v8/types.ts +52 -40
  251. package/src/v8/variants.ts +30 -26
  252. package/src/v8/vite/index.ts +3 -3
  253. package/dist/v8/cli/serve/server.d.ts +0 -29
  254. package/dist/v8/cli/serve/server.d.ts.map +0 -1
  255. package/dist/v8/cli/serve/server.js +0 -296
  256. package/dist/v8/cli/serve/server.js.map +0 -1
  257. package/src/v8/cli/serve/server.ts +0 -348
package/src/v8/cli/run.ts CHANGED
@@ -1,67 +1,129 @@
1
1
  /**
2
- * The `deco` command line: `deco <schema|content|check|serve> [flags]`
3
- * (spec: cli). Parses flags, runs one command and returns its exit code.
2
+ * The `deco` command line (spec: cli). Parses flags, runs one command and
3
+ * returns its exit code (spec: cli › Exit codes): 0 ok, 1 check failed (or
4
+ * any other failure), 2 conflict, 3 auth, 4 network, 5 busy (run again), 64
5
+ * usage. Every command takes `--json`: stdout then carries exactly one JSON
6
+ * object, and what a person reads goes to stderr.
4
7
  */
5
- import { check } from "./check/index.ts";
6
- import { content, writeContent } from "./content.ts";
8
+ import { readSchemaFile, reportCheck } from "./check/index.ts";
9
+ import { content, readSavedBlocks, savedBlocksFromMap, writeContent } from "./content.ts";
7
10
  import { consoleReporter, type Reporter, withColor } from "./log.ts";
8
- import { CliError, decoPaths, findDecoRoot } from "./root.ts";
11
+ import {
12
+ diff,
13
+ drafts,
14
+ login,
15
+ type Outcome,
16
+ publish,
17
+ pull,
18
+ push,
19
+ type RemoteContext,
20
+ releases,
21
+ remoteBlocks,
22
+ schemaPush,
23
+ } from "./remote/commands.ts";
24
+ import type { CommandRunner, Env } from "./remote/env.ts";
25
+ import type { Fetch } from "./remote/http.ts";
26
+ import { checkDraftName, findSite, requireDraftName } from "./remote/local.ts";
27
+ import { CliError, decoPaths, EXIT, findDecoRoot, usageError } from "./root.ts";
9
28
  import { reportSchema, schema, writeSchema } from "./schema/index.ts";
10
- import { serve, startServer } from "./serve/server.ts";
11
29
  import { watchFiles, watchTree } from "./watch.ts";
12
30
 
13
31
  type FlagKind = "string" | "boolean";
14
32
 
15
- const COMMANDS: Record<string, { usage: string; flags: Record<string, FlagKind> }> = {
16
- schema: {
17
- usage: "deco schema [--root <dir>] [--watch | --check]",
18
- flags: { root: "string", watch: "boolean", check: "boolean" },
33
+ interface CommandSpec {
34
+ usage: string;
35
+ flags: Record<string, FlagKind>;
36
+ /** How many positional arguments it takes, at most. */
37
+ positionals?: number;
38
+ }
39
+
40
+ const DRAFT = { draft: "string" } as const;
41
+
42
+ const COMMANDS: Record<string, CommandSpec> = {
43
+ login: { usage: "deco login", flags: {} },
44
+ pull: {
45
+ usage: "deco pull [--draft=<name>] [--force]",
46
+ flags: { ...DRAFT, force: "boolean" },
47
+ },
48
+ diff: { usage: "deco diff [--draft=<name>]", flags: { ...DRAFT } },
49
+ push: {
50
+ usage: "deco push --draft=<name> [--ours | --theirs] [--prune]",
51
+ flags: { ...DRAFT, ours: "boolean", theirs: "boolean", prune: "boolean" },
52
+ },
53
+ publish: {
54
+ usage: "deco publish --draft=<name> [--message=<text>]",
55
+ flags: { ...DRAFT, message: "string" },
56
+ },
57
+ drafts: {
58
+ usage: "deco drafts list | new <name> | discard <name> | url <name>",
59
+ flags: {},
60
+ positionals: 2,
61
+ },
62
+ releases: { usage: "deco releases [--cursor=<cursor>]", flags: { cursor: "string" } },
63
+ check: {
64
+ usage: "deco check [--draft=<name> | --revision=<id>]",
65
+ flags: { ...DRAFT, revision: "string" },
19
66
  },
20
67
  content: {
21
- usage: "deco content [--root <dir>] [--watch]",
22
- flags: { root: "string", watch: "boolean" },
68
+ usage: "deco content [--watch]",
69
+ flags: { watch: "boolean" },
23
70
  },
24
- check: { usage: "deco check [--root <dir>]", flags: { root: "string" } },
25
- serve: {
26
- usage:
27
- "deco serve [--root <dir>] [--port <n>] [--host <addr>] [--preview <host:port|url>] [--assets <dir>] [--read-only]",
28
- flags: {
29
- root: "string",
30
- port: "string",
31
- host: "string",
32
- preview: "string",
33
- assets: "string",
34
- "read-only": "boolean",
35
- },
71
+ schema: {
72
+ usage: "deco schema [--watch | --check]\n deco schema push",
73
+ flags: { watch: "boolean", check: "boolean" },
74
+ positionals: 1,
36
75
  },
37
76
  };
38
77
 
78
+ /** Flags every command takes. */
79
+ const COMMON_FLAGS: Record<string, FlagKind> = { root: "string", json: "boolean" };
80
+
39
81
  export const USAGE = `Usage: deco <command> [flags]
40
82
 
41
83
  Commands:
84
+ login print how to log in (the session is Studio CLI's: npx decocms auth login)
85
+ pull write production, or a draft, into .deco/blocks
86
+ diff show what .deco/blocks changes against what was pulled, or against a draft
87
+ push save the blocks changed since the pull into a draft as one change (deletes with
88
+ --prune); prints its preview link
89
+ publish make a draft live (prints its changes first)
90
+ drafts list, create, discard a draft, or print its preview link
91
+ releases list the published revisions, newest first, 50 a page
92
+ check check that the content fits the schema (production; or a draft, or a revision;
93
+ with no DECO_SITE set anywhere, the saved blocks in .deco/blocks)
94
+ content turn .deco/blocks into the content module, .deco/blocks.gen.ts (content without
95
+ a site: createCMS({ blocks, content }))
42
96
  schema turn the types in .deco/index.ts into .deco/schema.gen.json
43
97
  (--check: write nothing, fail when the file is out of date; for CI)
44
- content turn .deco/blocks into the content module, .deco/blocks.gen.ts
45
- check check that every saved block fits the schema (writes nothing)
46
- serve serve .deco to the site editor on this machine, at http://localhost:4545/rpc;
47
- run it inside the site's git repository (the change list compares with HEAD)
98
+ schema push: upload it so Studio can draw forms (CI, on production deploys)
48
99
 
49
100
  ${Object.values(COMMANDS)
50
101
  .map((c) => ` ${c.usage}`)
51
102
  .join("\n")}
52
103
 
53
104
  Every command finds .deco/ by walking up from the current folder, or takes --root.
54
- Every command takes --color or --no-color; without either, output is coloured only on a terminal.`;
105
+ Every command takes --json (one JSON object on stdout) and --color or --no-color.
106
+ Site: DECO_SITE, from the environment, else .env, .dev.vars, then vars.DECO_SITE in
107
+ wrangler.jsonc, wrangler.json or wrangler.toml (in the folder that contains .deco/).
108
+ Studio: DECO_STUDIO_URL (default https://studio.decocms.com); token: DECO_TOKEN, else
109
+ npx decocms auth token. Exit codes: 0 ok, 1 failed, 2 conflict, 3 auth, 4 network,
110
+ 5 busy (run again), 64 usage.`;
55
111
 
56
112
  export type ParsedFlags = Record<string, string | boolean | string[]>;
57
113
 
58
114
  export function parseFlags(command: string, args: string[]): ParsedFlags {
59
- const spec = COMMANDS[command].flags;
115
+ const command_ = COMMANDS[command]!;
116
+ const spec = { ...COMMON_FLAGS, ...command_.flags };
60
117
  const flags: ParsedFlags = {};
118
+ const positionals: string[] = [];
61
119
  for (let i = 0; i < args.length; i++) {
62
- const arg = args[i];
63
- if (!arg.startsWith("--"))
64
- throw new CliError(`unexpected argument "${arg}"\n${COMMANDS[command].usage}`);
120
+ const arg = args[i]!;
121
+ if (!arg.startsWith("--")) {
122
+ if (positionals.length >= (command_.positionals ?? 0))
123
+ throw usageError(`unexpected argument "${arg}"\n${command_.usage}`);
124
+ positionals.push(arg);
125
+ continue;
126
+ }
65
127
  // Every command's: `color` is true, false or absent; the last one given wins.
66
128
  if (arg === "--color" || arg === "--no-color") {
67
129
  flags.color = arg === "--color";
@@ -69,11 +131,11 @@ export function parseFlags(command: string, args: string[]): ParsedFlags {
69
131
  }
70
132
  const eq = arg.indexOf("=");
71
133
  const name = arg.slice(2, eq === -1 ? undefined : eq);
72
- if (name === "color" || name === "no-color") throw new CliError(`--${name} takes no value`);
134
+ if (name === "color" || name === "no-color") throw usageError(`--${name} takes no value`);
73
135
  const kind = Object.hasOwn(spec, name) ? spec[name] : undefined;
74
- if (!kind) throw new CliError(`unknown flag --${name}\n${COMMANDS[command].usage}`);
136
+ if (!kind) throw usageError(`unknown flag --${name}\n${command_.usage}`);
75
137
  if (kind === "boolean") {
76
- if (eq !== -1) throw new CliError(`--${name} takes no value`);
138
+ if (eq !== -1) throw usageError(`--${name} takes no value`);
77
139
  flags[name] = true;
78
140
  continue;
79
141
  }
@@ -82,11 +144,12 @@ export function parseFlags(command: string, args: string[]): ParsedFlags {
82
144
  else {
83
145
  value = args[i + 1];
84
146
  if (value === undefined || value.startsWith("--"))
85
- throw new CliError(`--${name} needs a value`);
147
+ throw usageError(`--${name} needs a value`);
86
148
  i++;
87
149
  }
88
150
  flags[name] = value;
89
151
  }
152
+ if (positionals.length > 0) flags._ = positionals;
90
153
  return flags;
91
154
  }
92
155
 
@@ -94,8 +157,16 @@ export interface RunOptions {
94
157
  cwd?: string;
95
158
  /** Defaults to the console, coloured when stdout and stderr are both terminals. */
96
159
  reporter?: Reporter;
97
- /** Resolves when a `--watch` or `serve` run should stop (tests); defaults to SIGINT/SIGTERM. */
160
+ /** Resolves when a `--watch` run should stop (tests); defaults to SIGINT/SIGTERM. */
98
161
  until?: Promise<void>;
162
+ /** The environment (`DECO_STUDIO_URL`, `DECO_TOKEN`); defaults to the process's. */
163
+ env?: Env;
164
+ /** Defaults to the global `fetch`. */
165
+ fetch?: Fetch;
166
+ /** Runs `npx decocms auth token` (tests replace it). */
167
+ runCommand?: CommandRunner;
168
+ /** Where `--json` writes its object; defaults to stdout. */
169
+ stdout?: (text: string) => void;
99
170
  }
100
171
 
101
172
  function stopSignal(): Promise<void> {
@@ -128,124 +199,250 @@ async function watchLoop(
128
199
  await running;
129
200
  }
130
201
 
131
- /**
132
- * What `deco publish` prints. It isn't one of the four commands and isn't in
133
- * the usage: publishing is committing (/next/design-decisions).
134
- */
135
- const PUBLISH_SIGNPOST = `There is no publish command: Git is the source of truth for content, so publishing is committing.
136
- Commit the changes in .deco/blocks (and push them). A deploy ships the commit; with the hosted
137
- Deco CMS, Studio's Publish (or Resync) makes the commit a release without a deploy.`;
202
+ /** Everything a person reads goes to stderr, so `--json`'s stdout is one object. */
203
+ const stderrReporter: Reporter = {
204
+ info: (message) => console.error(message),
205
+ warn: (message) => console.error(message),
206
+ error: (message) => console.error(message),
207
+ };
208
+
209
+ function stringFlag(flags: ParsedFlags, name: string): string | null {
210
+ const value = flags[name];
211
+ return typeof value === "string" ? value : null;
212
+ }
138
213
 
139
214
  /** Run one `deco` invocation; returns the exit code. */
140
215
  export async function runCli(argv: string[], options: RunOptions = {}): Promise<number> {
141
216
  let reporter = options.reporter ?? consoleReporter;
217
+ const stdout = options.stdout ?? ((text: string) => process.stdout.write(`${text}\n`));
142
218
  const [command, ...rest] = argv;
143
219
  if (!command || command === "help" || command === "--help" || command === "-h") {
144
220
  reporter.info(USAGE);
145
- return command ? 0 : 1;
146
- }
147
- if (command === "publish") {
148
- // Not a command: a signpost for agents that look for one (design-decisions).
149
- reporter.error(PUBLISH_SIGNPOST);
150
- return 1;
151
- }
152
- if (!Object.hasOwn(COMMANDS, command)) {
153
- reporter.error(`unknown command "${command}"\n\n${USAGE}`);
154
- return 1;
221
+ return command ? EXIT.ok : EXIT.usage;
155
222
  }
223
+ const json = rest.includes("--json");
224
+ if (json && !options.reporter) reporter = stderrReporter;
225
+ let outcome: Outcome;
156
226
  try {
227
+ if (!Object.hasOwn(COMMANDS, command))
228
+ throw usageError(`unknown command "${command}"\n\n${USAGE}`);
157
229
  const flags = parseFlags(command, rest);
158
230
  const color =
159
231
  typeof flags.color === "boolean"
160
232
  ? flags.color
161
233
  : options.reporter
162
234
  ? Boolean(options.reporter.color)
163
- : Boolean(process.stdout.isTTY && process.stderr.isTTY);
235
+ : !json && Boolean(process.stdout.isTTY && process.stderr.isTTY);
164
236
  reporter = withColor(reporter, color);
165
- const root = flags.root as string | undefined;
166
- const base = { root, cwd: options.cwd, reporter };
167
- switch (command) {
168
- case "schema": {
169
- if (flags.watch && flags.check) {
170
- throw new CliError(`--watch and --check can't be combined\n${COMMANDS.schema.usage}`);
171
- }
172
- if (!flags.watch) return await schema({ ...base, check: flags.check === true });
173
- const paths = decoPaths(findDecoRoot(base));
174
- // Monorepo packages the block map imports live outside the root:
175
- // watch the files the last run read there, too.
176
- const external = watchFiles(() => void once());
177
- let running = Promise.resolve();
178
- const run = async () => {
179
- const result = await writeSchema(paths);
180
- external.update(result.externalSources);
181
- reportSchema(result, reporter);
182
- };
183
- const once = () => {
184
- running = running.then(run).catch((error) => reporter.error((error as Error).message));
185
- return running;
237
+ const env = options.env ?? process.env;
238
+ outcome = await runCommand(command, flags, { ...options, env, reporter });
239
+ } catch (error) {
240
+ if (!(error instanceof CliError)) throw error;
241
+ reporter.error(error.message);
242
+ if (json) {
243
+ stdout(
244
+ JSON.stringify({
245
+ ok: false,
246
+ exitCode: error.exitCode,
247
+ error: { code: error.code, message: error.message },
248
+ ...error.details,
249
+ }),
250
+ );
251
+ }
252
+ return error.exitCode;
253
+ }
254
+ if (json) {
255
+ stdout(
256
+ JSON.stringify(
257
+ outcome.exitCode === EXIT.ok
258
+ ? { ok: true, ...outcome.result }
259
+ : { ok: false, exitCode: outcome.exitCode, ...outcome.result },
260
+ ),
261
+ );
262
+ }
263
+ return outcome.exitCode;
264
+ }
265
+
266
+ /**
267
+ * The root of a remote command. With no `.deco/` at all a remote command has
268
+ * no folder to work in nor to read `DECO_SITE` from, a usage error (64), as a
269
+ * missing `DECO_SITE` is (contract §7.4); local commands keep exit 1. The
270
+ * message stays the documented one (cli-09).
271
+ */
272
+ function remoteRoot(options: { root?: string; cwd?: string }): string {
273
+ try {
274
+ return findDecoRoot(options);
275
+ } catch (error) {
276
+ if (error instanceof CliError && error.exitCode !== EXIT.usage) {
277
+ throw usageError(error.message);
278
+ }
279
+ throw error;
280
+ }
281
+ }
282
+
283
+ async function runCommand(
284
+ command: string,
285
+ flags: ParsedFlags,
286
+ options: RunOptions & { env: Env; reporter: Reporter },
287
+ ): Promise<Outcome> {
288
+ const { reporter } = options;
289
+ const positionals = (flags._ as string[] | undefined) ?? [];
290
+ const root = flags.root as string | undefined;
291
+ const base = { root, cwd: options.cwd, reporter };
292
+ const remote = (): RemoteContext => ({
293
+ paths: decoPaths(remoteRoot(base)),
294
+ reporter,
295
+ env: options.env,
296
+ fetch: options.fetch ?? fetch,
297
+ runCommand: options.runCommand,
298
+ });
299
+ const legacy = (exitCode: number, result: Record<string, unknown> = {}): Outcome =>
300
+ exitCode === EXIT.ok
301
+ ? { exitCode, result }
302
+ : {
303
+ exitCode,
304
+ result: { error: { code: "failed", message: `deco ${command} failed` }, ...result },
186
305
  };
187
- await run();
188
- // Regenerate when any source file changes; the schema only depends on code.
189
- await watchLoop(
190
- paths.root,
191
- (rel) =>
192
- /\.(ts|tsx|mts|cts)$/.test(rel) &&
193
- !rel
194
- .split("/")
195
- .some((s) => s === "node_modules" || s.startsWith(".git") || s === "dist") &&
196
- !rel.endsWith(".gen.ts"),
197
- once,
198
- options.until ?? stopSignal(),
199
- reporter,
200
- );
201
- external.close();
202
- await running;
203
- return 0;
306
+ switch (command) {
307
+ case "login":
308
+ return login({ env: options.env, reporter });
309
+ case "pull": {
310
+ const draft = stringFlag(flags, "draft");
311
+ return pull(remote(), {
312
+ draft: draft === null ? null : checkDraftName(draft),
313
+ force: flags.force === true,
314
+ });
315
+ }
316
+ case "diff": {
317
+ const draft = stringFlag(flags, "draft");
318
+ return diff(remote(), { draft: draft === null ? null : checkDraftName(draft) });
319
+ }
320
+ case "push": {
321
+ const draft = requireDraftName(flags.draft, "push");
322
+ if (flags.ours && flags.theirs) throw usageError("--ours and --theirs can't be combined");
323
+ return push(remote(), {
324
+ draft,
325
+ side: flags.ours ? "ours" : flags.theirs ? "theirs" : null,
326
+ prune: flags.prune === true,
327
+ });
328
+ }
329
+ case "publish":
330
+ return publish(remote(), {
331
+ draft: requireDraftName(flags.draft, "publish"),
332
+ message: stringFlag(flags, "message") ?? undefined,
333
+ });
334
+ case "drafts": {
335
+ const name = positionals[1] ?? null;
336
+ return drafts(remote(), {
337
+ action: positionals[0],
338
+ name: name === null ? null : checkDraftName(name),
339
+ });
340
+ }
341
+ case "releases":
342
+ return releases(remote(), { cursor: stringFlag(flags, "cursor") ?? undefined });
343
+ case "check": {
344
+ const draft = stringFlag(flags, "draft");
345
+ const revision = stringFlag(flags, "revision");
346
+ if (draft !== null && revision !== null)
347
+ throw usageError("--draft and --revision can't be combined");
348
+ // No flag: production (latest.json, then each block by hash, from the
349
+ // CDN), always, even when .deco/blocks exists. No .deco/ at all stays
350
+ // exit 1 for check, as before.
351
+ const paths = decoPaths(findDecoRoot(base));
352
+ if (draft === null && revision === null && findSite(paths, options.env) === null) {
353
+ // No Studio site: the content is the git-backed .deco/blocks (a site
354
+ // on createCMS({ blocks, content }), a v7 site being migrated), checked
355
+ // as deco check always did.
356
+ const meta = readSchemaFile(paths.schema);
357
+ return checkOutcome(reportCheck(meta, readSavedBlocks(paths.blocks), reporter));
204
358
  }
205
- case "content": {
206
- if (!flags.watch) return await content(base);
207
- const paths = decoPaths(findDecoRoot(base));
208
- const once = async () => {
209
- const result = await writeContent(paths);
210
- if (result.changed) reporter.info(`wrote .deco/blocks.gen.ts (${result.count} blocks)`);
211
- };
212
- await content({ ...base, watching: true });
213
- await watchLoop(
214
- paths.blocks,
215
- (rel) => rel.endsWith(".json"),
216
- once,
217
- options.until ?? stopSignal(),
218
- reporter,
219
- );
220
- return 0;
359
+ const ctx = remote();
360
+ const meta = readSchemaFile(ctx.paths.schema);
361
+ const source = await remoteBlocks(ctx, {
362
+ draft: draft === null ? null : checkDraftName(draft),
363
+ revision,
364
+ });
365
+ reporter.info(`checking ${source.label}`);
366
+ return checkOutcome(reportCheck(meta, savedBlocksFromMap(source.blocks), reporter));
367
+ }
368
+ case "content": {
369
+ if (!flags.watch) return legacy(await content(base));
370
+ const paths = decoPaths(findDecoRoot(base));
371
+ const once = async () => {
372
+ const result = await writeContent(paths);
373
+ if (result.changed) reporter.info(`wrote .deco/blocks.gen.ts (${result.count} blocks)`);
374
+ };
375
+ await content({ ...base, watching: true });
376
+ await watchLoop(
377
+ paths.blocks,
378
+ (rel) => rel.endsWith(".json"),
379
+ once,
380
+ options.until ?? stopSignal(),
381
+ reporter,
382
+ );
383
+ return { exitCode: EXIT.ok, result: {} };
384
+ }
385
+ case "schema": {
386
+ if (positionals.length > 0) {
387
+ if (positionals[0] !== "push")
388
+ throw usageError(`unexpected argument "${positionals[0]}"\n${COMMANDS.schema!.usage}`);
389
+ if (flags.watch || flags.check)
390
+ throw usageError("deco schema push takes no --watch or --check");
391
+ return schemaPush(remote());
221
392
  }
222
- case "check":
223
- return check(base);
224
- case "serve": {
225
- const port = flags.port === undefined ? undefined : Number(flags.port);
226
- if (port !== undefined && !Number.isInteger(port))
227
- throw new CliError(`--port must be a number, got ${flags.port}`);
228
- const serveOptions = {
229
- ...base,
230
- port,
231
- host: flags.host as string | undefined,
232
- preview: flags.preview as string | undefined,
233
- assets: flags.assets as string | undefined,
234
- readOnly: Boolean(flags["read-only"]),
235
- };
236
- if (!options.until) return await serve(serveOptions);
237
- const running = await startServer(serveOptions);
238
- await options.until;
239
- await running.close();
240
- return 0;
393
+ if (flags.watch && flags.check) {
394
+ throw usageError(`--watch and --check can't be combined\n${COMMANDS.schema!.usage}`);
241
395
  }
396
+ if (!flags.watch) return legacy(await schema({ ...base, check: flags.check === true }));
397
+ const paths = decoPaths(findDecoRoot(base));
398
+ // Monorepo packages the block map imports live outside the root:
399
+ // watch the files the last run read there, too.
400
+ const external = watchFiles(() => void once());
401
+ let running = Promise.resolve();
402
+ const run = async () => {
403
+ const result = await writeSchema(paths);
404
+ external.update(result.externalSources);
405
+ reportSchema(result, reporter);
406
+ };
407
+ const once = () => {
408
+ running = running.then(run).catch((error) => reporter.error((error as Error).message));
409
+ return running;
410
+ };
411
+ await run();
412
+ // Regenerate when any source file changes; the schema only depends on code.
413
+ await watchLoop(
414
+ paths.root,
415
+ (rel) =>
416
+ /\.(ts|tsx|mts|cts)$/.test(rel) &&
417
+ !rel
418
+ .split("/")
419
+ .some((s) => s === "node_modules" || s.startsWith(".git") || s === "dist") &&
420
+ !rel.endsWith(".gen.ts"),
421
+ once,
422
+ options.until ?? stopSignal(),
423
+ reporter,
424
+ );
425
+ external.close();
426
+ await running;
427
+ return { exitCode: EXIT.ok, result: {} };
242
428
  }
243
- return 1;
244
- } catch (error) {
245
- if (error instanceof CliError) {
246
- reporter.error(error.message);
247
- return 1;
248
- }
249
- throw error;
250
429
  }
430
+ throw usageError(`unknown command "${command}"`);
431
+ }
432
+
433
+ function checkOutcome(report: ReturnType<typeof reportCheck>): Outcome {
434
+ const result = {
435
+ blocks: report.count,
436
+ errors: report.errors,
437
+ warnings: report.warnings,
438
+ problems: report.problems,
439
+ };
440
+ if (report.exitCode === EXIT.ok) return { exitCode: EXIT.ok, result };
441
+ return {
442
+ exitCode: report.exitCode,
443
+ result: {
444
+ error: { code: "check_failed", message: `${report.errors} errors` },
445
+ ...result,
446
+ },
447
+ };
251
448
  }
@@ -1,5 +1,5 @@
1
1
  /**
2
- * The forms of the twelve built-in blocks (spec: built-in-blocks, and the types
2
+ * The forms of the thirteen built-in blocks (spec: built-in-blocks, and the types
3
3
  * in api-reference › Types). They're always in the schema, unless the block
4
4
  * map declares the same key, which replaces the built-in.
5
5
  */
@@ -16,6 +16,7 @@ export const BUILT_IN_GROUPS: Record<string, ManifestGroup> = {
16
16
  campaign: "matchers",
17
17
  page: "pages",
18
18
  redirect: "redirects",
19
+ redirects: "redirects",
19
20
  "cms-settings": "content",
20
21
  "split-traffic": "content",
21
22
  calendar: "content",
@@ -42,6 +43,10 @@ const BUILT_IN_DOCS: Record<string, { title: string; description: string; icon?:
42
43
  },
43
44
  page: { title: "Page", description: "A page at a URL" },
44
45
  redirect: { title: "Redirect", description: "Sends one URL to another" },
46
+ redirects: {
47
+ title: "Redirects",
48
+ description: "The site's redirects: every rule in one block (the saved block Redirects)",
49
+ },
45
50
  "cms-settings": {
46
51
  title: "CMS settings",
47
52
  description: "Telemetry and analytics: the saved block named CMS",
@@ -61,6 +66,23 @@ const BUILT_IN_DOCS: Record<string, { title: string; description: string; icon?:
61
66
  },
62
67
  };
63
68
 
69
+ /** One redirect rule: the props of `redirect`, and each item of `redirects`. */
70
+ const REDIRECT_RULE = {
71
+ type: "object",
72
+ required: ["from", "to", "permanent"],
73
+ properties: {
74
+ from: { type: "string", title: "From" },
75
+ to: { type: "string", title: "To" },
76
+ permanent: {
77
+ type: "boolean",
78
+ title: "Permanent",
79
+ description: "301 when true, 307 otherwise",
80
+ },
81
+ status: { type: "number", enum: [301, 302, 307, 308], title: "Status" },
82
+ discardQueryParameters: { type: "boolean", title: "Discard query parameters" },
83
+ },
84
+ };
85
+
64
86
  /** The form of each test in a `split-traffic` block: a whole percentage. */
65
87
  const ALLOCATION = {
66
88
  type: "integer",
@@ -213,19 +235,16 @@ function builtInProps(name: string, ctx: BuiltInContext): any {
213
235
  },
214
236
  };
215
237
  case "redirect":
238
+ return REDIRECT_RULE;
239
+ case "redirects":
216
240
  return {
217
241
  type: "object",
218
- required: ["from", "to", "permanent"],
219
242
  properties: {
220
- from: { type: "string", title: "From" },
221
- to: { type: "string", title: "To" },
222
- permanent: {
223
- type: "boolean",
224
- title: "Permanent",
225
- description: "301 when true, 302 otherwise",
243
+ redirects: {
244
+ type: "array",
245
+ title: "Redirects",
246
+ items: { ...REDIRECT_RULE, title: "Redirect" },
226
247
  },
227
- status: { type: "number", enum: [301, 302, 307, 308], title: "Status" },
228
- discardQueryParameters: { type: "boolean", title: "Discard query parameters" },
229
248
  },
230
249
  };
231
250
  case "cms-settings":
@@ -237,7 +237,7 @@ export async function generateSchema(paths: DecoPaths): Promise<SchemaResult> {
237
237
  const ret = nonNullable(returnType);
238
238
  let group: ManifestGroup;
239
239
  if (key === "page") group = "pages";
240
- else if (key === "redirect") group = "redirects";
240
+ else if (key === "redirect" || key === "redirects") group = "redirects";
241
241
  else if (usableReturn && (isJsxType(ret) || isDescriptorType(ret))) group = "sections";
242
242
  else if (usableReturn && isBooleanType(ret)) group = "matchers";
243
243
  else if (propsType && usableReturn && sameType(returnType, propsType)) {