@forumulate/cli 0.20.7 → 0.22.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 (84) hide show
  1. package/CHANGELOG.md +418 -0
  2. package/README.md +1 -0
  3. package/dist/api/operations.json +1 -1
  4. package/dist/cache-command.d.ts +1 -1
  5. package/dist/cache-command.d.ts.map +1 -1
  6. package/dist/check/markdown-links.d.ts.map +1 -1
  7. package/dist/check/markdown-links.js +3 -28
  8. package/dist/check/markdown-links.js.map +1 -1
  9. package/dist/commands/groups-community.d.ts.map +1 -1
  10. package/dist/commands/groups-community.js +6 -0
  11. package/dist/commands/groups-community.js.map +1 -1
  12. package/dist/doctor/command.d.ts +1 -1
  13. package/dist/doctor/command.d.ts.map +1 -1
  14. package/dist/exit-codes.d.ts +7 -1
  15. package/dist/exit-codes.d.ts.map +1 -1
  16. package/dist/exit-codes.js +8 -1
  17. package/dist/exit-codes.js.map +1 -1
  18. package/dist/heartbeat-command.d.ts +14 -5
  19. package/dist/heartbeat-command.d.ts.map +1 -1
  20. package/dist/heartbeat-command.js +72 -18
  21. package/dist/heartbeat-command.js.map +1 -1
  22. package/dist/help-commands.d.ts +18 -11
  23. package/dist/help-commands.d.ts.map +1 -1
  24. package/dist/help-commands.js +69 -13
  25. package/dist/help-commands.js.map +1 -1
  26. package/dist/help.d.ts +1 -1
  27. package/dist/help.d.ts.map +1 -1
  28. package/dist/help.js +13 -4
  29. package/dist/help.js.map +1 -1
  30. package/dist/import/mdx.d.ts.map +1 -1
  31. package/dist/import/mdx.js +6 -15
  32. package/dist/import/mdx.js.map +1 -1
  33. package/dist/known-flags.js +3 -3
  34. package/dist/known-flags.js.map +1 -1
  35. package/dist/plan/cli-release.d.ts +8 -0
  36. package/dist/plan/cli-release.d.ts.map +1 -0
  37. package/dist/plan/cli-release.js +47 -0
  38. package/dist/plan/cli-release.js.map +1 -0
  39. package/dist/plan/command.d.ts +5 -1
  40. package/dist/plan/command.d.ts.map +1 -1
  41. package/dist/plan/command.js +40 -8
  42. package/dist/plan/command.js.map +1 -1
  43. package/dist/plan/conflicts.d.ts +28 -0
  44. package/dist/plan/conflicts.d.ts.map +1 -0
  45. package/dist/plan/conflicts.js +111 -0
  46. package/dist/plan/conflicts.js.map +1 -0
  47. package/dist/plan/document.d.ts +2 -0
  48. package/dist/plan/document.d.ts.map +1 -1
  49. package/dist/plan/document.js +9 -0
  50. package/dist/plan/document.js.map +1 -1
  51. package/dist/plan/domain-lines.d.ts +34 -0
  52. package/dist/plan/domain-lines.d.ts.map +1 -0
  53. package/dist/plan/domain-lines.js +40 -0
  54. package/dist/plan/domain-lines.js.map +1 -0
  55. package/dist/plan/env-out.d.ts +17 -0
  56. package/dist/plan/env-out.d.ts.map +1 -0
  57. package/dist/plan/env-out.js +65 -0
  58. package/dist/plan/env-out.js.map +1 -0
  59. package/dist/plan/output.d.ts +30 -3
  60. package/dist/plan/output.d.ts.map +1 -1
  61. package/dist/plan/output.js +48 -8
  62. package/dist/plan/output.js.map +1 -1
  63. package/dist/plan/pull.d.ts +31 -4
  64. package/dist/plan/pull.d.ts.map +1 -1
  65. package/dist/plan/pull.js +119 -17
  66. package/dist/plan/pull.js.map +1 -1
  67. package/dist/publish/fences.d.ts +17 -0
  68. package/dist/publish/fences.d.ts.map +1 -0
  69. package/dist/publish/fences.js +40 -0
  70. package/dist/publish/fences.js.map +1 -0
  71. package/dist/publish/posts.d.ts.map +1 -1
  72. package/dist/publish/posts.js +2 -1
  73. package/dist/publish/posts.js.map +1 -1
  74. package/dist/run.d.ts.map +1 -1
  75. package/dist/run.js +11 -40
  76. package/dist/run.js.map +1 -1
  77. package/dist/validate.d.ts +1 -1
  78. package/dist/validate.d.ts.map +1 -1
  79. package/dist/version.d.ts +1 -1
  80. package/dist/version.js +1 -1
  81. package/dist/whoami.d.ts +1 -1
  82. package/dist/whoami.d.ts.map +1 -1
  83. package/dist/whoami.js +1 -1
  84. package/package.json +3 -2
