@intentius/chant 0.124.99 → 0.124.101

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 (245) hide show
  1. package/bin/chant +3 -3
  2. package/dist/action-pins.d.ts +2 -0
  3. package/dist/action-pins.js +3 -0
  4. package/dist/ci-detect.d.ts +13 -0
  5. package/dist/ci-detect.js +12 -0
  6. package/dist/ci-system.d.ts +66 -0
  7. package/dist/ci-system.js +61 -0
  8. package/dist/cli/commands/carve-emit.js +2 -2
  9. package/dist/cli/commands/check-lexicon-plugin.d.ts +2 -2
  10. package/dist/cli/commands/check-lexicon-plugin.js +3 -3
  11. package/dist/cli/commands/check-lexicon.js +4 -4
  12. package/dist/cli/commands/init-lexicon/templates/project.d.ts +1 -1
  13. package/dist/cli/commands/init-lexicon/templates/project.js +4 -4
  14. package/dist/cli/commands/init.d.ts +13 -0
  15. package/dist/cli/commands/init.js +30 -2
  16. package/dist/cli/handlers/build.js +27 -0
  17. package/dist/cli/handlers/release-doctor.d.ts +12 -0
  18. package/dist/cli/handlers/release-doctor.js +118 -0
  19. package/dist/cli/handlers/release-init.d.ts +10 -0
  20. package/dist/cli/handlers/release-init.js +342 -0
  21. package/dist/cli/handlers/release.d.ts +50 -1
  22. package/dist/cli/handlers/release.js +688 -30
  23. package/dist/cli/handlers/run-generate.js +11 -0
  24. package/dist/cli/main.d.ts +2 -0
  25. package/dist/cli/main.js +45 -97
  26. package/dist/cli/parse-args.js +55 -0
  27. package/dist/cli/registry.d.ts +18 -0
  28. package/dist/cli/release-commands/artifacts.d.ts +3 -0
  29. package/dist/cli/release-commands/artifacts.js +14 -0
  30. package/dist/cli/release-commands/candidates.d.ts +3 -0
  31. package/dist/cli/release-commands/candidates.js +16 -0
  32. package/dist/cli/release-commands/changed.d.ts +3 -0
  33. package/dist/cli/release-commands/changed.js +14 -0
  34. package/dist/cli/release-commands/compose.d.ts +3 -0
  35. package/dist/cli/release-commands/compose.js +16 -0
  36. package/dist/cli/release-commands/cut.d.ts +3 -0
  37. package/dist/cli/release-commands/cut.js +49 -0
  38. package/dist/cli/release-commands/doctor.d.ts +3 -0
  39. package/dist/cli/release-commands/doctor.js +14 -0
  40. package/dist/cli/release-commands/export.d.ts +3 -0
  41. package/dist/cli/release-commands/export.js +12 -0
  42. package/dist/cli/release-commands/images.d.ts +3 -0
  43. package/dist/cli/release-commands/images.js +13 -0
  44. package/dist/cli/release-commands/index.d.ts +8 -0
  45. package/dist/cli/release-commands/index.js +52 -0
  46. package/dist/cli/release-commands/init.d.ts +3 -0
  47. package/dist/cli/release-commands/init.js +16 -0
  48. package/dist/cli/release-commands/list.d.ts +3 -0
  49. package/dist/cli/release-commands/list.js +10 -0
  50. package/dist/cli/release-commands/next.d.ts +3 -0
  51. package/dist/cli/release-commands/next.js +13 -0
  52. package/dist/cli/release-commands/publish.d.ts +3 -0
  53. package/dist/cli/release-commands/publish.js +22 -0
  54. package/dist/cli/release-commands/stamp.d.ts +3 -0
  55. package/dist/cli/release-commands/stamp.js +15 -0
  56. package/dist/cli/release-commands/status.d.ts +3 -0
  57. package/dist/cli/release-commands/status.js +17 -0
  58. package/dist/cli/release-commands/tag.d.ts +3 -0
  59. package/dist/cli/release-commands/tag.js +12 -0
  60. package/dist/cli/release-commands/types.d.ts +20 -0
  61. package/dist/cli/release-commands/types.js +1 -0
  62. package/dist/cli/release-commands/verify.d.ts +3 -0
  63. package/dist/cli/release-commands/verify.js +15 -0
  64. package/dist/cli/release-commands/workflow.d.ts +3 -0
  65. package/dist/cli/release-commands/workflow.js +13 -0
  66. package/dist/codegen/pinned-upgrade.js +1 -1
  67. package/dist/components/capability-plugin.d.ts +1 -1
  68. package/dist/components/capability-plugin.js +1 -1
  69. package/dist/components/cli-support.d.ts +1 -1
  70. package/dist/components/cli-support.js +1 -1
  71. package/dist/config-environments.d.ts +8 -1
  72. package/dist/config-environments.js +2 -0
  73. package/dist/config.d.ts +299 -6
  74. package/dist/config.js +102 -5
  75. package/dist/dead-guards.d.ts +5 -1
  76. package/dist/dead-guards.js +34 -23
  77. package/dist/discovery/sandbox/driver.js +1 -1
  78. package/dist/discovery/specifier-resolve.js +1 -1
  79. package/dist/floor-table.d.ts +3 -1
  80. package/dist/floor-table.data.js +23 -3
  81. package/dist/floor-table.js +4 -3
  82. package/dist/forge-remote.d.ts +13 -0
  83. package/dist/forge-remote.js +15 -0
  84. package/dist/lexicon.d.ts +41 -2
  85. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts +62 -0
  86. package/dist/lifecycle/__fixtures__/publish-fakes.js +270 -3
  87. package/dist/lifecycle/publish-attachments.d.ts +2 -1
  88. package/dist/lifecycle/publish-attachments.js +19 -2
  89. package/dist/lifecycle/publish-cargo.d.ts +99 -0
  90. package/dist/lifecycle/publish-cargo.js +412 -0
  91. package/dist/lifecycle/publish-credentials.d.ts +1 -1
  92. package/dist/lifecycle/publish-credentials.js +8 -0
  93. package/dist/lifecycle/publish-declaration.d.ts +199 -4
  94. package/dist/lifecycle/publish-declaration.js +200 -9
  95. package/dist/lifecycle/publish-forge.d.ts +45 -2
  96. package/dist/lifecycle/publish-forge.js +434 -34
  97. package/dist/lifecycle/publish-git-ssh.d.ts +15 -0
  98. package/dist/lifecycle/publish-git-ssh.js +30 -4
  99. package/dist/lifecycle/publish-github.d.ts +40 -2
  100. package/dist/lifecycle/publish-github.js +100 -3
  101. package/dist/lifecycle/publish-homebrew.d.ts +7 -9
  102. package/dist/lifecycle/publish-homebrew.js +34 -197
  103. package/dist/lifecycle/publish-index.d.ts +141 -0
  104. package/dist/lifecycle/publish-index.js +719 -0
  105. package/dist/lifecycle/publish-marketplace.js +77 -0
  106. package/dist/lifecycle/publish-mcp-registry.d.ts +66 -0
  107. package/dist/lifecycle/publish-mcp-registry.js +306 -0
  108. package/dist/lifecycle/publish-npm.js +165 -2
  109. package/dist/lifecycle/publish-oci.d.ts +34 -1
  110. package/dist/lifecycle/publish-oci.js +246 -7
  111. package/dist/lifecycle/publish-pypi.d.ts +136 -0
  112. package/dist/lifecycle/publish-pypi.js +657 -0
  113. package/dist/lifecycle/publish-record.d.ts +6 -3
  114. package/dist/lifecycle/publish-record.js +6 -3
  115. package/dist/lifecycle/publish-signing.d.ts +147 -0
  116. package/dist/lifecycle/publish-signing.js +257 -0
  117. package/dist/lifecycle/publish-targets.d.ts +27 -1
  118. package/dist/lifecycle/publish-targets.js +80 -0
  119. package/dist/lifecycle/publish-tauri.js +43 -0
  120. package/dist/lifecycle/publish-train-names.d.ts +54 -0
  121. package/dist/lifecycle/publish-train-names.js +118 -0
  122. package/dist/lifecycle/publish-verify.d.ts +121 -0
  123. package/dist/lifecycle/publish-verify.js +130 -0
  124. package/dist/lifecycle/query.js +8 -0
  125. package/dist/lifecycle/release-artifacts.d.ts +212 -0
  126. package/dist/lifecycle/release-artifacts.js +571 -0
  127. package/dist/lifecycle/release-changelog.d.ts +13 -1
  128. package/dist/lifecycle/release-changelog.js +35 -2
  129. package/dist/lifecycle/release-cut.d.ts +58 -3
  130. package/dist/lifecycle/release-cut.js +132 -34
  131. package/dist/lifecycle/release-doctor.d.ts +113 -0
  132. package/dist/lifecycle/release-doctor.js +996 -0
  133. package/dist/lifecycle/release-green.d.ts +86 -0
  134. package/dist/lifecycle/release-green.js +286 -0
  135. package/dist/lifecycle/release-init.d.ts +255 -0
  136. package/dist/lifecycle/release-init.js +859 -0
  137. package/dist/lifecycle/release-intents.d.ts +73 -0
  138. package/dist/lifecycle/release-intents.js +128 -0
  139. package/dist/lifecycle/release-next.d.ts +111 -0
  140. package/dist/lifecycle/release-next.js +252 -0
  141. package/dist/lifecycle/release-prerelease.d.ts +19 -0
  142. package/dist/lifecycle/release-prerelease.js +30 -0
  143. package/dist/lifecycle/release-publish.d.ts +256 -10
  144. package/dist/lifecycle/release-publish.js +246 -34
  145. package/dist/lifecycle/release-status-change.d.ts +226 -0
  146. package/dist/lifecycle/release-status-change.js +478 -0
  147. package/dist/lifecycle/release-status.d.ts +11 -0
  148. package/dist/lifecycle/release-status.js +1 -1
  149. package/dist/lifecycle/release-store.d.ts +73 -2
  150. package/dist/lifecycle/release-store.js +32 -1
  151. package/dist/lifecycle/release-tag.d.ts +142 -0
  152. package/dist/lifecycle/release-tag.js +323 -0
  153. package/dist/lifecycle/release-verify.d.ts +73 -1
  154. package/dist/lifecycle/release-verify.js +117 -2
  155. package/dist/lifecycle/release-version-formats.d.ts +73 -0
  156. package/dist/lifecycle/release-version-formats.js +570 -0
  157. package/dist/lifecycle/release-version.d.ts +58 -10
  158. package/dist/lifecycle/release-version.js +164 -36
  159. package/dist/lifecycle/release-workstation.d.ts +3 -2
  160. package/dist/lifecycle/release-workstation.js +3 -2
  161. package/dist/module-source.d.ts +2 -2
  162. package/dist/module-source.js +8 -8
  163. package/dist/op/generate-pipeline.js +1 -1
  164. package/dist/pr-forge-base.js +4 -2
  165. package/dist/pr-forge.d.ts +20 -2
  166. package/dist/pr-forge.js +46 -10
  167. package/dist/release-floors.d.ts +10 -1
  168. package/dist/release-floors.js +10 -1
  169. package/dist/tool-pins.d.ts +38 -0
  170. package/dist/tool-pins.js +54 -0
  171. package/dist/ts-loader.d.ts +1 -1
  172. package/dist/ts-loader.js +6 -6
  173. package/dist/wave-runtime.mjs +337 -334
  174. package/dist/workspace/ci-forge.d.ts +17 -0
  175. package/dist/workspace/ci-forge.js +17 -0
  176. package/dist/workspace/ci-init.js +1 -1
  177. package/dist/workspace/composites.schema.json +1 -0
  178. package/dist/workspace/declaration.d.ts +8 -0
  179. package/dist/workspace/declaration.js +12 -0
  180. package/dist/workspace/declaration.schema.json +8 -0
  181. package/dist/workspace/environments.d.ts +2 -0
  182. package/dist/workspace/environments.js +1 -1
  183. package/dist/workspace/identity-gate-rule.d.ts +61 -5
  184. package/dist/workspace/identity-gate-rule.js +81 -12
  185. package/dist/workspace/member-pipeline.d.ts +2 -1
  186. package/dist/workspace/member-pipeline.js +5 -2
  187. package/dist/workspace/reason-codes.d.ts +6 -0
  188. package/dist/workspace/reason-codes.js +8 -1
  189. package/dist/workspace/release-changed.d.ts +179 -0
  190. package/dist/workspace/release-changed.js +625 -0
  191. package/dist/workspace/release-changed.schema.json +206 -0
  192. package/dist/workspace/release-steps/artifacts.d.ts +7 -0
  193. package/dist/workspace/release-steps/artifacts.js +45 -0
  194. package/dist/workspace/release-steps/builds.d.ts +12 -0
  195. package/dist/workspace/release-steps/builds.js +38 -0
  196. package/dist/workspace/release-steps/doctor.d.ts +8 -0
  197. package/dist/workspace/release-steps/doctor.js +14 -0
  198. package/dist/workspace/release-steps/goreleaser.d.ts +16 -0
  199. package/dist/workspace/release-steps/goreleaser.js +36 -0
  200. package/dist/workspace/release-steps/green.d.ts +3 -0
  201. package/dist/workspace/release-steps/green.js +6 -0
  202. package/dist/workspace/release-steps/images.d.ts +22 -0
  203. package/dist/workspace/release-steps/images.js +59 -0
  204. package/dist/workspace/release-steps/index.d.ts +9 -0
  205. package/dist/workspace/release-steps/index.js +46 -0
  206. package/dist/workspace/release-steps/pypi.d.ts +15 -0
  207. package/dist/workspace/release-steps/pypi.js +21 -0
  208. package/dist/workspace/release-steps/qemu.d.ts +21 -0
  209. package/dist/workspace/release-steps/qemu.js +35 -0
  210. package/dist/workspace/release-steps/signing.d.ts +18 -0
  211. package/dist/workspace/release-steps/signing.js +30 -0
  212. package/dist/workspace/release-steps/stamp.d.ts +3 -0
  213. package/dist/workspace/release-steps/stamp.js +4 -0
  214. package/dist/workspace/release-steps/targets.d.ts +31 -0
  215. package/dist/workspace/release-steps/targets.js +40 -0
  216. package/dist/workspace/release-steps/types.d.ts +104 -0
  217. package/dist/workspace/release-steps/types.js +2 -0
  218. package/dist/workspace/release-steps/verify.d.ts +3 -0
  219. package/dist/workspace/release-steps/verify.js +4 -0
  220. package/dist/workspace/release-toolchains.d.ts +59 -0
  221. package/dist/workspace/release-toolchains.js +133 -0
  222. package/dist/workspace/release-train-workflow.d.ts +29 -0
  223. package/dist/workspace/release-train-workflow.js +85 -0
  224. package/dist/workspace/release-train.d.ts +3 -1
  225. package/dist/workspace/release-train.js +20 -3
  226. package/dist/workspace/release-workflow.d.ts +160 -61
  227. package/dist/workspace/release-workflow.js +539 -193
  228. package/dist/workspace/releases.schema.json +70 -1
  229. package/dist/workspace/search-contract.d.ts +1 -1
  230. package/dist/workspace/security.js +9 -2
  231. package/dist/workspace/train-cut.d.ts +182 -0
  232. package/dist/workspace/train-cut.js +482 -0
  233. package/dist/workspace/train-prepare.d.ts +61 -0
  234. package/dist/workspace/train-prepare.js +267 -0
  235. package/dist/workspace/train-publish.d.ts +177 -0
  236. package/dist/workspace/train-publish.js +575 -0
  237. package/dist/workspace/train-range-labels.d.ts +33 -0
  238. package/dist/workspace/train-range-labels.js +109 -0
  239. package/dist/workspace/trust/seal.d.ts +13 -3
  240. package/dist/workspace/trust/seal.js +14 -4
  241. package/dist/workspace/work-cli.d.ts +3 -2
  242. package/dist/workspace/work-cli.js +3 -2
  243. package/dist/workspace/workspace-ledger.d.ts +14 -1
  244. package/dist/workspace/workspace-ledger.js +33 -7
  245. package/package.json +26 -26
