editlet 0.0.0-stage → 0.1.0-alpha.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 (146) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +113 -2
  3. package/dist/admin/config.d.ts +22 -0
  4. package/dist/admin/config.js +75 -0
  5. package/dist/admin/dist/assets/RichEditor-BlaCRrEX.css +1 -0
  6. package/dist/admin/dist/assets/RichEditor-IZKdt6MK.js +42 -0
  7. package/dist/admin/dist/assets/blank-line-CbGzlqBI.js +1 -0
  8. package/dist/admin/dist/assets/channel-CljeMIwA.js +1 -0
  9. package/dist/admin/dist/assets/db-CCMyPgQa.js +1 -0
  10. package/dist/admin/dist/assets/index-CWoJh4H8.js +257 -0
  11. package/dist/admin/dist/assets/index-DkRMnD_M.css +1 -0
  12. package/dist/admin/dist/assets/mdast-util-from-markdown-C79q1_d8.js +3 -0
  13. package/dist/admin/dist/assets/mdast-util-gfm-cM-_xFJE.js +19 -0
  14. package/dist/admin/dist/assets/micromark-extension-gfm-Wz6-oszS.js +1 -0
  15. package/dist/admin/dist/assets/micromark-util-classify-character-BgXaGAja.js +1 -0
  16. package/dist/admin/dist/assets/micromark-util-html-tag-name-B61T18yC.js +1 -0
  17. package/dist/admin/dist/assets/rolldown-runtime-XKyaHtl9.js +1 -0
  18. package/dist/admin/dist/index.html +16 -0
  19. package/dist/admin/dist/preview.js +1 -0
  20. package/dist/admin/dist/window.js +1 -0
  21. package/dist/astro/content.d.ts +21 -0
  22. package/dist/astro/content.js +235 -0
  23. package/dist/astro/devServer.js +89 -0
  24. package/dist/astro/index.d.ts +15 -0
  25. package/dist/astro/index.js +98 -0
  26. package/dist/astro/nodeBridge.js +36 -0
  27. package/dist/astro/shared.js +10 -0
  28. package/dist/astro/stub/index.html +71 -0
  29. package/dist/auth/client.d.ts +24 -0
  30. package/dist/auth/client.js +120 -0
  31. package/dist/auth/handler.d.ts +16 -0
  32. package/dist/auth/handler.js +281 -0
  33. package/dist/auth/protocol.d.ts +25 -0
  34. package/dist/auth/protocol.js +3 -0
  35. package/dist/core/assets.d.ts +73 -0
  36. package/dist/core/assets.js +405 -0
  37. package/dist/core/devApi.d.ts +28 -0
  38. package/dist/core/devApi.js +3 -0
  39. package/dist/core/entryFile.d.ts +13 -0
  40. package/dist/core/entryFile.js +81 -0
  41. package/dist/core/fields.js +147 -0
  42. package/dist/core/generate.d.ts +3 -0
  43. package/dist/core/generate.js +70 -0
  44. package/dist/core/gitStyle.d.ts +92 -0
  45. package/dist/core/gitStyle.js +206 -0
  46. package/dist/core/index.d.ts +16 -0
  47. package/dist/core/index.js +16 -0
  48. package/dist/core/issues.d.ts +10 -0
  49. package/dist/core/issues.js +10 -0
  50. package/dist/core/paths.d.ts +31 -0
  51. package/dist/core/paths.js +114 -0
  52. package/dist/core/project.js +56 -0
  53. package/dist/core/references.d.ts +68 -0
  54. package/dist/core/references.js +103 -0
  55. package/dist/core/rename.d.ts +60 -0
  56. package/dist/core/rename.js +133 -0
  57. package/dist/core/schema.d.ts +117 -0
  58. package/dist/core/schema.js +299 -0
  59. package/dist/core/sha.d.ts +2 -0
  60. package/dist/core/sha.js +13 -0
  61. package/dist/core/source.d.ts +48 -0
  62. package/dist/core/source.js +57 -0
  63. package/dist/core/validate.d.ts +22 -0
  64. package/dist/core/validate.js +148 -0
  65. package/dist/core/walk.d.ts +23 -0
  66. package/dist/core/walk.js +94 -0
  67. package/dist/core/writes.d.ts +37 -0
  68. package/dist/core/writes.js +166 -0
  69. package/dist/github/base64.js +16 -0
  70. package/dist/github/cache.d.ts +34 -0
  71. package/dist/github/cache.js +126 -0
  72. package/dist/github/client.d.ts +38 -0
  73. package/dist/github/client.js +228 -0
  74. package/dist/github/codeowners.d.ts +23 -0
  75. package/dist/github/codeowners.js +96 -0
  76. package/dist/github/commitReader.d.ts +25 -0
  77. package/dist/github/commitReader.js +38 -0
  78. package/dist/github/deploy.d.ts +15 -0
  79. package/dist/github/deploy.js +33 -0
  80. package/dist/github/index.d.ts +9 -0
  81. package/dist/github/index.js +8 -0
  82. package/dist/github/repo.d.ts +95 -0
  83. package/dist/github/repo.js +375 -0
  84. package/dist/github/source.d.ts +115 -0
  85. package/dist/github/source.js +558 -0
  86. package/dist/loader/index.d.ts +27 -0
  87. package/dist/loader/index.js +151 -0
  88. package/dist/loader/protocol.d.ts +95 -0
  89. package/dist/loader/protocol.js +120 -0
  90. package/dist/loader/window/geometry.js +9 -0
  91. package/dist/next/EditletLoader.d.ts +5 -0
  92. package/dist/next/EditletLoader.js +33 -0
  93. package/dist/next/assetUrl.d.ts +9 -0
  94. package/dist/next/assetUrl.js +13 -0
  95. package/dist/next/buildGuard.js +26 -0
  96. package/dist/next/config.d.ts +18 -0
  97. package/dist/next/config.js +255 -0
  98. package/dist/next/devServer.js +70 -0
  99. package/dist/next/editletField.d.ts +7 -0
  100. package/dist/next/editletField.js +7 -0
  101. package/dist/next/index.d.ts +8 -0
  102. package/dist/next/index.js +6 -0
  103. package/dist/next/preview.d.ts +18 -0
  104. package/dist/next/preview.js +100 -0
  105. package/dist/next/previewCookie.d.ts +5 -0
  106. package/dist/next/previewCookie.js +72 -0
  107. package/dist/next/previewEnv.js +25 -0
  108. package/dist/next/previewRef.d.ts +8 -0
  109. package/dist/next/previewRef.js +17 -0
  110. package/dist/next/publicDir.js +65 -0
  111. package/dist/next/reader.d.ts +49 -0
  112. package/dist/next/reader.js +161 -0
  113. package/dist/next/stub/index.html +56 -0
  114. package/dist/node/devHandler.d.ts +6 -0
  115. package/dist/node/devHandler.js +430 -0
  116. package/dist/node/fs.js +37 -0
  117. package/dist/node/index.d.ts +3 -0
  118. package/dist/node/index.js +3 -0
  119. package/dist/node/project.d.ts +12 -0
  120. package/dist/node/project.js +43 -0
  121. package/package.json +187 -4
  122. package/skills/README.md +84 -0
  123. package/skills/editlet/SKILL.md +119 -0
  124. package/skills/editlet/references/content-format.md +191 -0
  125. package/skills/editlet/references/preview.md +75 -0
  126. package/skills/editlet/references/publishing.md +137 -0
  127. package/skills/editlet/references/schema-changes.md +127 -0
  128. package/skills/editlet/scripts/guard.mjs +1061 -0
  129. package/skills/editlet/scripts/link.mjs +193 -0
  130. package/skills/editlet/scripts/refs.mjs +1480 -0
  131. package/skills/editlet/scripts/schema.mjs +1340 -0
  132. package/skills/editlet/scripts/style.mjs +657 -0
  133. package/skills/editlet/scripts/types.mjs +525 -0
  134. package/skills/editlet/scripts/validate.mjs +724 -0
  135. package/skills/editlet-migrate/SKILL.md +92 -0
  136. package/skills/editlet-migrate/references/mapping.md +73 -0
  137. package/skills/editlet-migrate/references/sources.md +70 -0
  138. package/skills/editlet-setup/SKILL.md +108 -0
  139. package/skills/editlet-setup/references/astro.md +83 -0
  140. package/skills/editlet-setup/references/doctor.md +89 -0
  141. package/skills/editlet-setup/references/next.md +140 -0
  142. package/skills/editlet-setup/references/preview.md +54 -0
  143. package/skills/editlet-setup/references/production.md +153 -0
  144. package/skills/editlet-setup/references/roles.md +238 -0
  145. package/skills/editlet-setup/references/skills.md +99 -0
  146. package/skills/editlet-setup/scripts/doctor.mjs +1378 -0