package/CHANGELOG.md ADDED
@@ -0,0 +1,418 @@
1
+ # Changelog
2
+
3
+ Releases of `@forumulate/cli`. Earlier versions are described in the git history of
4
+ `packages/cli` (`release(cli): …` commits).
5
+
6
+ ## 0.21.0
7
+
8
+ ### Changed
9
+ - **`apply` refuses a page edited in the studio since the last apply** (exit 5, nothing written) and names each page, who edited it and when. `apply --force` overwrites the edits with your files. Before, apply wrote the file back over the edit silently. The API refuses it too (`409`), so 0.20.x gets the same refusal without `--force` to pass: upgrade, or take the edits in with `pull`.
10
+ - `plan` prints `CONFLICT edited in the studio by <name> at <time>` under such a page and ends with the fix, `forumulate pull <dir> --space <slug> --only <slugs>`. `plan --check` exits 5 on a conflict.
11
+ - `plan --diff` prints a conflicting page's paragraphs, live (`-`) against your file (`+`).
12
+ - A plan never prints a field whose two sides are equal (`url: null -> null`). A secret's change still prints, as `<write-only> (changed, not shown)`.
13
+ - Every command's `--help` ends with its guide's address.
14
+
15
+ ### Added
16
+ - `pull --only a,b`, `pull --diff` (prints, writes nothing) and `pull --kinds pages|legal|faq|posts|releases`. Blog posts and changelog releases come back as one Markdown file each. A drawing, extension block or API operation is kept as a ```` ```forumulate-block ```` fence that `publish` and `apply` read back, and named: `WARN <slug>: block <type> kept as a fenced component`.
17
+ - `sites[].subdomain: <label>` in `forumulate.yaml`: plan prints `+ claim subdomain <label>`, `plan --check` exits 1 while it is not claimed, apply claims it; `subdomain: null` releases it.
18
+ - Exit code 6: this CLI is older than the oldest the API supports (`cli.minimum` on the manifest answer). Nothing is written. A CLI that is merely behind prints one line on stderr: `CLI <x> is available (you run <y>)`.
19
+ - This file ships in the npm package.
20
+
21
+ ## 0.20.7
22
+
23
+ ### Fixed
24
+ - `publish` tells the API which pages a `redirect_from` may retire. The API now refuses to retire a live page without that, so **0.20.6 and older get a clear refusal when a file names a live page other than the one its own name made**. Upgrade to retire pages that way.
25
+ - `publish`: two files with `redirect_from` naming one address write nothing and name both files. Every run used to fail read-back with no reason given.
26
+ - `publish`: the plan names every page it retires, `(bb now redirects here)`, including on an update and when `redirect_from` is the only change.
27
+
28
+ Correction: 0.20.6 said a redirect you add reaches readers at once. That only held for an address nobody had read in the last minute. This note first said the API change made it true everywhere, and it did not: about 1 run in 4 still answered 404 for a minute, because the web tier's own lookups were being rate limited. That was fixed on the API and web side on 2026-11-06.
29
+
30
+ ## 0.20.6
31
+
32
+ ### Fixed
33
+ - `publish`: a `redirect_from` naming a page another file publishes now writes nothing and names both files. It used to take that page off live, fail, and leave a redirect hiding it after the line was removed. A space already stuck that way recovers on its next publish.
34
+ - `publish`: adding or removing `redirect_from` is a change, shown as `update page start redirect_from`, with no other edit. Needs the API of 2026-11-06. Rules written before that date are not withdrawn when the line is removed: remove those in the redirect manager.
35
+ - `redirect_from` as a YAML block list works the same as `[/guide]`.
36
+
37
+ ## 0.20.5
38
+
39
+ ### Fixed
40
+ - `publish`: two files claiming one slug now write nothing in that space, with or without `--strict` or `--prune`. The run used to report the error after overwriting the other page on live, and each rerun flipped which file won. Posts get the same error, which they never had.
41
+ - `publish`: a page a file retires with `redirect_from` is no longer listed as `still live` or in `noFile`. The plan says it now redirects to the new page.
42
+ - `publish --only` no longer claims the whole space matches the folder.
43
+ - `publish`: a component the converter does not know is named as such, rather than blamed on the token.
44
+ - `import mdx`: names code sitting directly inside `<Steps>`, `<Tabs>`, `<CardGroup>` and `<CardGrid>`, which publish refuses.
45
+
46
+ ## 0.20.4
47
+
48
+ ### Fixed
49
+ - `publish`: MDX components in a blog post, changelog release or other post (`<Warning>`, `<Card>`, …) now convert as they do on a docs page, so readers no longer see the tags as text. An `.mdx` post's `import` and `export` lines are removed too. Re-publish affected posts.
50
+ - `publish`: a token that can only read a blog no longer re-sends every post on every run.
51
+ - `publish`: a dead link no longer adds the warning `the run was not recorded (Space not found)`.
52
+ - `publish`: adding `slug:` to a published page no longer makes every later publish fail with `404 Page not found`. It makes a page at the new slug, as changing a slug always has. The old page stays live until `--prune`, or you can add `redirect_from`.
53
+ - `publish --check` works with a read token: unchanged pages report `Nothing to change`, changed ones are named, and a refused comparison is reported as refused rather than as an `update`.
54
+ - `publish`: live pages and posts with no file are named, in text and in `--json` as `noFile`, instead of `the space already matches the folder`. The exit code does not change.
55
+ - `publish`: a link's title (`[x](url "title")`) is stored, served, and kept by the studio editor.
56
+ - `publish --check` names a blog post slug the reader keeps for itself, where it used to pass and the publish then failed.
57
+ - `import mdx`: names loose text inside `<CardGroup>` and `<CardGrid>`, and on its own line inside `<Steps>` and `<Tabs>`.
58
+
59
+ ## 0.20.3
60
+
61
+ ### Fixed
62
+ - **`publish` and `publish --check` missed real edits.** 0.20.2 reported `Nothing to change` and exited 0 for a changed directive, code sample, link or image URL, heading level or emphasis, so the page stayed wrong while CI passed. Older versions missed the link, image and formatting edits too. The API now compares with the converter that would publish the file. Please upgrade.
63
+ - `publish`: no `link to nothing` warning for `/sub/other/`, `./sub/other` or a page's custom `slug:` in the same run, and each dead link warns once.
64
+ - `publish`: a page refused by the import no longer adds a second `404` error.
65
+ - `publish`: blog posts get the same comparison as docs pages, so the same edits are no longer missed there.
66
+ - `import mdx`: names `<Step>` or `<Tab>` outside its wrapper, and text directly inside `<Steps>` or `<Tabs>`.
67
+ - `plan`: a value still in `--vars-file` is masked after the manifest stops using it. With the file gone the CLI cannot know the old value was a secret; `plan --help` says so.
68
+
69
+ ### Known limit
70
+ - MDX components in a blog post are not converted: readers see the tags as text. Fixed in 0.20.4.
71
+
72
+ ## 0.20.2
73
+
74
+ ### Fixed
75
+ - `publish`: a `.md` page with a directive (`:::note`, `:::hint`, `::::tabs`, `> [!NOTE]`) reads as unchanged once stored. Every run re-sent it and exited 1 on the read-back.
76
+ - `publish`: no `link to nothing` warning for a link to a page in the same run.
77
+ - `publish`: a failed run no longer also prints `Nothing to change`.
78
+ - `plan`: the old side of a value set by a variable is masked, and so is a variable set in the shell that the manifest uses.
79
+ - `domains records` names itself when there is no manifest.
80
+
81
+ ## 0.20.1
82
+
83
+ ### Added
84
+ - `plan` and `apply`: `--vars-file <path>`, repeatable. A missing file exits 2. `--env-file` is the old name; Node itself exits 9 on a missing one.
85
+ - `publish --check`: writes nothing and exits 1 on a change or a conflict.
86
+ - `import mdx --json`.
87
+
88
+ ### Changed
89
+ - `plan` and `apply` mask `--vars-file` values of 8 characters or more.
90
+ - An unknown flag on `publish`, `plan`, `apply` or `pull` exits 2 and writes nothing.
91
+ - `pull` skips unchanged pages, keeps folders, and writes fresh front matter.
92
+
93
+ ## 0.20.0
94
+
95
+ ### Added
96
+ - `forumulate pull <folder> --space <s>`: live pages back into the folder.
97
+ - `forumulate import mdx <folder>`: what would publish as literal text, by file and line; exit 1 if anything would.
98
+ - `forumulate init --from-site <folder>`: a first `forumulate.yaml` from the Markdown a site has.
99
+ - `forumulate domains records [file] [--json] [--format cloudflare]`: the DNS records a plan waits for, as data.
100
+ - `plan` and `apply`: `--env-file <path>`, and `--show-secrets` (terminal only).
101
+ - `redirectsFrom:` in a page's front matter in a `pages` folder.
102
+ - `doctor --org` follows each exact redirect rule to its end.
103
+ - `plan --diff` prints a page's final address when its space declares a domain.
104
+
105
+ ### Changed
106
+ - `plan` and `apply` mask declared secrets in everything they print, `--json` and errors included.
107
+
108
+ ## 0.19.1
109
+
110
+ ### Changed
111
+ - `forumulate --help` lists one `publish` form, `publish <folder> --org <org> --space <space>`. The
112
+ positional forms `publish <orgId> <spaceId> <folder|pageId>` were deprecated in 0.11.0; they
113
+ still run and print the form to use on stderr, and `publish --help` names them under
114
+ "Older forms (deprecated in 0.11.0)".
115
+
116
+ ## 0.19.0
117
+
118
+ ### Added
119
+ - COMPARE spaces as code: `forumulate.yaml` takes `compare: { catalog: compare.yaml, matrix: matrix.csv, … }`
120
+ (a `.csv` name is read, other text is sent as written; `publish` syncs it), and page front matter takes
121
+ `comparison:`.
122
+ - `forumulate about get | set | patch | preview | prefill | import | history | undo`: the about page's parts.
123
+ - Careers hiring verbs: applications in bulk, `offer get|set|action`, `ats get|set|sync|disconnect`,
124
+ `indexing get|test|submit`, `google status|key|set|clear`, `indexnow get|set`,
125
+ `subscribers list|export|tag|remove|tags`, `broadcasts list|send`.
126
+ - `forumulate doctor --org <slug|id>`: one report of an organization's wiring — reader sign-in warnings,
127
+ heartbeat staleness, consent and privacy-executor link, subdomain serving.
128
+ - `forumulate.yaml` `readerAuth: { providers, signInUrl }` (declarative: apply replaces, plan shows each
129
+ removed provider and a cleared `signInUrl`) and `privacy: { executor: cookiemunch }`.
130
+
131
+ ### Changed
132
+ - The bundled spec is API version `2027-03-01`: a reader JWT without `email_verified` is read as unverified.
133
+
134
+ ## 0.18.2
135
+
136
+ ### Changed
137
+ - The bundled spec describes `reader-meta`'s new fields: `i18nLocale` (the interface locale its `i18n` part is in; without `?locale=`, the space's declared language) and per-part refusals under `errors`, `chrome` included.
138
+
139
+ ## 0.18.1
140
+
141
+ ### Changed
142
+ - The operation index includes `GET /public/orgs/{orgId}/spaces/{spaceId}/reader-meta`: a space's chrome, SEO, consent and interface strings in one read.
143
+
144
+ ## 0.18.0
145
+
146
+ ### Added
147
+ - `releases: {file, git}` together: the file's releases win, and git drafts fill the periods the file
148
+ doesn't cover. A draft is dropped if the file has its version or a release dated in its period.
149
+ - `git.publish: true | {after: 2d}` (with `cut: day|week`): the API publishes a period's release once
150
+ the period closes.
151
+ - `git.subjects: any` and `changelog import --subjects any`: a commit without a type prefix lists
152
+ under Changed. Merge commits are left out.
153
+
154
+ ## 0.17.0
155
+
156
+ ### Added
157
+ - `releases: {git: {cut: day | week}}`: one draft release per day or ISO week from conventional
158
+ commits, versioned by the period's first day (`2026.11.02`), for a repository that deploys from
159
+ `main` without tags. `since` defaults to the start of the current period. The current period's
160
+ draft is updated with newer commits on each apply until someone edits or publishes it.
161
+
162
+ ### Fixed
163
+ - `plan` no longer reports a change, and `apply` no longer reports `READ BACK DIFFERS`, when
164
+ objects inside a list (`legal.subprocessors.items`, …) are written in a different key order.
165
+ Fixed in the API: the CLI needs no upgrade for this.
166
+
167
+ ## 0.16.0
168
+
169
+ ### Added
170
+ - `changelog import --source conventional-commits [--repo .] [--since <tag|YYYY-MM-DD>] [--include feat,fix,perf] [--release <version>]`:
171
+ release drafts from `git log` for a repository with no CHANGELOG.md. There is one release per tag in range,
172
+ plus one for the untagged commits, named `--release` (default: today, `YYYY.MM.DD`). They are unpublished
173
+ unless `--publish true`; `--dryRun true` lists them and writes nothing.
174
+
175
+ ### Fixed
176
+ - A bare date in `--since` (and in the manifest's `releases: {git: {since}}`) means midnight. Before, git read
177
+ it as that day at the current time of day, so the day's earlier commits were missed.
178
+
179
+ ## 0.15.0
180
+
181
+ From the Hermetica rollout (2026-11-02).
182
+
183
+ ### Added
184
+ - `plan` / `apply` for an organization that does not exist yet: `orgName:` in the file or
185
+ `--create-org`. `plan` prints `+ create org <slug>` and the full list and writes nothing;
186
+ `apply` creates the organization first.
187
+ - `domains[].onUnverified: hold | fail` (default `hold`): a domain whose verification file is not
188
+ served yet stays claimed and prints `waiting: …` with what each proof method saw; every other
189
+ unit applies and `apply` exits 0. Re-apply once the file is served.
190
+ - `--secrets-file` now also holds each heartbeat monitor's ping URL under
191
+ `monitors/<space>/<name>`, on every apply (not only when the monitor was written). The file is
192
+ merged, not replaced, so secrets from earlier applies are kept.
193
+ - `releases: {git: {repo, since, include}}`: one draft release per tag from conventional commits,
194
+ created once, unpublished, for review.
195
+ - The `openapi:` block takes `untaggedTitle` (default "Other endpoints" for new references);
196
+ `plan` prints the untagged count.
197
+
198
+ ## 0.14.1
199
+
200
+ ### Added
201
+ - `plan --help` lists the `tokens` block (API 2026-11-02): an API token of the caller keyed by
202
+ `ref`, its secret written only to `--secrets-file`. 0.14.0 already plans and applies it; the
203
+ block is checked by the API, so no other change was needed.
204
+
205
+ ## 0.14.0
206
+
207
+ From the Advernue rollout (2026-11-02).
208
+
209
+ ### Added
210
+ - `forumulate orgs ensure <slug> [--name] [--external-ref]`: the organization, created only when
211
+ it does not exist (reads `GET /orgs/{slug}`, then `POST /orgs`, which is a get-or-create by
212
+ `externalRef`); safe to re-run, and `--dry-run` prints the write.
213
+ - `forumulate heartbeat ping-url <monitor>`: prints a heartbeat monitor's ping URL.
214
+ - `apply` prints `pingUrl:` under each heartbeat monitor it creates or updates (the API now
215
+ returns it on that step).
216
+ - `domains setup` (space and site) prints `mode`, `pendingReason` when the API sends it, and the
217
+ whole `message`, then the proxy origin and DNS state; `--json` is unchanged.
218
+ - `${NAME}` is expanded inside a string (`url: ${API_URL}/health`), not only as a whole value;
219
+ `$${NAME}` is the literal text. Never inside `pages`/`posts`, and in content and code keys
220
+ (`body`, `customJs`, …) only a whole value.
221
+
222
+ ### Changed
223
+ - `plan`/`apply` against an organization that does not exist add a hint naming
224
+ `forumulate orgs ensure`.
225
+ - `plan` says what its `unchanged` count is made of (`12 unchanged (already as declared:
226
+ settings 4, roles 8)`), and prints the "left alone" line only under `--verbose` (`--json`
227
+ still carries `extras`).
228
+ - The by-hand domain list: a path mount (or a wildcard-DNS name such as nip.io) gets the verification file
229
+ alone, as a URL with its contents, and no DNS TXT line; a proxy step never prints
230
+ `-> undefined`; a kind this CLI does not know is printed with its fields.
231
+
232
+ ## 0.13.0
233
+
234
+ From the Calendoro and Watchtower rollouts (2026-11-01).
235
+
236
+ ### Added
237
+ - `apply --secrets-file <path>`: every shown-once value goes to a 0600 JSON file; stdout and
238
+ `--json` print them redacted.
239
+ - `forumulate heartbeat ping <monitor> [--fail] [--message]`.
240
+ - `forumulate changelog import --file CHANGELOG.md --source keep-a-changelog`.
241
+ - `forumulate members remove-external`.
242
+ - Manifest: `releases:` (CHANGELOG spaces), `legalDocuments:` (LEGAL spaces), `readerIdentity`,
243
+ `domains[].state`, `pages[].ignore`, `pages[].env` / front matter `env: true` (`${NAME}` in
244
+ page bodies; `apply` refuses an unset one unless `--allow-unset-env`), monitor `headers` and
245
+ `json` mapping, front matter `category:` → collection.
246
+ - `FORUMULATE_API` is read as an alias of `FORUMULATE_API_URL`.
247
+
248
+ ### Changed
249
+ - Front matter keys nothing reads are kept on the page as `metadata.frontMatter` instead of
250
+ refusing the file.
251
+ - Two files that derive the same slug from different folders take their folder path
252
+ (`go-install`); declared slugs that still collide are listed together in one error.
253
+ - A relative `.md` link that matches no page is a `plan` warning with file and line.
254
+ - The by-hand domain list prints the verification file next to the TXT record, and says
255
+ "nothing to proxy" when the host is served by Forumulate's own edge.
256
+ - `${ENV}` placeholders work inside one-line `{…}` YAML maps.
257
+
258
+ ## 0.12.3
259
+
260
+ ### Fixed
261
+ - A CSV export the API queues (`202`, past 20,000 rows: `audit export`, form and
262
+ inbox exports, …) waited for nothing and wrote the job's JSON as the file. The CLI
263
+ now follows the job (up to 30 minutes) and writes the finished CSV.
264
+
265
+ ### Added
266
+ - Operations for export jobs (`/orgs/{orgId}/exports/{id}`, `/download`) and the
267
+ public nav children route.
268
+
269
+ ## 0.12.2
270
+
271
+ ### Added
272
+ - `publish` rewrites a relative link to a page that lives in a sibling space on the
273
+ same host (`./slug` → `/guides/slug`), and reports links that resolve nowhere;
274
+ `--strict` fails the run on them. Posts spaces are not checked.
275
+ - Operations for the connector webhook (`/connector/kb/webhook`) and
276
+ `GET /public/domains/sibling-page`.
277
+
278
+ ## 0.12.1
279
+
280
+ ### Fixed
281
+
282
+ - `publish` of a blog with a token issued only `blog:read` + `blog:write` printed its
283
+ plan and then failed `403 rbac.forbidden docs.read`. The API's `/items` reads, a
284
+ space's asset list and upload, and `DELETE …/items/{id}` (prune) now also accept the
285
+ space type's own capability (`blog.read` / `blog.author` on a blog), so a blog-only
286
+ publish needs no `docs.*` scope. Needs the matching API release.
287
+ - `forumulate plan` planned `~ update openapi … (spec, pages)` with `0 new, 0 replaced`
288
+ on every run after a resync (console, deploy hook or `autoResync`) had already
289
+ imported the served spec. It is `unchanged` now; when the spec did change, the plan
290
+ lists the pages it adds, replaces and deletes by slug (`new pages:`, …).
291
+ - An `excerpt:` edit on a blog that declares a standfirst planned as `content` with
292
+ `@ standfirst`. The standfirst is filled from the same words when the file states no
293
+ `standfirst:`; the change is now named `excerpt` (`@ excerpt` under `--diff`).
294
+ - A `consent` block naming its `webhookSecret` (`${ENV}`) planned an update on every
295
+ run; a secret equal to the stored one is no change, and a changed one prints as
296
+ `<write-only>`.
297
+ - A refused `plan`/`apply`, a failed organization lookup in `publish`, and every other
298
+ command's error line print the 422's field paths (`slug: too long`), as `publish`
299
+ already did, instead of a JSON blob or nothing.
300
+
301
+ ## 0.12.0
302
+
303
+ ### Added
304
+
305
+ - `forumulate.yaml` (v2): a blog's `posts` from Markdown files — `body: posts/launch.md`
306
+ on an entry (the entry's own keys win), or `posts: {dir: blog}` for a folder. Front
307
+ matter maps to the fields `publish` reads (`excerpt`/`description`/`summary`, `date`,
308
+ `image`, `tags`, `featured`, `bylines`, …); a key the blog has no name for is sent as a
309
+ declared field for the API to judge; `draft: true` leaves a folder's file out. Relative
310
+ local images in those files are uploaded and rewritten, as `publish` does.
311
+ - `forumulate.yaml` (v2): a value that is exactly `${NAME}` is read from the environment
312
+ (not inside `pages` or `posts`), so a `consent` webhook secret can live in CI's secret
313
+ store. An unset variable stops the run, naming it.
314
+
315
+ ### Fixed
316
+
317
+ - `publish` / `sync` kept only the first 70 characters of a `slug:` a file states, silently.
318
+ It is kept whole up to the API's limit (120 for a blog post, 80 for a docs page); past it
319
+ the run stops, naming the file and the limit.
320
+ - `excerpt` (`description`, `summary`) was not sent for a blog whose shape declares a
321
+ standfirst — the standfirst took it — and the read-back never compared it. It is sent,
322
+ and a changed excerpt plans `excerpt`.
323
+ - `featured: true` on a new post failed with a bare 422; the API now takes `featured`,
324
+ `pinned` and `listed` on create, and `listed` is read from front matter.
325
+ - A 422 in `publish` prints the field paths the API named, not only its sentence.
326
+ - `bylines: [{author: key}]` read back as "did not land" on every run; a registry byline
327
+ is compared by its key. Front matter `author:` that is a registry key credits that
328
+ profile instead of printing the key as a name.
329
+
330
+ ## 0.11.1
331
+
332
+ ### Added
333
+
334
+ - Front matter sets every page setting the page endpoints take, in any casing
335
+ (`schemaType`, `schema_type`, `schema-type`): `schemaType`, `availability`, `navClass`,
336
+ `navData`, `customHead`, `cmsBinding`, `apiLocale`, `nofollow`, `owner`, `related` and
337
+ `lesson` were silently dropped by `publish`, `sync` and `plan`. `plan` also reads `api:` /
338
+ `openapi:` into the page's operation reference, and a `locale:` that contradicts the
339
+ file's folder or suffix is an error instead of a guess.
340
+
341
+ ### Fixed
342
+
343
+ - The default `Forumulate-Version` is the SDK's `API_VERSION` (2027-02-01), imported rather
344
+ than copied. The CLI had kept sending 2026-12-01 while the SDK, the docs and the API's
345
+ newest were 2027-02-01. `--api-version`, `FORUMULATE_API_VERSION` and
346
+ `forumulate config set api-version` still pin another.
347
+ - Paged lists are read from `data` as well as their named key. From 2027-01-01 a list
348
+ answers its rows once, under `data` (lean lists), so `publish`/`plan` (org, space,
349
+ collection and page walks), `spaces`, `domains`, content libraries, library assets and
350
+ translation targets would have seen an empty list under the newer default.
351
+
352
+ ## 0.11.0
353
+
354
+ The output contract, the token named, and publishing that knows what it overwrites.
355
+
356
+ ### Added (DX-D)
357
+
358
+ - `forumulate plan [forumulate.yaml]` / `forumulate apply`: one version-2 document for a
359
+ whole site — spaces with their languages, SEO, translations, front door, contact form
360
+ and About parts; Markdown folders as pages with locale twins (`page.es.md` or
361
+ `es/page.md`; front matter `title`, `slug`, `seoTitle`, `seoDescription`,
362
+ `canonicalUrl`, `sections`, `collection`, `order`); redirects; sites with their config
363
+ and members. `plan` prints the diff (`--diff` field by field, `--check` exits 1 when it
364
+ is not empty); `apply` writes it through `PUT /orgs/{org}/manifest?apply=true` in
365
+ batches (`--batch`), every write read back; `--prune` removes only what the manifest
366
+ wrote. Local images are uploaded once by content hash.
367
+
368
+ ### Added (FMU wave 2c)
369
+
370
+ - `forumulate validate [dir]`: checks `forumulate.yaml`, every Markdown file's front matter
371
+ and any file whose `$schema` names `https://forumulate.com/schemas/2026-12-01/<name>.json`,
372
+ with did-you-mean hints (`footerColumns[].title` → `heading`). Exit 2 when invalid.
373
+ - `forumulate theme explain --space <s>`: the theme the reader renders and the layer behind
374
+ every key (space, site, brand, org, look, default).
375
+ - `forumulate sites brand get|set|refresh|remove <siteId>`: a site's brand file.
376
+
377
+ ### Fixed
378
+
379
+ - `--json` (and every output) piped into another program is no longer cut at 64 KiB /
380
+ 128 KiB. The CLI waits for stdout to drain, sets `process.exitCode`, and exits non-zero
381
+ when a write fails (a full disk, a closed pipe).
382
+ - `publish --help`, `doctor --help` and every other top-level command print their own
383
+ help (every flag, the `forumulate.yaml` keys, exit codes, an example) instead of the
384
+ global page. `forumulate help <command>` prints the same.
385
+
386
+ ### Added
387
+
388
+ - Documented exit codes: 0 ok, 1 failed (read-back mismatch, doctor FAIL), 2 usage,
389
+ 3 auth, 4 not found, 5 conflict.
390
+ - `--out <file>` on every command; `--jsonl` with `--paginate` streams one row per line.
391
+ - `whoami` shows the token source (`--token` › `FORUMULATE_TOKEN` › `credentials.json`),
392
+ the PAT's id, name, last four characters, expiry, narrowing and the API base;
393
+ `auth status --json` for scripts. Unknown `FORUMULATE_*` variables are named with a
394
+ did-you-mean.
395
+ - `api list --refresh`: the live API's operation list (ETag-revalidated), used from then on;
396
+ the footer says whether it counted the bundled or the live list.
397
+ - `publish --purge page|space|none` (default page), reported per CDN (`edge: none` when no
398
+ CDN fronts the addresses); `--json` prints `{space, created, updated, unchanged, trashed,
399
+ purged, verify, diffUrl}`; each run is recorded and fires `publish.completed`
400
+ (`--no-report` to skip).
401
+ - `publish` refuses to overwrite pages edited in the studio since the last publish:
402
+ `CONFLICT <slug> edited in studio by <name> at <time>`, exit 5; `--force` overwrites.
403
+ - `cache purge --space … [--page …]` / `--all-spaces`: drop cached copies, delete nothing.
404
+ - `spaces destroy` / `items destroy` (`--confirm <slug>`): delete a trashed space or page for
405
+ good. `purge` remains as their old name.
406
+ - `spaces list --deleted true` shows `deletedAt` and `purgeAfter` (trash retention).
407
+ - `sites replace` prints the dry-run diff and asks before writing unless `--yes`.
408
+ - `openapi relabel <spec> --landing-slug … --landing-title … --landing-description …`.
409
+ - `doctor`: `canonical-both-addresses`, `sitemap-crawl`, `cache-consistency`,
410
+ `root-redirect`, `meta-description`, `llms-txt`, `favicon`, `consent-tag` (any CMP) and
411
+ `white-label-leaks`; `--site <slug>`, `--json`, exit 1 on any FAIL; a GitHub Action
412
+ template in `examples/github-action-doctor.yml`.
413
+
414
+ ### Deprecated
415
+
416
+ - `publish <orgId> <spaceId> <folder>` and `publish <orgId> <spaceId> <pageId>`: they still
417
+ work and print the form to use instead on stderr. The one form is
418
+ `publish <folder> --org … --space …`.
package/README.md CHANGED
@@ -63,6 +63,7 @@ Every group takes the same verbs (`list`, `get`, `create`, `update`, `delete`, a
63
63
  | `openapi list\|register\|resync\|lint\|import\|generate\|…`, `openapi sdk languages\|get\|download` | OpenAPI specs behind reference pages, and the SDKs generated from them. |
64
64
  | `sdks packages\|register\|publish\|publishes`, `sdks registries list\|set\|test\|remove` | Publishing those SDKs to package registries. |
65
65
  | `blog`, `forum`, `changelog` `list\|get\|create\|update\|publish\|delete\|…` | Articles, topics and releases; scheduling, pinning, settings, flags, polls, replies. `create --file post.md --publish`. |
66
+ | `changelog from-github --space <s> --tag <tag> [--name] [--file notes.md] [--url] [--publish true] [--post '{"space":"blog"}']` | One GitHub release as a changelog draft, for CI on `release: published`; or `--data @payload.json` with the webhook payload. Needs `blog:write`; no GitHub token. See [the CLI guide](https://forumulate.com/guides/cli#release-notes-from-github-changelog-from-github). |
66
67
  | `blog` / `forum` / `changelog` / `status` `translations list\|get\|put\|remove\|auto` | One piece's translations at its own door. `translations` (below) is the whole-space workflow. |
67
68
  | `roadmap board\|get\|submit\|update\|status\|vote\|comment\|merge\|proxy-votes …` | A roadmap space. |
68
69
  | `status board`, `status incidents …`, `status components …`, `status channels …`, `status groups get\|set` | A status space: incidents, components, where they are announced. |