@@ -0,0 +1,478 @@
1
+ /**
2
+ * Deprecate, yank and restore a published release (#5163):
3
+ * `chant release deprecate|yank|restore <label|digest>`.
4
+ *
5
+ * A change is one status record (./release-status.ts) and what each publish
6
+ * target does about it:
7
+ *
8
+ * - `deprecate` sets `deprecated`. Consumers keep resolving the release and
9
+ * are warned: npm marks each version with `npm deprecate`. A registry, a
10
+ * forge release and a formula have no deprecation, so nothing changes there.
11
+ * - `yank` sets `yanked`. New consumers stop resolving the release: npm
12
+ * deprecates each version and moves the dist-tag back, the OCI target moves
13
+ * its moving tags back, the forge release becomes a prerelease, a draft or
14
+ * is deleted, and a tap's formula is reverted. "Back" is the head: the
15
+ * newest release of the same line that is active, not revoked and was
16
+ * revealed on that target. The line is the channel the release was cut
17
+ * for, else, for a prerelease label (#5166), its npm dist-tag (`rc`), else
18
+ * the stable line, so a yanked `1.4.0-rc.2` moves `rc` back to `1.4.0-rc.1`
19
+ * and a yanked stable release never moves `latest` onto a prerelease.
20
+ * - `restore` sets `active` again and undoes what the target can: npm clears
21
+ * the message, a forge release is published again, and when the release is
22
+ * the head again the moving tags and the formula point at it.
23
+ *
24
+ * The floating tag (`release.tag.floating`, #5150), such as `v1`, is one
25
+ * more step: a yank of the stable release it names moves it back to the
26
+ * highest active stable release of that major, and a restore moves it
27
+ * forward when the release is that one again. The release's own tag, as
28
+ * `release.tag` renders it, names the forge release.
29
+ *
30
+ * What went out is read from the publish record (`_releases/publishes.jsonl`,
31
+ * ./publish-record.ts), never the checkout, so a change runs from any
32
+ * checkout of the member. A target the release was not revealed on is left
33
+ * alone.
34
+ *
35
+ * The status record goes to `_releases/release-status.jsonl` with `env`
36
+ * `_releases` and the member as `component`, and each target's actions to
37
+ * `_releases/status-actions.jsonl`, both on `chant/lifecycle` and pushed as
38
+ * they are written. A change that stopped part way resumes: run the same
39
+ * command again, and the latest status record, when it already sets the same
40
+ * status, is the change resumed, and a target with an actions line for it is
41
+ * skipped.
42
+ *
43
+ * Under an `identity.gates.release` entry a change must be signed by a signer
44
+ * in the gate's class, as a cut must (`admitReleaseStatus`).
45
+ */
46
+ import { execFileSync } from "node:child_process";
47
+ import { renderFloatingTag, stableVersionOf } from "./release-tag.js";
48
+ import { PublishTargetError, moveFloatingTag } from "./release-publish.js";
49
+ import { prereleaseOf } from "./release-prerelease.js";
50
+ export const STATUS_OF = { deprecate: "deprecated", yank: "yanked", restore: "active" };
51
+ /** The file each target's actions are appended to, under `_releases/`. */
52
+ export const STATUS_ACTIONS_FILE = "status-actions.jsonl";
53
+ /** The ledger directory a status record of a cut release goes to: the release's own, `_releases`. */
54
+ export const RELEASE_STATUS_LEDGER = "_releases";
55
+ /** Parse `status-actions.jsonl`. A line that is not a record is skipped. */
56
+ export function parseStatusActions(text) {
57
+ const out = [];
58
+ for (const line of (text ?? "").split("\n").map((l) => l.trim()).filter(Boolean)) {
59
+ try {
60
+ const r = JSON.parse(line);
61
+ if (r && r.version === 1 && typeof r.releaseDigest === "string" && typeof r.statusAt === "string" && typeof r.target === "string" && Array.isArray(r.actions))
62
+ out.push(r);
63
+ }
64
+ catch {
65
+ // A line that is not JSON is skipped.
66
+ }
67
+ }
68
+ return out;
69
+ }
70
+ /** A change that stopped at a target. */
71
+ export class StatusRunError extends PublishTargetError {
72
+ constructor(code, message, fix, done) {
73
+ super(code, message, fix);
74
+ this.done = done;
75
+ this.name = "StatusRunError";
76
+ }
77
+ }
78
+ /** The line of a release cut for `channel` with `label` (#5166): the channel, else the prerelease's dist-tag, else null. */
79
+ export function lineOf(channel, label) {
80
+ return channel ?? prereleaseOf(label)?.distTag ?? null;
81
+ }
82
+ /**
83
+ * The head of `target`: among `known` releases of `line` ({@link lineOf}), the newest whose
84
+ * status (with `override` applied for one digest) is active, that is not
85
+ * revoked and that the record says was revealed on the target.
86
+ */
87
+ export function headOn(key, known, line, statusOfDigest, revoked, revealedOn, tagOf) {
88
+ const candidates = known
89
+ .filter((k) => k.line === line && statusOfDigest(k.release.releaseDigest) === "active" && !revoked(k.release) && revealedOn(k.release.releaseDigest, key) !== undefined)
90
+ .sort((a, b) => (a.firstCut < b.firstCut ? -1 : a.firstCut > b.firstCut ? 1 : 0));
91
+ const top = candidates.at(-1);
92
+ return top ? { releaseDigest: top.release.releaseDigest, label: top.label, releaseTag: tagOf(top.label), items: revealedOn(top.release.releaseDigest, key) } : null;
93
+ }
94
+ /**
95
+ * The floating tag's step (#5150), or null when the release moves none: no
96
+ * `release.tag.floating`, a prerelease or non-version label, or a cut for a
97
+ * channel. Among the stable releases of the same major cut with no channel
98
+ * that are active (with this change applied), not revoked and published, the
99
+ * highest version is where the tag belongs, as `floatingTagPlan` moves it at
100
+ * publish. A yank moves it there when it names this release's commit; a
101
+ * restore moves it to this release when it is that one.
102
+ */
103
+ export function floatingTagStep(o) {
104
+ const { tags, label } = o;
105
+ if (label === null || o.channel !== null)
106
+ return null;
107
+ const name = renderFloatingTag(tags.template, tags.place, label);
108
+ if (name === null)
109
+ return null;
110
+ const floatingOf = (l) => {
111
+ if (l === null)
112
+ return null;
113
+ try {
114
+ return renderFloatingTag(tags.template, tags.place, l);
115
+ }
116
+ catch {
117
+ return null;
118
+ }
119
+ };
120
+ const cmp = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
121
+ const best = o.known
122
+ .filter((k) => k.channel === null && floatingOf(k.label) === name && o.statusOfDigest(k.release.releaseDigest) === "active" && !o.revoked(k.release) && o.published(k.release.releaseDigest))
123
+ .map((k) => ({ k, v: stableVersionOf(k.label) }))
124
+ .sort((a, b) => cmp(a.v, b.v))
125
+ .at(-1)?.k;
126
+ const ours = o.release.commit;
127
+ const tagCommit = o.tagCommit ?? ((n) => localTagCommit(o.cwd, n));
128
+ const move = o.move ?? ((n, commit) => moveFloatingTag(o.cwd, { name: n, commit, move: true, reason: null }));
129
+ return {
130
+ name,
131
+ async setStatus(ctx) {
132
+ if (ctx.status === "deprecated")
133
+ return [{ what: `${name} unchanged: a deprecated release keeps it; yank moves it`, already: true }];
134
+ if (ctx.status === "active" && best?.release.releaseDigest !== o.release.releaseDigest) {
135
+ return [{ what: `${name} unchanged: ${best?.label ?? "another release"} is the highest active release of its major`, already: true }];
136
+ }
137
+ const to = ctx.status === "active" ? o.release : best?.release;
138
+ const toName = ctx.status === "active" ? label : best?.label;
139
+ if (!to) {
140
+ return [{
141
+ what: `${name} stays where it is`,
142
+ refused: { code: "release-status-no-previous", message: `no other active release of the major ${label} is in was published, so ${name} has nowhere to move back to`, fix: `Cut and publish a release of that major, restore an earlier one, or delete the tag by hand: git push --delete origin refs/tags/${name}` },
143
+ }];
144
+ }
145
+ const what = ctx.status === "active" ? `move ${name} to ${toName} (${to.commit.slice(0, 12)})` : `move ${name} back to ${toName} (${to.commit.slice(0, 12)}), if it names ${label}`;
146
+ if (!ctx.apply)
147
+ return [{ what }];
148
+ const now = tagCommit(name);
149
+ if (now === to.commit || (ctx.status === "yanked" && now !== ours))
150
+ return [{ what: `${name} names ${now ? now.slice(0, 12) : "nothing"}; not moved`, already: true }];
151
+ const warning = move(name, to.commit);
152
+ if (warning)
153
+ throw new PublishTargetError("release-status-tag-failed", warning);
154
+ ctx.log(`moved ${name} to ${to.commit.slice(0, 12)}`);
155
+ return [{ what }];
156
+ },
157
+ };
158
+ }
159
+ /** The commit the tag `name` names, after fetching it from origin when it can; null when there is none. */
160
+ function localTagCommit(cwd, name) {
161
+ const git = (args) => execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
162
+ try {
163
+ git(["fetch", "--quiet", "--force", "origin", `refs/tags/${name}:refs/tags/${name}`]);
164
+ }
165
+ catch {
166
+ // No origin, or the remote has no such tag: the local tag is what there is.
167
+ }
168
+ try {
169
+ return git(["rev-parse", "--verify", "--quiet", `refs/tags/${name}^{commit}`]);
170
+ }
171
+ catch {
172
+ return null;
173
+ }
174
+ }
175
+ /**
176
+ * Resolve `ref` in the member at `cwd` and plan the change: the status
177
+ * record it writes, or the one it resumes, and what each target would do.
178
+ * Reads the local `chant/lifecycle` and the tags; asks no registry.
179
+ */
180
+ export async function prepareStatusChange(req) {
181
+ const { resolveRelease, readCuts, readAllReleases, labelsByDigest } = await import("./release-store.js");
182
+ const { readReleaseStatus, statusOf } = await import("./release-status.js");
183
+ const { readBlobFromPath } = await import("./git.js");
184
+ const { parsePublishRecords, PUBLISHES_FILE } = await import("./publish-record.js");
185
+ const { scopeSource } = await import("../workspace/write-scope.js");
186
+ const { releaseRuleFrom } = await import("../workspace/identity.js");
187
+ const { createRedactor } = await import("./publish-credentials.js");
188
+ const { cwd, ref, verb } = req;
189
+ const loc = { cwd };
190
+ const found = await resolveRelease(ref, loc);
191
+ if (!found)
192
+ return { refusal: { code: "release-not-found", message: `no release is labelled or digested "${ref}" in this member`, fix: "List them with: chant release list" } };
193
+ const { release, label } = found;
194
+ const name = label ?? release.releaseDigest;
195
+ const status = STATUS_OF[verb];
196
+ const { resolveMemberLedger } = await import("./member-ledger.js");
197
+ const { releaseTagName } = await import("./release-workstation.js");
198
+ const ledger = await resolveMemberLedger(cwd).catch(() => ({ members: [] }));
199
+ const member = ledger.members.length > 0 ? ledger.members.join("/") : null;
200
+ const component = member ?? ".";
201
+ // #5150: the tag release.tag renders for a label, as the cut made it; the legacy tag when it can't be read.
202
+ const { memberTags, renderReleaseTag } = await import("./release-tag.js");
203
+ const tags = await memberTags(cwd).catch(() => null);
204
+ const tagOf = (l) => {
205
+ if (l === null)
206
+ return null;
207
+ if (tags) {
208
+ try {
209
+ return renderReleaseTag(tags.template, tags.place, l);
210
+ }
211
+ catch {
212
+ // A template this label can't fill: the legacy tag.
213
+ }
214
+ }
215
+ return releaseTagName(member, l);
216
+ };
217
+ const statusRecords = (await readReleaseStatus(RELEASE_STATUS_LEDGER, loc)).records;
218
+ const current = statusOf(statusRecords, component, release.releaseDigest);
219
+ const resumes = current.record && current.status === status ? current.record : null;
220
+ if (verb === "restore" && !current.record) {
221
+ return { refusal: { code: "release-status-unchanged", message: `${name} was never deprecated or yanked, so there is nothing to restore`, fix: "Deprecate or yank it with chant release deprecate|yank." } };
222
+ }
223
+ if (verb === "deprecate" && current.status === "yanked") {
224
+ return {
225
+ refusal: {
226
+ code: "release-status-yanked",
227
+ message: `${name} is yanked, and a deprecation would leave its tags moved and its forge release withdrawn while the record says only deprecated`,
228
+ fix: `Restore it first, then deprecate it: chant release restore ${name} --yes`,
229
+ },
230
+ };
231
+ }
232
+ const rule = releaseRuleFrom(scopeSource(cwd));
233
+ if (rule.requirement && !req.sign && !resumes) {
234
+ return {
235
+ refusal: {
236
+ code: "release-unsigned",
237
+ message: `chant.workspace.json at base names a release gate in identity.gates${rule.requirement.class !== null ? `, from the class ${rule.requirement.class}` : ""}, and this status change is not signed`,
238
+ fix: `chant release ${verb} ${name} --actor <principal> --sign [<key file>], with a key ${rule.rule.signers.signersPath} at base lists for that principal.`,
239
+ },
240
+ };
241
+ }
242
+ const env = req.env ?? process.env;
243
+ let targets;
244
+ try {
245
+ const { releasePublishTargets } = await import("./release-publish.js");
246
+ targets = await releasePublishTargets(cwd, req.deps);
247
+ }
248
+ catch (err) {
249
+ return { refusal: { code: "publish-config-invalid", message: `the publish targets can't be read: ${err instanceof Error ? err.message : String(err)}`, fix: "Fix release.publish in chant.config.ts." } };
250
+ }
251
+ const redactor = createRedactor(env, targets.flatMap((t) => t.credentialEnv));
252
+ // What each release revealed on each target, from the publish record.
253
+ const records = parsePublishRecords(await readBlobFromPath(RELEASE_STATUS_LEDGER, PUBLISHES_FILE, loc)).records;
254
+ const revealed = new Map();
255
+ const revealedNames = new Map();
256
+ for (const r of records) {
257
+ if (r.step !== "revealed")
258
+ continue;
259
+ revealed.set(`${r.releaseDigest}\u0000${r.target}`, r.items);
260
+ if (r.releaseDigest === release.releaseDigest)
261
+ revealedNames.set(r.target, r.name);
262
+ }
263
+ const revealedOn = (digest, key) => revealed.get(`${digest}\u0000${key}`);
264
+ // Every release of the member, in the order first cut, with its channel.
265
+ const { cuts } = await readCuts(loc);
266
+ const labels = labelsByDigest(cuts);
267
+ const { releases } = await readAllReleases(loc);
268
+ const known = [];
269
+ for (const r of releases) {
270
+ const mine = cuts.filter((c) => c.releaseDigest === r.releaseDigest);
271
+ if (mine.length === 0)
272
+ continue;
273
+ const firstCut = mine.map((c) => c.timestamp).sort()[0];
274
+ const channel = [...mine].reverse().find((c) => c.channel)?.channel ?? null;
275
+ const l = labels.get(r.releaseDigest) ?? null;
276
+ known.push({ release: r, label: l, firstCut, channel, line: lineOf(channel, l) });
277
+ }
278
+ const channel = known.find((k) => k.release.releaseDigest === release.releaseDigest)?.channel ?? [...cuts].reverse().find((c) => c.releaseDigest === release.releaseDigest && c.channel)?.channel ?? null;
279
+ const releaseLine = lineOf(channel, label);
280
+ const { readRevokedCommits } = await import("./release-revocation.js");
281
+ const revokedCommits = await readRevokedCommits(cwd).catch(() => new Map());
282
+ const statusOfDigest = (digest) => (digest === release.releaseDigest ? status : statusOf(statusRecords, component, digest).status);
283
+ // A change resumed carries out the record's words, not this run's.
284
+ const reason = resumes ? (resumes.reason ?? null) : (req.reason ?? null);
285
+ const replacement = resumes ? (resumes.replacement ?? null) : (req.replacement ?? null);
286
+ const forgeYank = req.forgeYank ?? "prerelease";
287
+ const actionsDone = resumes
288
+ ? new Set(parseStatusActions(await readBlobFromPath(RELEASE_STATUS_LEDGER, STATUS_ACTIONS_FILE, loc)).filter((a) => a.releaseDigest === release.releaseDigest && a.statusAt === resumes.timestamp).map((a) => a.target))
289
+ : new Set();
290
+ const log = req.log ?? (() => undefined);
291
+ const ctxFor = (revealed, head) => ({
292
+ cwd,
293
+ env,
294
+ redactor,
295
+ log: (line) => log(redactor.redact(line)),
296
+ provenance: { oidc: false, ci: null, reason: "a status change publishes nothing" },
297
+ tag: channel,
298
+ release,
299
+ label,
300
+ releaseTag: tagOf(label),
301
+ status,
302
+ reason,
303
+ replacement,
304
+ revealed,
305
+ head,
306
+ forgeYank,
307
+ apply: false,
308
+ });
309
+ const planned = [];
310
+ for (const target of targets) {
311
+ const base = { kind: target.kind, name: target.name, key: target.key, destination: target.destination };
312
+ const items = revealedOn(release.releaseDigest, target.key);
313
+ if (!items) {
314
+ planned.push({ ...base, skip: "the release was not published to it", done: false, actions: [], head: null });
315
+ continue;
316
+ }
317
+ const head = headOn(target.key, known, releaseLine, statusOfDigest, (r) => revokedCommits.has(r.commit), revealedOn, tagOf);
318
+ const ctx = ctxFor(items, head);
319
+ const actions = target.setStatus
320
+ ? await target.setStatus(ctx)
321
+ : [{ what: `${target.name} unchanged`, refused: { code: "release-status-unsupported", message: `a ${target.kind} target can't deprecate, yank or restore a version`, fix: `Change ${target.destination} by hand.` } }];
322
+ planned.push({ ...base, done: actionsDone.has(target.key), actions, head, target, ctx });
323
+ }
324
+ const floating = tags ? floatingTagStep({ cwd, tags, known, release, label, channel, statusOfDigest, revoked: (r) => revokedCommits.has(r.commit), published: (d) => targets.length === 0 || [...revealed.keys()].some((k) => k.startsWith(`${d}\u0000`)) }) : null;
325
+ if (floating) {
326
+ const ctx = ctxFor([], null);
327
+ planned.push({ kind: "git-tag", name: `floating tag ${floating.name}`, key: `floating-tag:${floating.name}`, destination: `the git tag ${floating.name}`, done: actionsDone.has(`floating-tag:${floating.name}`), actions: await floating.setStatus(ctx), head: null, target: floating, ctx });
328
+ }
329
+ const declared = new Set(targets.map((t) => t.key));
330
+ const undeclared = [...revealedNames].filter(([key]) => !declared.has(key)).map(([, n]) => n);
331
+ return {
332
+ verb,
333
+ status,
334
+ release,
335
+ label,
336
+ member,
337
+ component,
338
+ current,
339
+ resumes,
340
+ actor: resumes ? resumes.actor : req.actor,
341
+ reason,
342
+ replacement,
343
+ forgeYank,
344
+ signed: rule.requirement !== null,
345
+ targets: planned,
346
+ undeclared,
347
+ redactor,
348
+ };
349
+ }
350
+ /**
351
+ * Carry out a planned change: write the status record (signed when `sign`
352
+ * names a key) unless the plan resumes one, then act on each target, last
353
+ * declared first for a yank, so a formula stops naming assets before the
354
+ * forge release that holds them is withdrawn, and first declared first
355
+ * otherwise. Each target's actions are recorded and pushed as it finishes.
356
+ * Throws {@link StatusRunError}.
357
+ */
358
+ export async function runStatusChange(plan, req) {
359
+ const { appendReleaseStatus } = await import("./release-status.js");
360
+ const { appendLedgerLine, pushLifecycleReport } = await import("./git.js");
361
+ const { resolveRunId } = await import("./release-ledger.js");
362
+ const { sortedJsonReplacer } = await import("../utils.js");
363
+ const say = req.say ?? (() => undefined);
364
+ const now = req.now ?? (() => new Date());
365
+ const keep = req.record ?? true;
366
+ const runId = resolveRunId(undefined, req.env ?? process.env).runId;
367
+ let recordWarning = null;
368
+ const push = async () => {
369
+ const p = await pushLifecycleReport({ cwd: req.cwd });
370
+ if (p.pushWarning && recordWarning === null)
371
+ recordWarning = p.pushWarning;
372
+ };
373
+ let record = plan.resumes;
374
+ let written = false;
375
+ if (!record) {
376
+ const timestamp = now().toISOString();
377
+ let signature;
378
+ if (req.sign !== undefined) {
379
+ const { resolveSigningKey, sealReleaseStatus, SealError } = await import("../workspace/trust/seal.js");
380
+ try {
381
+ const key = resolveSigningKey(req.sign, req.cwd);
382
+ try {
383
+ signature = sealReleaseStatus(key.file, { releaseDigest: plan.release.releaseDigest, label: plan.label, actor: plan.actor, timestamp, status: plan.status }).signature;
384
+ }
385
+ finally {
386
+ key.cleanup();
387
+ }
388
+ }
389
+ catch (err) {
390
+ if (!(err instanceof SealError))
391
+ throw err;
392
+ throw new StatusRunError("release-signer-refused", `nothing was changed: ${err.message}`, undefined, []);
393
+ }
394
+ }
395
+ if (plan.signed) {
396
+ const { scopeSource } = await import("../workspace/write-scope.js");
397
+ const { releaseRuleFrom } = await import("../workspace/identity.js");
398
+ const { admitReleaseStatus } = await import("../workspace/identity-gate-rule.js");
399
+ const rule = releaseRuleFrom(scopeSource(req.cwd));
400
+ const why = admitReleaseStatus(rule.rule, { releaseDigest: plan.release.releaseDigest, label: plan.label, actor: plan.actor, timestamp, status: plan.status, signature: signature ?? null });
401
+ if (why !== null) {
402
+ throw new StatusRunError("release-signer-refused", `nothing was changed: ${why}`, `identity.gates.release in chant.workspace.json at base counts only a change signed by a key ${rule.rule.signers.signersPath} lists for the actor${rule.requirement?.class ? `, who holds the role of the class ${rule.requirement.class}` : ""}. Pass --actor <principal> naming that signer.`, []);
403
+ }
404
+ }
405
+ const input = {
406
+ component: plan.component,
407
+ env: RELEASE_STATUS_LEDGER,
408
+ digest: plan.release.releaseDigest,
409
+ ...(plan.label ? { releaseVersion: plan.label } : {}),
410
+ status: plan.status,
411
+ ...(plan.reason ? { reason: plan.reason } : {}),
412
+ ...(plan.replacement ? { replacement: plan.replacement } : {}),
413
+ actor: plan.actor,
414
+ timestamp,
415
+ ...(signature ? { signature } : {}),
416
+ };
417
+ if (keep) {
418
+ record = (await appendReleaseStatus(input, { cwd: req.cwd })).record;
419
+ await push();
420
+ }
421
+ else {
422
+ record = { version: 1, ...input };
423
+ }
424
+ written = true;
425
+ }
426
+ const order = plan.verb === "yank" ? [...plan.targets].reverse() : plan.targets;
427
+ const results = [];
428
+ const done = [];
429
+ for (const t of order) {
430
+ if (t.skip || !t.target || !t.ctx)
431
+ continue;
432
+ if (t.done) {
433
+ say(` ${t.name}: done by an earlier run; skipped`);
434
+ results.push({ name: t.name, actions: [], resumed: true });
435
+ done.push(t.name);
436
+ continue;
437
+ }
438
+ let actions;
439
+ if (!t.target.setStatus) {
440
+ actions = t.actions;
441
+ }
442
+ else {
443
+ say(` ${t.name}`);
444
+ try {
445
+ actions = await t.target.setStatus({ ...t.ctx, apply: true });
446
+ }
447
+ catch (err) {
448
+ const e = err instanceof PublishTargetError ? err : new PublishTargetError("release-status-failed", err instanceof Error ? err.message : String(err));
449
+ throw new StatusRunError(e.code, plan.redactor.redact(`${t.name}: ${e.message}`), e.fix, done);
450
+ }
451
+ }
452
+ results.push({ name: t.name, actions, resumed: false });
453
+ done.push(t.name);
454
+ if (!keep)
455
+ continue;
456
+ try {
457
+ const line = {
458
+ version: 1,
459
+ releaseDigest: plan.release.releaseDigest,
460
+ label: plan.label,
461
+ status: plan.status,
462
+ statusAt: record.timestamp,
463
+ target: t.key,
464
+ kind: t.kind,
465
+ name: t.name,
466
+ actions,
467
+ runId,
468
+ timestamp: now().toISOString(),
469
+ };
470
+ await appendLedgerLine(RELEASE_STATUS_LEDGER, STATUS_ACTIONS_FILE, plan.redactor.redact(JSON.stringify(line, sortedJsonReplacer)), `Release status actions: ${t.name}`, { cwd: req.cwd });
471
+ await push();
472
+ }
473
+ catch (err) {
474
+ recordWarning ?? (recordWarning = `the status actions record was not written: ${err instanceof Error ? err.message : String(err)}`);
475
+ }
476
+ }
477
+ return { record, written, results, recordWarning };
478
+ }
@@ -8,6 +8,11 @@
8
8
  * publish may append one (ruling C, 2026-10-27): there is no approval gate,
