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.
- package/LICENSE +21 -0
- package/README.md +113 -2
- package/dist/admin/config.d.ts +22 -0
- package/dist/admin/config.js +75 -0
- package/dist/admin/dist/assets/RichEditor-BlaCRrEX.css +1 -0
- package/dist/admin/dist/assets/RichEditor-IZKdt6MK.js +42 -0
- package/dist/admin/dist/assets/blank-line-CbGzlqBI.js +1 -0
- package/dist/admin/dist/assets/channel-CljeMIwA.js +1 -0
- package/dist/admin/dist/assets/db-CCMyPgQa.js +1 -0
- package/dist/admin/dist/assets/index-CWoJh4H8.js +257 -0
- package/dist/admin/dist/assets/index-DkRMnD_M.css +1 -0
- package/dist/admin/dist/assets/mdast-util-from-markdown-C79q1_d8.js +3 -0
- package/dist/admin/dist/assets/mdast-util-gfm-cM-_xFJE.js +19 -0
- package/dist/admin/dist/assets/micromark-extension-gfm-Wz6-oszS.js +1 -0
- package/dist/admin/dist/assets/micromark-util-classify-character-BgXaGAja.js +1 -0
- package/dist/admin/dist/assets/micromark-util-html-tag-name-B61T18yC.js +1 -0
- package/dist/admin/dist/assets/rolldown-runtime-XKyaHtl9.js +1 -0
- package/dist/admin/dist/index.html +16 -0
- package/dist/admin/dist/preview.js +1 -0
- package/dist/admin/dist/window.js +1 -0
- package/dist/astro/content.d.ts +21 -0
- package/dist/astro/content.js +235 -0
- package/dist/astro/devServer.js +89 -0
- package/dist/astro/index.d.ts +15 -0
- package/dist/astro/index.js +98 -0
- package/dist/astro/nodeBridge.js +36 -0
- package/dist/astro/shared.js +10 -0
- package/dist/astro/stub/index.html +71 -0
- package/dist/auth/client.d.ts +24 -0
- package/dist/auth/client.js +120 -0
- package/dist/auth/handler.d.ts +16 -0
- package/dist/auth/handler.js +281 -0
- package/dist/auth/protocol.d.ts +25 -0
- package/dist/auth/protocol.js +3 -0
- package/dist/core/assets.d.ts +73 -0
- package/dist/core/assets.js +405 -0
- package/dist/core/devApi.d.ts +28 -0
- package/dist/core/devApi.js +3 -0
- package/dist/core/entryFile.d.ts +13 -0
- package/dist/core/entryFile.js +81 -0
- package/dist/core/fields.js +147 -0
- package/dist/core/generate.d.ts +3 -0
- package/dist/core/generate.js +70 -0
- package/dist/core/gitStyle.d.ts +92 -0
- package/dist/core/gitStyle.js +206 -0
- package/dist/core/index.d.ts +16 -0
- package/dist/core/index.js +16 -0
- package/dist/core/issues.d.ts +10 -0
- package/dist/core/issues.js +10 -0
- package/dist/core/paths.d.ts +31 -0
- package/dist/core/paths.js +114 -0
- package/dist/core/project.js +56 -0
- package/dist/core/references.d.ts +68 -0
- package/dist/core/references.js +103 -0
- package/dist/core/rename.d.ts +60 -0
- package/dist/core/rename.js +133 -0
- package/dist/core/schema.d.ts +117 -0
- package/dist/core/schema.js +299 -0
- package/dist/core/sha.d.ts +2 -0
- package/dist/core/sha.js +13 -0
- package/dist/core/source.d.ts +48 -0
- package/dist/core/source.js +57 -0
- package/dist/core/validate.d.ts +22 -0
- package/dist/core/validate.js +148 -0
- package/dist/core/walk.d.ts +23 -0
- package/dist/core/walk.js +94 -0
- package/dist/core/writes.d.ts +37 -0
- package/dist/core/writes.js +166 -0
- package/dist/github/base64.js +16 -0
- package/dist/github/cache.d.ts +34 -0
- package/dist/github/cache.js +126 -0
- package/dist/github/client.d.ts +38 -0
- package/dist/github/client.js +228 -0
- package/dist/github/codeowners.d.ts +23 -0
- package/dist/github/codeowners.js +96 -0
- package/dist/github/commitReader.d.ts +25 -0
- package/dist/github/commitReader.js +38 -0
- package/dist/github/deploy.d.ts +15 -0
- package/dist/github/deploy.js +33 -0
- package/dist/github/index.d.ts +9 -0
- package/dist/github/index.js +8 -0
- package/dist/github/repo.d.ts +95 -0
- package/dist/github/repo.js +375 -0
- package/dist/github/source.d.ts +115 -0
- package/dist/github/source.js +558 -0
- package/dist/loader/index.d.ts +27 -0
- package/dist/loader/index.js +151 -0
- package/dist/loader/protocol.d.ts +95 -0
- package/dist/loader/protocol.js +120 -0
- package/dist/loader/window/geometry.js +9 -0
- package/dist/next/EditletLoader.d.ts +5 -0
- package/dist/next/EditletLoader.js +33 -0
- package/dist/next/assetUrl.d.ts +9 -0
- package/dist/next/assetUrl.js +13 -0
- package/dist/next/buildGuard.js +26 -0
- package/dist/next/config.d.ts +18 -0
- package/dist/next/config.js +255 -0
- package/dist/next/devServer.js +70 -0
- package/dist/next/editletField.d.ts +7 -0
- package/dist/next/editletField.js +7 -0
- package/dist/next/index.d.ts +8 -0
- package/dist/next/index.js +6 -0
- package/dist/next/preview.d.ts +18 -0
- package/dist/next/preview.js +100 -0
- package/dist/next/previewCookie.d.ts +5 -0
- package/dist/next/previewCookie.js +72 -0
- package/dist/next/previewEnv.js +25 -0
- package/dist/next/previewRef.d.ts +8 -0
- package/dist/next/previewRef.js +17 -0
- package/dist/next/publicDir.js +65 -0
- package/dist/next/reader.d.ts +49 -0
- package/dist/next/reader.js +161 -0
- package/dist/next/stub/index.html +56 -0
- package/dist/node/devHandler.d.ts +6 -0
- package/dist/node/devHandler.js +430 -0
- package/dist/node/fs.js +37 -0
- package/dist/node/index.d.ts +3 -0
- package/dist/node/index.js +3 -0
- package/dist/node/project.d.ts +12 -0
- package/dist/node/project.js +43 -0
- package/package.json +187 -4
- package/skills/README.md +84 -0
- package/skills/editlet/SKILL.md +119 -0
- package/skills/editlet/references/content-format.md +191 -0
- package/skills/editlet/references/preview.md +75 -0
- package/skills/editlet/references/publishing.md +137 -0
- package/skills/editlet/references/schema-changes.md +127 -0
- package/skills/editlet/scripts/guard.mjs +1061 -0
- package/skills/editlet/scripts/link.mjs +193 -0
- package/skills/editlet/scripts/refs.mjs +1480 -0
- package/skills/editlet/scripts/schema.mjs +1340 -0
- package/skills/editlet/scripts/style.mjs +657 -0
- package/skills/editlet/scripts/types.mjs +525 -0
- package/skills/editlet/scripts/validate.mjs +724 -0
- package/skills/editlet-migrate/SKILL.md +92 -0
- package/skills/editlet-migrate/references/mapping.md +73 -0
- package/skills/editlet-migrate/references/sources.md +70 -0
- package/skills/editlet-setup/SKILL.md +108 -0
- package/skills/editlet-setup/references/astro.md +83 -0
- package/skills/editlet-setup/references/doctor.md +89 -0
- package/skills/editlet-setup/references/next.md +140 -0
- package/skills/editlet-setup/references/preview.md +54 -0
- package/skills/editlet-setup/references/production.md +153 -0
- package/skills/editlet-setup/references/roles.md +238 -0
- package/skills/editlet-setup/references/skills.md +99 -0
- 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.
|