@@ -0,0 +1,75 @@
1
+ # Preview in the `?editlet` editor
2
+
3
+ The editor opens over any page of the site when the URL has `?editlet`. In dev it reads and writes the local files
4
+ through the dev server. A site may use another parameter name: `EDITLET_PARAM` in `.env*` or the host's env, or
5
+ `admin.param` in `next.config.*` / `astro.config.*`. Then use that name everywhere below (`?cms=post/spring-sale`). Use it to **show** the human your changes. Make your edits in the files, not by driving the
6
+ editor's form, unless the human asks you to.
7
+
8
+ ## Is a dev server running?
9
+
10
+ ```bash
11
+ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/__editlet/files
12
+ ```
13
+
14
+ - `200`: a dev server with the Editlet adapter is running on that port. Try the project's usual port first (Next
15
+ `3000`, Astro `4321`, or what `package.json` / the dev script says).
16
+ - `403` or `500`: a server runs there, but the request was refused (`403`: host not allowed) or the schema is
17
+ broken (`500`, the body lists the issues). Do not start a second server; fix the schema or use `localhost`.
18
+ - `404`, another code, or a refused connection: no Editlet dev server. To start one, use the dev script (`npm run dev`)
19
+ in the background, or the host's preview tool. Wait until the check returns `200`. If the human did not ask for a
20
+ preview, just tell them how to start one.
21
+
22
+ ## Open the right screen
23
+
24
+ URL: `http://localhost:<port><page>?editlet=<route>`. Use the page where the content appears (`/blog/spring-sale`), or `/`
25
+ if you do not know it. Keep any existing query parameters.
26
+
27
+ | Route | Screen |
28
+ |---|---|
29
+ | `?editlet` | Editor home: collections and entries |
30
+ | `?editlet=<collection>/<slug>` | One entry, e.g. `?editlet=post/spring-sale`. A singleton: `?editlet=homePage/index` |
31
+ | `?editlet=schema` | The content model, the screen to show after a schema change |
32
+ | `?editlet=media` | Media: every image, where it is used, upload, alt text, delete unused |
33
+ | `?editlet=branch:<name>` | Preview of branch `<prefix><name>` (`git.branchPrefix`, default `editlet/`) with its diff ([publishing](publishing.md)) |
34
+
35
+ Write the route readably: `?editlet=post/spring-sale`, not `%2F`.
36
+
37
+ **Browser tools.** In the Claude desktop app, use the built-in browser (`preview_start` with the URL, or
38
+ `navigate`). Use Claude in Chrome (`mcp__claude-in-chrome__*`) only when the human asks for it or the built-in
39
+ browser is not available. Take one screenshot or read the page to confirm the screen opened, then hand over to the
40
+ human. Without browser tools, print the URL.
41
+
42
+ ## Driving the editor yourself
43
+
44
+ Only when the human asks you to use the editor (or to check what it shows). Open the admin as its own page,
45
+ `http://localhost:<port>/editlet/?editlet=<route>`: the same editor, with every control in the page's accessibility tree
46
+ (the `?editlet` window lives in an iframe that some browser tools do not read). Act by role and name, never by
47
+ coordinates:
48
+
49
+ - A field is named by its schema `label` (`textbox "Title"`, `combobox "Category"`); required fields have
50
+ `aria-required`.
51
+ - `button "Save"` opens `dialog "Review changes"`: one region per changed field with the old (`−`) and new (`+`)
52
+ value. Confirm with the `Save` inside the dialog. Then check the file with `git diff`.
53
+ - The status bar (`contentinfo`) says `Unsaved changes (n)`, `n uncommitted` or `Draft`.
54
+ - Escape closes a menu or dialog first, then collapses the window; errors are text in the page.
55
+
56
+ The full map of roles and names is `docs/admin/agents.md` in the Editlet repository.
57
+
58
+ ## After you edit
59
+
60
+ - The dev server picks up file changes. If an entry screen is already open, navigate to the same URL again so the
61
+ editor reloads the file.
62
+ - If the editor shows an error, run `validate` and fix the file. The editor refuses invalid content just like the
63
+ script does.
64
+
65
+ ## When the human edits in the editor
66
+
67
+ - A save in the editor writes the file on disk, and in dev it is not committed. Before your next edit, run
68
+ `git status` / `git diff` and re-read the file. Build on their version, and never write back a stale copy.
69
+ - If you and the human changed the same field differently, ask which one wins.
70
+
71
+ ## Dev versus publishing
72
+
73
+ Editing locally changes nothing on the live site. To put the changes live, follow [publishing](publishing.md): a
74
+ `editlet/<name>` branch (the schema's prefix), a PR, approval, then the merge. Commit in dev only when the human asks. Then still use a branch,
75
+ never the base branch.
@@ -0,0 +1,137 @@
1
+ # Publishing (prod)
2
+
3
+ A change goes live when it is merged into the base branch. Hosting then rebuilds the site, which takes 1–3 minutes.
4
+ You work only with `git` and `gh` in the local clone, and the human decides when the merge happens.
5
+
6
+ ```mermaid
7
+ flowchart LR
8
+ A[edit + validate] --> B[prefix/name branch] --> C[commit + push] --> D[PR] --> E["?editlet=branch:name + diff"]
9
+ E --> F{human approves?}
10
+ F -- "says publish" --> G[merge] --> H[redeploy]
11
+ F -- changes --> A
12
+ ```
13
+
14
+ ## Before you start
15
+
16
+ - `gh auth status` must show a login. If it does not, ask the human to run `gh auth login` themselves. Never ask for a
17
+ token.
18
+ - Base branch: `git.baseBranch` in `cms/schema.json` (below: `<base>`). Run `git fetch origin`.
19
+ - Run `validate`. Fix every issue first.
20
+ - **Take names from `style.mjs`, never write them by hand.** It applies `git` of the schema (branch prefix, commit
21
+ template, pull request title, labels, draft) exactly as the editor does, so branches, commits and pull requests from
22
+ you and from `?editlet` look the same. The prefix is `git.branchPrefix`, default `editlet/` (below: `<prefix>`).
23
+
24
+ ```bash
25
+ S=.claude/skills/editlet/scripts/style.mjs
26
+ node $S branch spring sale post # → editlet/spring-sale-post
27
+ node $S commit --staged # → the message for what is staged, with "Editlet-Source: agent"
28
+ node $S pr <branch> --login <you> [--site <url>] [--param <name>] # → JSON { title, body, labels, draft }
29
+ ```
30
+
31
+ ## 1. Branch
32
+
33
+ One `<prefix><name>` branch holds one change set: everything the human will review and publish together. By default,
34
+ all edits made since the last publish in this conversation are one change set; start a new one when the human says so
35
+ or switches to an unrelated topic. `<name>` is a short slug of the intent: `node $S branch spring sale post` gives
36
+ `editlet/spring-sale-post`.
37
+
38
+ Edit in the working tree while the human iterates. Create the branch, commit, push and open the PR when they ask to
39
+ publish or to see a preview on the live site, not after every edit.
40
+
41
+ - **Same change set, continuing:** reuse its branch. Check with
42
+ `gh pr list --head <branch> --state open --json number,url`, then `git switch <branch> && git pull --ff-only`.
43
+ - **New change set:** `git switch -c "$(node $S branch <name>)" --no-track origin/<base>`. Uncommitted edits come
44
+ along. If
45
+ `git switch` refuses because of a conflict, stop and ask.
46
+ - The human's unrelated uncommitted work stays uncommitted. You stage only your paths.
47
+
48
+ ## 2. Commit and push
49
+
50
+ ```bash
51
+ node .claude/skills/editlet/scripts/validate.mjs
52
+ git add cms/content/post/spring-sale.md cms/content/post/spring-sale/ # only your paths
53
+ git diff --cached --stat # nothing else staged?
54
+ node $S commit --staged > /tmp/editlet-msg # the style's message + trailer
55
+ git commit -F /tmp/editlet-msg -- cms/content/post/spring-sale.md cms/content/post/spring-sale/
56
+ git push -u origin <branch>
57
+ ```
58
+
59
+ The guard hook blocks a commit while `validate` fails, blocks any push to `<base>`, and asks first when content is
60
+ committed on a branch outside `<prefix>`. If the guard denies a command, fix the cause. Never work around it.
61
+
62
+ The `Editlet-Source: agent` trailer and the prefix mark the change as Editlet's. They are a convention for people and
63
+ search, not a permission: GitHub's rulesets decide what may be pushed and merged.
64
+
65
+ ## 3. Pull request
66
+
67
+ ```bash
68
+ node $S pr <branch> --login "$(gh api user --jq .login)" --site <site> > /tmp/editlet-pr.json
69
+ gh pr create --base <base> --head <branch> \
70
+ --title "$(jq -r .title /tmp/editlet-pr.json)" --body "$(jq -r .body /tmp/editlet-pr.json)" \
71
+ $(jq -r '.labels[] | "--label " + .' /tmp/editlet-pr.json) $(jq -r 'if .draft then "--draft" else "" end' /tmp/editlet-pr.json)
72
+ ```
73
+
74
+ The body lists the changed entries and the review link between `<!-- editlet:start -->` and `<!-- editlet:end -->`.
75
+ Anything outside the markers is the human's. `gh pr create --label` fails when a label does not exist in the repo:
76
+ then create the pull request without it and tell the human. Run `gh label create` only after an explicit yes.
77
+
78
+ If the branch already has a PR, do not open a second one. After the next push, refresh its body:
79
+
80
+ ```bash
81
+ gh pr view <n> --json body -q .body | node $S pr-body <branch> --login <you> --site <site> | gh pr edit <n> --body-file -
82
+ ```
83
+
84
+ ## 4. Show the change
85
+
86
+ - In chat: a short per-entry summary, with `git diff origin/<base>...HEAD --stat` and the key field changes.
87
+ - In the browser: open `<site>/?editlet=branch:<name>`, where `<name>` has no `<prefix>`. A site with its own parameter
88
+ name (`EDITLET_PARAM`, `admin.param`: see [preview](preview.md)) uses `?<param>=branch:<name>`; pass `--param <name>`
89
+ to `pr` and `pr-body` so the review link in the body uses it too. The editor finds the branch
90
+ preview deployment and shows the diff. While the preview build runs, it shows "build in progress" and the diff.
91
+ - Site URL: use the one the human gave you, or the latest production deployment:
92
+ `gh api "repos/{owner}/{repo}/deployments?environment=Production&per_page=1" --jq '.[0].statuses_url'`, then
93
+ `gh api <statuses_url> --jq '.[0].environment_url'`. If neither works, ask once.
94
+
95
+ Then stop and say: what changed, the PR link, the preview link, and that you will merge when they say so.
96
+
97
+ ## 5. Approval and merge
98
+
99
+ Merge only when the human writes an explicit go-ahead in this conversation, after seeing this PR: "publish", "merge
100
+ it", "ship it", "go live". "Looks good" alone is not enough. Ask once: "Merge PR #12 into main now?"
101
+
102
+ To merge:
103
+
104
+ ```bash
105
+ gh pr view <n> --json mergeable,mergeStateStatus,url
106
+ gh repo view --json squashMergeAllowed,mergeCommitAllowed,rebaseMergeAllowed
107
+ gh pr merge <n> --squash --delete-branch # or --merge / --rebase, whichever the repo allows
108
+ ```
109
+
110
+ The guard hook turns `gh pr merge` into a permission prompt, so the human confirms once more.
111
+
112
+ **Blocked merges.** If the base branch needs reviews or checks, or the merge fails, give the PR link and what blocks
113
+ it, then stop. Use `gh pr merge <n> --auto` only if the human asks; it waits for the checks and keeps protection.
114
+ NEVER pass `--admin`, push to `<base>`, or change branch protection.
115
+
116
+ ## 6. After the merge
117
+
118
+ - Tell the human that hosting is rebuilding (1–3 minutes). For status:
119
+ `gh api "repos/{owner}/{repo}/deployments?ref=<base>&per_page=1"`.
120
+ - Return to the base: `git switch <base> && git pull --ff-only`.
121
+
122
+ ## Undo a published change
123
+
124
+ Use a new change set, never a direct push:
125
+
126
+ ```bash
127
+ git switch -c "$(node $S branch revert spring sale)" --no-track origin/<base>
128
+ git revert --no-edit <squash-commit> # a merge commit needs: git revert --no-edit -m 1 <merge-commit>
129
+ node .claude/skills/editlet/scripts/validate.mjs
130
+ ```
131
+
132
+ Then push, open a PR, show it, and merge after approval, the same as steps 2–5.
133
+
134
+ ## Closing without publishing
135
+
136
+ If the human drops the change: `gh pr close <n> --delete-branch`, after they confirm. The content on `<base>` stays
137
+ as it was.
@@ -0,0 +1,127 @@
1
+ # Schema changes
2
+
3
+ `cms/schema.json` is the content model. The dev server, the `?editlet` editor and the site build all read it, so a broken
4
+ or incompatible schema breaks them at once. Always run a dry run first.
5
+
6
+ ## The schema in one minute
7
+
8
+ ```json
9
+ {
10
+ "contentDir": "cms/content",
11
+ "git": { "baseBranch": "main" },
12
+ "collections": {
13
+ "post": {
14
+ "label": "Post",
15
+ "titleField": "title",
16
+ "slugFrom": "title",
17
+ "fields": {
18
+ "title": { "type": "string", "label": "Title", "required": true },
19
+ "body": { "type": "markdown", "label": "Body" }
20
+ }
21
+ },
22
+ "homePage": { "label": "Home page", "singleton": true, "fields": { "title": { "type": "string", "label": "Title" } } }
23
+ }
24
+ }
25
+ ```
26
+
27
+ - Collection and field keys match `^[a-zA-Z][a-zA-Z0-9]*$`. Use camelCase, never hyphens. Two collection keys must
28
+ differ by more than letter case.
29
+ - Every object is strict, so an unknown key is an error. `draft` cannot be a field key.
30
+ - Each field needs `type` and `label`. Optional keys are `required` and `hint`, plus the type's own keys:
31
+ - `string`: `list`, `default`
32
+ - `text`: `rows`, `default`
33
+ - `boolean`: `default`, `labels: { true, false }`
34
+ - `select`: `options: [{ label, value }]` (at least one), `multiple`, `default`
35
+ - `number`: `min`, `max`, `step`, `integer`, `default`
36
+ - `datetime`: `dateOnly`, `defaultNow`
37
+ - `color`: `default`
38
+ - `reference`: `collections` (at least one, must exist), `multiple`, `min`, `max` (both need `multiple: true`)
39
+ - `object`: `fields` (nested fields, at least one), `list`, `min`, `max` (both need `list: true`)
40
+ - `blocks`: `blocks: { <kind>: { label, fields } }` (at least one kind), `min`, `max`. `block` cannot be a field
41
+ key inside a block
42
+ - `markdown`, `json`, `url`, `image`: no extra keys
43
+ - Nested fields (in `object` and `blocks`) take every type, `object` and `blocks` too, with the same rules. A nested
44
+ `markdown` is a Markdown string; `draft` is an ordinary key there. `object` and `blocks` take no `default`.
45
+ - At most one `markdown` field per collection (top level). `titleField` and `slugFrom` must name a field of the collection.
46
+ - To add a block kind or a nested field, edit the candidate schema and run `check`: existing entries stay valid as
47
+ long as the new nested field is optional. `rename-field` and `remove-field` work on top-level fields only; for a
48
+ nested field, change the schema and every entry with a candidate + `check`.
49
+ - A `default` fills **new** entries only (the editor uses it). It does not fill existing files.
50
+
51
+ ## Choose the procedure
52
+
53
+ | Change | Procedure |
54
+ |---|---|
55
+ | Rename a field | `schema.mjs rename-field` ([below](#rename-a-field)) |
56
+ | Remove a field | `schema.mjs remove-field` ([below](#remove-a-field)) |
57
+ | Add a field, add a collection, change options, labels, `required`, … | Candidate file + `schema.mjs check` ([below](#any-other-change-candidate--check)) |
58
+ | Rename a collection | Manual ([below](#rename-a-collection)) |
59
+
60
+ After any applied change, run `node .claude/skills/editlet/scripts/validate.mjs` and `node .claude/skills/editlet/scripts/types.mjs`. Then tell the human what changed. If a
61
+ dev server is running, offer to open `?editlet=schema`.
62
+
63
+ ## Any other change: candidate + check
64
+
65
+ 1. Copy the schema into a candidate file and edit the copy:
66
+ `mkdir -p .editlet && cp cms/schema.json .editlet/schema.next.json`.
67
+ 2. Run `node .claude/skills/editlet/scripts/schema.mjs check .editlet/schema.next.json` (a relative path is resolved against `--root` when given, else the current folder). It applies the core write rules to the existing content
68
+ and reports only the issues the change would **introduce**, as `file: field — message`. The script prints
69
+ `✓ schema change is safe (N entries checked)` when there are none.
70
+ 3. Show the human the schema diff (`diff -u cms/schema.json .editlet/schema.next.json`) and the impact.
71
+ 4. Resolve the impact before you apply:
72
+ - **New required field:** every existing entry needs a value. Ask for the values, or agree to make the field
73
+ optional (`default` does not fill existing entries). Then apply in this order: write the values into the
74
+ entries first, then move the candidate into place. Running `check` again with the values present must pass.
75
+ - **Narrowed options, `min`/`max`, `integer`:** fix the listed entries, or keep the old rule.
76
+ 5. Apply: `mv .editlet/schema.next.json cms/schema.json`, then validate. If the change is dropped, delete the
77
+ candidate.
78
+
79
+ **New collection:** add it to the candidate with `label`, `fields`, and usually `titleField` (the field the editor
80
+ shows as the entry title) and `slugFrom` (the field slugs are made from). Create the folder `<contentDir>/<key>/` when
81
+ you add the first entry. Git does not track empty folders. Add a reference field elsewhere with `collections: ["<key>"]` if entries
82
+ should link to it.
83
+
84
+ ## Rename a field
85
+
86
+ ```bash
87
+ node .claude/skills/editlet/scripts/schema.mjs rename-field post featuredImage cover # dry run: prints the plan
88
+ node .claude/skills/editlet/scripts/schema.mjs rename-field post featuredImage cover --apply # writes it
89
+ ```
90
+
91
+ - The dry run lists `cms/schema.json` and every entry that has the field. Nothing is written.
92
+ - Apply renames the key in place in the schema, keeping the field order, and updates `titleField` / `slugFrom`.
93
+ It edits only the key line in each entry. If that edit would not read back the same, it rewrites that entry's
94
+ frontmatter in the standard format. Above 12 occurrences of the key in the schema, or when no text edit verifies, the schema file is rewritten in 2-space JSON. The plan marks such entries `(rewritten in standard format)`; `titleField` / `slugFrom` changes are printed as `note:` lines. The whole batch is validated before anything is written.
95
+ - Renaming a `markdown` field changes only the schema, because its text is the body.
96
+ - The field's `label` stays. If it names the old key ("Featured image"), offer to update it with a candidate + `check`.
97
+ - Afterwards, search the site code for the old name: `git grep -n featuredImage -- ':!cms/'`. Code that reads
98
+ `data.featuredImage` must change too. Say so if it is out of your task.
99
+
100
+ ## Remove a field
101
+
102
+ ```bash
103
+ node .claude/skills/editlet/scripts/schema.mjs remove-field post subtitle # dry run
104
+ node .claude/skills/editlet/scripts/schema.mjs remove-field post subtitle --apply
105
+ ```
106
+
107
+ - The dry run prints a `loses data:` line for each entry that has a value. **Show these lines and get an explicit
108
+ yes before `--apply`.**
109
+ - Removing a `markdown` field empties the body of every entry, and the dry run lists them as `loses body:`.
110
+ - `titleField` / `slugFrom` that named the field are dropped from the collection.
111
+ - Image files that the removed field pointed to stay on disk. Delete them only if the human agrees and no other entry
112
+ uses them.
113
+
114
+ ## Rename a collection
115
+
116
+ There is no script. The rename touches folders and every reference, so do it in one change set:
117
+
118
+ 1. Edit a candidate: rename the collection key and update every reference field's `collections` that named it.
119
+ 2. `git mv <contentDir>/<old> <contentDir>/<new>`.
120
+ 3. Replace `<old>/` with `<new>/` in reference values across `contentDir` (only in reference fields).
121
+ 4. Move the candidate into place and run `validate`. Image `src` values are relative, so they keep working.
122
+ 5. Site code that names the collection must change too.
123
+
124
+ ## If the schema on disk is broken
125
+
126
+ `validate` prints the schema issues with paths like `collections.post.fields.title.type`. Fix `cms/schema.json`
127
+ first. Until the schema parses, the editor can save only the schema file.