9
9
  * and the record carries the actor and the reason instead.
10
10
  *
11
+ * `chant release deprecate|yank|restore` (#5163) writes the record of a
12
+ * release `chant release cut` made to `_releases/release-status.jsonl`,
13
+ * beside the release's `cuts.jsonl`, with `env` `_releases` and the member as
14
+ * `component` (./release-status-change.ts).
15
+ *
11
16
  * Writes go through `appendLedgerLine` (./git.ts), so they land under the
12
17
  * member prefix of `cwd` and honour `--no-record` (`CHANT_NO_RECORD`), as the
13
18
  * writers of #4551 do. Nothing here pushes: the caller runs
@@ -49,6 +54,12 @@ export interface ReleaseStatusRecord {
49
54
  actor: string;
50
55
  /** ISO-8601 time it was set, given by the caller. */
51
56
  timestamp: string;
57
+ /**
58
+ * The actor's ssh signature over `releaseStatusSealPayload` in the
59
+ * `chant-release` namespace (#5163), which an `identity.gates.release`
60
+ * entry requires of `chant release deprecate|yank|restore`.
61
+ */
62
+ signature?: string;
52
63
  }
53
64
  /** The fields a caller gives; `version` is filled in. */
54
65
  export type ReleaseStatusInput = Omit<ReleaseStatusRecord, "version">;
@@ -12,7 +12,7 @@ export class ReleaseStatusError extends Error {
12
12
  }
13
13
  }
14
14
  const REQUIRED = ["component", "env", "digest", "actor", "timestamp"];
15
- const OPTIONAL = ["releaseVersion", "reason", "replacement"];
15
+ const OPTIONAL = ["releaseVersion", "reason", "replacement", "signature"];
16
16
  /** Why `value` is not a status record, one line per problem; empty when it is one. */
17
17
  export function releaseStatusProblems(value) {
18
18
  if (value === null || typeof value !== "object" || Array.isArray(value))
@@ -103,6 +103,25 @@ export interface ReleaseTarget {
103
103
  /** The directories the target records (#4155). Absent on a target cut before #4155. */
104
104
  trees?: ReleaseTree[];
105
105
  }
106
+ /**
107
+ * One `release.publish` target of an artifact release (#5149): a release cut
108
+ * with no environments, which records what its targets publish in place of
109
+ * compile targets. The files a target uploads are checked at publish against
110
+ * the artifacts the release records at their paths (`artifactDigests`), as
111
+ * for any release.
112
+ */
113
+ export interface ReleasePublish {
114
+ /** The target's key (`publishTargetKey`): its type and a digest of its declaration. */
115
+ target: string;
116
+ /** The declaration's `type`, such as `npm` or `forge`. */
117
+ kind: string;
118
+ /** Where it publishes, as the publish prints it. */
119
+ destination: string;
120
+ }
121
+ /** The first chant that writes and reads a release's `publishes` (#5149). */
122
+ export declare const RELEASE_PUBLISHES_FLOOR = "0.124.101";
123
+ /** The first chant that signs a cut's green-gate record and writes and reads `sealVersion` (#5177). */
124
+ export declare const RELEASE_GATE_SEAL_FLOOR = "0.124.101";
106
125
  /** The release file, `_releases/<releaseDigest>.json`. */
107
126
  export interface Release {
108
127
  version: 1;
@@ -112,7 +131,15 @@ export interface Release {
112
131
  /** The full sha of the green commit. */
113
132
  commit: string;
114
133
  artifactDigests: ReleaseArtifact[];
134
+ /** One per environment; empty for an artifact release (#5149). */
115
135
  targets: ReleaseTarget[];
136
+ /**
137
+ * An artifact release (#5149), cut with no environments: the targets
138
+ * `release.publish` declares, in order. In the digest when present, so such
139
+ * a release is read by chant {@link RELEASE_PUBLISHES_FLOOR} and newer.
140
+ * Absent on a release cut from environments.
141
+ */
142
+ publishes?: ReleasePublish[];
116
143
  }
117
144
  /** One line of `_releases/cuts.jsonl`. */
118
145
  export interface ReleaseCut {
@@ -136,10 +163,19 @@ export interface ReleaseCut {
136
163
  /**
137
164
  * The cut's signature (#4031): an armored ssh signature by the actor's key
138
165
  * in the `chant-release` namespace over the release digest, the label, the
139
- * actor and the time, one per line (`releaseSealPayload`). Null for an
166
+ * actor and the time, one per line (`releaseSealPayload`), and since
167
+ * #5177 the green-gate record (`sealVersion`). Null for an
140
168
  * unsigned cut, and on every cut written before 0.124.28.
141
169
  */
142
170
  signature: string | null;
171
+ /**
172
+ * The version of the payload `signature` signs (#5177): 2 when it covers
173
+ * the green-gate record (`green`, `override` and `lane`) as well
174
+ * (`releaseGateSealPayload`). Absent on an unsigned cut and on a cut signed
175
+ * before chant {@link RELEASE_GATE_SEAL_FLOOR}, whose gate record is not
176
+ * signed.
177
+ */
178
+ sealVersion?: 2;
143
179
  /**
144
180
  * A cut of a composed commit (#4168 4.3): its compose branch, the base it
145
181
  * was composed on, and the trunk commits picked onto the base, oldest
@@ -166,7 +202,42 @@ export interface ReleaseCut {
166
202
  * (#4693). Absent on a cut of a green commit.
167
203
  */
168
204
  override?: ReleaseCutOverride;
205
+ /**
206
+ * What the cut took as the commit being green (#5149): a chant green tag,
207
+ * the forge's checks by name, or nothing (`release.green: "none"`). Absent
208
+ * on a cut under an override, and on every cut written before #5149.
209
+ */
210
+ green?: ReleaseCutGreen;
211
+ /**
212
+ * The intent files the cut consumed (#5159): each `.chant/release/*.md`
213
+ * at the commit that named this member and that no earlier cut of it
214
+ * had consumed. A later release of the member skips them. Absent when
215
+ * there were none, and on every cut written before #5159.
216
+ */
217
+ intents?: ReleaseCutIntent[];
169
218
  }
219
+ /** One intent file a cut consumed (#5159). */
220
+ export interface ReleaseCutIntent {
221
+ /** The file's path from the repository root, such as `.chant/release/fast-sync.md`. */
222
+ path: string;
223
+ /** The full sha of the commit that added the file: a file deleted and written again is another intent. */
224
+ added: string;
225
+ /** The level it gave this member. */
226
+ bump: "major" | "minor" | "patch";
227
+ }
228
+ /** The green gate a cut passed (#5149), `release.green`. */
229
+ export type ReleaseCutGreen = {
230
+ source: "chant";
231
+ tag: string;
232
+ } | {
233
+ source: "forge-checks";
234
+ forge: string;
235
+ checks: string[];
236
+ } | {
237
+ source: "none";
238
+ };
239
+ /** Whether `v` reads as a {@link ReleaseCutGreen}. */
240
+ export declare function isCutGreen(v: unknown): v is ReleaseCutGreen;
170
241
  /**
171
242
  * The override a cut of a commit that was not green ran under (#4693): an
172
243
  * override on `_gates/policy-override.jsonl`, written by a person the
@@ -189,7 +260,7 @@ export interface ReleaseCutOverride {
189
260
  sealed: boolean;
190
261
  }
191
262
  /** The parts of a release a digest is computed from. */
192
- export type ReleaseSubject = Pick<Release, "member" | "commit" | "artifactDigests" | "targets">;
263
+ export type ReleaseSubject = Pick<Release, "member" | "commit" | "artifactDigests" | "targets" | "publishes">;
193
264
  /** The same release with every list in the order ws-104 sets: artifacts by component then path (a handed image's `ref` kept), targets by env, templates by component then path, params by name. */
194
265
  export declare function normalizeRelease<T extends ReleaseSubject>(release: T): T;
195
266
  /** The hash input of ws-104 question 3: a param's `source` is left out. */