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,140 @@
|
|
|
1
|
+
# Next.js setup
|
|
2
|
+
|
|
3
|
+
For Next.js App Router sites: `next >=16`, `react >=19`. Paths below assume a `src/` folder; drop `src/` when the
|
|
4
|
+
project has `app/` at the root.
|
|
5
|
+
|
|
6
|
+
## 1. Config
|
|
7
|
+
|
|
8
|
+
Wrap the existing export. Keep every existing option, and keep the file's language (`.ts`, `.mjs`).
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
// next.config.ts
|
|
12
|
+
import type { NextConfig } from 'next';
|
|
13
|
+
import { withEditlet } from 'editlet/next/config';
|
|
14
|
+
|
|
15
|
+
const nextConfig: NextConfig = {
|
|
16
|
+
// the existing options, unchanged
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
export default withEditlet(nextConfig);
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
- An existing phase function (`export default (phase) => ({ … })`) also works: `withEditlet(fn)`.
|
|
23
|
+
- Other wrappers (`withMDX(…)`, `withSentryConfig(…)`) stay; put `withEditlet` innermost:
|
|
24
|
+
`export default withSentryConfig(withEditlet(nextConfig), …)`.
|
|
25
|
+
- `withEditlet` writes `.editlet/content.d.ts` and `public/editlet/` when `next dev` or `next build` starts, and in
|
|
26
|
+
`next dev` it serves the dev file API at `/__editlet`. Options for the live site go in a second argument (see
|
|
27
|
+
[production](production.md)).
|
|
28
|
+
|
|
29
|
+
## 2. `.gitignore`
|
|
30
|
+
|
|
31
|
+
Append, if missing:
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
/.editlet/
|
|
35
|
+
/public/editlet/
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## 3. The loader in the root layout
|
|
39
|
+
|
|
40
|
+
Add the import and render `<EditletLoader />` as the last child of `<body>`, after `{children}`. Change nothing else.
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
// src/app/layout.tsx
|
|
44
|
+
import { EditletLoader } from 'editlet/next';
|
|
45
|
+
|
|
46
|
+
// inside <body>:
|
|
47
|
+
{children}
|
|
48
|
+
<EditletLoader />
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`<EditletLoader />` renders nothing until the URL has `?editlet`. With several root layouts (route groups), add it to
|
|
52
|
+
each.
|
|
53
|
+
|
|
54
|
+
## 4. Schema and content
|
|
55
|
+
|
|
56
|
+
If `cms/schema.json` does not exist and the project has no content to migrate, create a minimal schema and one entry
|
|
57
|
+
so `?editlet` has something to show. Say that it is a sample.
|
|
58
|
+
|
|
59
|
+
```json
|
|
60
|
+
{
|
|
61
|
+
"contentDir": "cms/content",
|
|
62
|
+
"git": { "baseBranch": "main" },
|
|
63
|
+
"collections": {
|
|
64
|
+
"post": {
|
|
65
|
+
"label": "Post",
|
|
66
|
+
"titleField": "title",
|
|
67
|
+
"slugFrom": "title",
|
|
68
|
+
"fields": {
|
|
69
|
+
"title": { "type": "string", "label": "Title", "required": true },
|
|
70
|
+
"publishedAt": { "type": "datetime", "label": "Published at" },
|
|
71
|
+
"body": { "type": "markdown", "label": "Body" }
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`git.baseBranch` is the branch the site deploys from: check `git symbolic-ref refs/remotes/origin/HEAD` or ask.
|
|
79
|
+
|
|
80
|
+
`cms/content/post/hello-world.md`:
|
|
81
|
+
|
|
82
|
+
```md
|
|
83
|
+
---
|
|
84
|
+
title: Hello world
|
|
85
|
+
publishedAt: 2026-01-15T09:00:00Z
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
The first post. Edit it at `/?editlet`.
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
If the project already has Markdown, MDX or another CMS, do not create sample content: offer `editlet-migrate`.
|
|
92
|
+
|
|
93
|
+
## 5. The reader
|
|
94
|
+
|
|
95
|
+
Only if the human wants pages to read Editlet content (or a migration needs it):
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
// src/lib/cms.ts
|
|
99
|
+
import { createReader } from 'editlet/next';
|
|
100
|
+
import type { EntryMap } from '../../.editlet/content';
|
|
101
|
+
|
|
102
|
+
export const { getEntries, getEntry, getRef } = createReader<EntryMap>();
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
The type import path is relative to the file: `../../.editlet/content` from `src/lib/`, `../.editlet/content` from
|
|
106
|
+
`lib/`. Use the functions in Server Components:
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
const posts = await getEntries('post'); // sorted by slug; drafts are left out of production builds
|
|
110
|
+
const post = await getEntry('post', 'hello-world'); // undefined when missing
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Markdown bodies with images need `assetUrl(entry, url)` from `editlet/next` in the Markdown renderer's URL transform.
|
|
114
|
+
Image fields already hold the public URL in `src`.
|
|
115
|
+
|
|
116
|
+
To let the editor point at an entry on the page, add `data-editlet-entry="post/hello-world"` to the element that shows
|
|
117
|
+
it. The same mark turns on select to edit (select words of the entry, press **Edit**).
|
|
118
|
+
|
|
119
|
+
## 6. Verify
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
node .claude/skills/editlet/scripts/types.mjs
|
|
123
|
+
node .claude/skills/editlet/scripts/validate.mjs
|
|
124
|
+
npm run build
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Then start the dev server in the background on a free port and check:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/__editlet/files # 200
|
|
131
|
+
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/editlet/index.html # 200
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Stop the server when done unless the human wants it running. Give the human `http://localhost:3000/?editlet`.
|
|
135
|
+
|
|
136
|
+
## Do not add unasked
|
|
137
|
+
|
|
138
|
+
- `app/api/editlet/preview/route.ts` (only with `admin.preview`, see [preview](preview.md));
|
|
139
|
+
- the auth route (only for the live site, see [production](production.md));
|
|
140
|
+
- pages that render the content.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Draft preview (Next.js)
|
|
2
|
+
|
|
3
|
+
The page overlay works everywhere without setup. The draft render is extra and Next.js only: after **Save** on a
|
|
4
|
+
`editlet/*` branch, the live site renders the page from that branch in Next draft mode. Set it up only when the human asks
|
|
5
|
+
for it.
|
|
6
|
+
|
|
7
|
+
## 1. Turn it on
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
// next.config.ts
|
|
11
|
+
export default withEditlet(nextConfig, {
|
|
12
|
+
admin: { authUrl: '…', preview: true },
|
|
13
|
+
});
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
`preview: true` needs a known repository (`admin.repo`, or Vercel's git env) and `git.baseBranch` in the schema.
|
|
17
|
+
|
|
18
|
+
## 2. The route
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
// src/app/api/editlet/preview/route.ts
|
|
22
|
+
export { POST, DELETE } from 'editlet/next/preview';
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## 3. Server env variables
|
|
26
|
+
|
|
27
|
+
Add the names to `.env.example`; the human sets the values in the host.
|
|
28
|
+
|
|
29
|
+
| Name | Value |
|
|
30
|
+
|---|---|
|
|
31
|
+
| `CMS_PREVIEW_SECRET` | At least 32 random characters. The human generates it: `openssl rand -base64 32` |
|
|
32
|
+
| `CMS_GITHUB_TOKEN` | A fine-grained GitHub token with read-only **Contents** access to the repository |
|
|
33
|
+
|
|
34
|
+
## 4. Pages read the preview ref
|
|
35
|
+
|
|
36
|
+
Every read on a content page passes `{ ref }`, list pages too:
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
import { editletField, previewRef } from 'editlet/next';
|
|
40
|
+
import { getEntry } from '@/lib/cms';
|
|
41
|
+
|
|
42
|
+
const ref = await previewRef(); // { branch, sha } in an editor's draft render, else undefined
|
|
43
|
+
const post = await getEntry('post', slug, { ref });
|
|
44
|
+
return <h1 {...editletField(post, 'title')}>{post.data.title}</h1>;
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
- Call `previewRef()` outside any `'use cache'` scope.
|
|
48
|
+
- Do not set `dynamicParams = false` on content routes: a draft can add a slug that was not built.
|
|
49
|
+
- Change only the pages the human names, or list the pages that read content and ask.
|
|
50
|
+
|
|
51
|
+
## Limits to mention
|
|
52
|
+
|
|
53
|
+
- Images that exist only on the branch are broken in the draft render until the branch deploys.
|
|
54
|
+
- Behind a TLS proxy, forward `Host` / `X-Forwarded-Host` and `X-Forwarded-Proto`, or the route answers `403`.
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# Editing on the live site
|
|
2
|
+
|
|
3
|
+
On the live site there is no dev API. The editor signs in with GitHub, commits to `editlet/<name>` branches (`git.branchPrefix`) and opens pull
|
|
4
|
+
requests; a merge publishes. You set up four things: the auth handler, the GitHub App, the `admin` options, and branch
|
|
5
|
+
protection. The human does every step outside the repo; you prepare the files and give exact values.
|
|
6
|
+
|
|
7
|
+
## 1. Choose where the auth handler runs
|
|
8
|
+
|
|
9
|
+
It needs one stable public HTTPS URL. Preview deploys sign in through the production URL too.
|
|
10
|
+
|
|
11
|
+
| Site | Host the handler | `authUrl` |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| Next.js (Vercel or Node) | A route in the site (below) | `https://<production domain>/api/editlet/oauth` |
|
|
14
|
+
| Astro with an SSR adapter | An endpoint in the site | `https://<production domain>/api/editlet/oauth` |
|
|
15
|
+
| Static Astro, or any other site | A Cloudflare Worker, or a Node / Bun / Deno server | The worker or server URL |
|
|
16
|
+
|
|
17
|
+
If the human did not say, recommend the route in the site for Next.js and a Cloudflare Worker for static Astro, and
|
|
18
|
+
ask once.
|
|
19
|
+
|
|
20
|
+
**Next.js route:**
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
// src/app/api/editlet/oauth/[...path]/route.ts
|
|
24
|
+
import { handleRequest, type Env } from 'editlet/auth';
|
|
25
|
+
|
|
26
|
+
const handler = (request: Request) => handleRequest(request, process.env as Env);
|
|
27
|
+
export { handler as GET, handler as OPTIONS, handler as POST };
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Keep this route out of middleware and out of site-wide CSP and COOP headers.
|
|
31
|
+
|
|
32
|
+
**Astro SSR endpoint:**
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
// src/pages/api/editlet/oauth/[...path].ts
|
|
36
|
+
import { handleRequest } from 'editlet/auth';
|
|
37
|
+
|
|
38
|
+
export const prerender = false;
|
|
39
|
+
export const ALL = ({ request }) => handleRequest(request, process.env);
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
**Cloudflare Worker** (a separate folder or repo, not the site):
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
// worker.ts
|
|
46
|
+
import { handleRequest, type Env } from 'editlet/auth';
|
|
47
|
+
export default { fetch: (request: Request, env: Env) => handleRequest(request, env) };
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
```toml
|
|
51
|
+
# wrangler.toml
|
|
52
|
+
name = "editlet-auth"
|
|
53
|
+
main = "worker.ts"
|
|
54
|
+
compatibility_date = "2026-11-01"
|
|
55
|
+
keep_vars = true
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The human deploys it (`npx wrangler@4 deploy`) and sets the secret (`npx wrangler@4 secret put
|
|
59
|
+
GITHUB_CLIENT_SECRET`). Its URL is `https://editlet-auth.<account>.workers.dev`.
|
|
60
|
+
|
|
61
|
+
## 2. The `admin` options
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
// next.config.ts
|
|
65
|
+
export default withEditlet(nextConfig, {
|
|
66
|
+
admin: { authUrl: 'https://example.com/api/editlet/oauth' },
|
|
67
|
+
});
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
```js
|
|
71
|
+
// astro.config.mjs
|
|
72
|
+
integrations: [editlet({ admin: { repo: 'acme/site', authUrl: 'https://editlet-auth.acme.workers.dev' } })];
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
- `repo` (`owner/name`) can be left out on Vercel and in GitHub Actions; the adapters read it from their env. Set it
|
|
76
|
+
for any other host.
|
|
77
|
+
- `authUrl` must be absolute `https` (or `http://localhost`), or a path starting with `/`.
|
|
78
|
+
- On Vercel, build it from the production domain so preview deploys use the same handler:
|
|
79
|
+
`authUrl: \`https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}/api/editlet/oauth\``. Fall back to the literal
|
|
80
|
+
domain when the variable is not set (local builds).
|
|
81
|
+
- Everything in `admin` is written to the public `/editlet/config.json`. NEVER put a secret there.
|
|
82
|
+
|
|
83
|
+
## 3. Environment variables
|
|
84
|
+
|
|
85
|
+
Write the names to `.env.example` (create it if missing), with empty values and a comment each. NEVER write values.
|
|
86
|
+
|
|
87
|
+
```text
|
|
88
|
+
# GitHub App client ID (not the App ID)
|
|
89
|
+
GITHUB_CLIENT_ID=
|
|
90
|
+
# GitHub App client secret: set it in the host as a secret, never in a file
|
|
91
|
+
GITHUB_CLIENT_SECRET=
|
|
92
|
+
# Origins of the admin pages, comma-separated: https://example.com
|
|
93
|
+
ALLOWED_ORIGINS=
|
|
94
|
+
# Only behind a proxy or under a path: https://example.com/api/editlet/oauth
|
|
95
|
+
PUBLIC_URL=
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Tell the human where to set them: Vercel → Project → Settings → Environment Variables (Production, and Preview if
|
|
99
|
+
previews should sign in), Cloudflare → the worker's Variables and Secrets. If they want you to run `vercel env add`,
|
|
100
|
+
ask first and let them type the secret value themselves.
|
|
101
|
+
|
|
102
|
+
**`ALLOWED_ORIGINS`** is the main security setting: any page on an allowed origin can get a signed-in user's token.
|
|
103
|
+
List the site's own origin(s). A wildcard is allowed only in the host and only on a domain the team owns
|
|
104
|
+
(`https://*.preview.example.com`). NEVER suggest a wildcard on a shared domain: `*.vercel.app`, `*.netlify.app`,
|
|
105
|
+
`*.pages.dev`, `*.github.io`, `*.workers.dev`.
|
|
106
|
+
|
|
107
|
+
## 4. The GitHub App (the human creates it)
|
|
108
|
+
|
|
109
|
+
Give these values; the human fills them in at GitHub → Settings → Developer settings → GitHub Apps → New GitHub App
|
|
110
|
+
(or the organization's settings):
|
|
111
|
+
|
|
112
|
+
| Field | Value |
|
|
113
|
+
|---|---|
|
|
114
|
+
| GitHub App name | for example `<site> Editlet` |
|
|
115
|
+
| Homepage URL | the site URL |
|
|
116
|
+
| Callback URL | `<authUrl>/callback`, for example `https://example.com/api/editlet/oauth/callback` |
|
|
117
|
+
| Expire user authorization tokens | on |
|
|
118
|
+
| Webhook | off (untick Active) |
|
|
119
|
+
| Repository permissions | Contents: Read and write; Pull requests: Read and write; Deployments: Read-only |
|
|
120
|
+
| Where can it be installed | Only on this account |
|
|
121
|
+
|
|
122
|
+
Then: generate a client secret (it goes into `GITHUB_CLIENT_SECRET` in the host), copy the **Client ID** into
|
|
123
|
+
`GITHUB_CLIENT_ID`, and install the app on the content repository.
|
|
124
|
+
|
|
125
|
+
## 5. Protect the base branch
|
|
126
|
+
|
|
127
|
+
An editor's token can merge through the GitHub API, so only GitHub can enforce review. Tell the human to add a ruleset
|
|
128
|
+
on the base branch (GitHub → repo Settings → Rules → Rulesets → New branch ruleset): target the base branch, require
|
|
129
|
+
a pull request with at least one approval, and allow no bypass. If they ask you to do it with `gh api`, show the exact
|
|
130
|
+
command and run it only after an explicit yes. If they want editors who change only content, follow
|
|
131
|
+
[roles](roles.md) instead: it includes this ruleset.
|
|
132
|
+
|
|
133
|
+
## 6. Headers
|
|
134
|
+
|
|
135
|
+
The site must not send `Cross-Origin-Opener-Policy: same-origin`: it cuts the sign-in popup off. Use `unsafe-none`
|
|
136
|
+
(the default) or `same-origin-allow-popups`. Check `headers()` in `next.config.*`, middleware, `vercel.json` and
|
|
137
|
+
`_headers`.
|
|
138
|
+
|
|
139
|
+
## 7. Verify after the deploy
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
node .claude/skills/editlet-setup/scripts/doctor.mjs --url https://example.com
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Then the human opens `https://example.com/?editlet`, signs in with GitHub, saves an edit, and sees an `editlet/*` branch and
|
|
146
|
+
the **Review changes** screen. Branch previews show only when the host reports deployments to GitHub (Vercel does).
|
|
147
|
+
|
|
148
|
+
## What the human does, as a checklist for your final message
|
|
149
|
+
|
|
150
|
+
1. Create the GitHub App with the values in § 4, generate the secret, install the app.
|
|
151
|
+
2. Set the variables in the host (§ 3).
|
|
152
|
+
3. Add the branch ruleset (§ 5).
|
|
153
|
+
4. Deploy, then run `doctor --url` or ask you to.
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
# Roles: admins and editors
|
|
2
|
+
|
|
3
|
+
Use this when the human wants copywriters (editors) who change only content, and admins (developers) who own code,
|
|
4
|
+
the schema and settings. Editlet has no roles of its own: **GitHub enforces everything** with teams, `CODEOWNERS`
|
|
5
|
+
and rulesets. You find out what the plan allows, write `.github/CODEOWNERS`, and prepare the rulesets. The human
|
|
6
|
+
approves every change outside the repo.
|
|
7
|
+
|
|
8
|
+
Do the live-site setup ([production](production.md)) first: editors need the editor to work before roles matter.
|
|
9
|
+
|
|
10
|
+
## Rules for this workflow
|
|
11
|
+
|
|
12
|
+
1. **Read only, until the human says yes.** `gh api` GETs are fine. Every write (`-X POST`, `-X PUT`, `-X PATCH`,
|
|
13
|
+
`-f`, `--input`) is a change outside the repo: show the exact command and its JSON first, run it only after an
|
|
14
|
+
explicit yes, one command at a time.
|
|
15
|
+
2. **`.github/CODEOWNERS` is code.** Leave it uncommitted, or commit it on `setup/editlet` and open a PR. Never on the
|
|
16
|
+
base branch, never on an `editlet/*` branch.
|
|
17
|
+
3. **Merge `CODEOWNERS` before you create the rulesets.** GitHub reads it from the base branch. If the review rules
|
|
18
|
+
come first, the setup PR itself may be blocked (see § 7).
|
|
19
|
+
4. **Never add a bypass the human did not ask for**, and never remove an existing rule to make a step pass.
|
|
20
|
+
|
|
21
|
+
## 1. Look
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
gh api repos/<owner>/<repo> --jq '{owner: .owner.type, visibility, admin: .permissions.admin}'
|
|
25
|
+
node -e "const s=require('./cms/schema.json'); console.log(s.contentDir, s.git.baseBranch)"
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
- `admin` must be `true`: only a repository admin can create rulesets. If not, stop and say who must do it.
|
|
29
|
+
- `owner` and `visibility` decide what is possible:
|
|
30
|
+
|
|
31
|
+
| Account and repo | Teams | Rulesets, `CODEOWNERS` | Push rules (§ 5) |
|
|
32
|
+
|---|---|---|---|
|
|
33
|
+
| Organization, public | yes | yes, on every plan | no (private and internal only) |
|
|
34
|
+
| Organization, private | yes | Team or Enterprise plan | Team or Enterprise plan |
|
|
35
|
+
| Personal account, public | no: name users | yes, on every plan | no |
|
|
36
|
+
| Personal account, private | no: name users | GitHub Pro | no |
|
|
37
|
+
|
|
38
|
+
GitHub's checks are the truth: if a ruleset call below answers `403` or `422` with a plan message, the plan does not
|
|
39
|
+
have it. Say so and continue without that part.
|
|
40
|
+
|
|
41
|
+
Then ask the human, once:
|
|
42
|
+
|
|
43
|
+
- **Who approves content?** (a) editors approve each other, admins can too; (b) only admins approve anything;
|
|
44
|
+
(c) per folder (for example blog posts by editors, legal pages by admins). With (a), an editor can also click Merge
|
|
45
|
+
after a colleague approves (§ 6).
|
|
46
|
+
- **The team names**, or (personal account) the logins of the admins and the editors.
|
|
47
|
+
- **Media outside `contentDir`**, if the site keeps images elsewhere (for example `public/images/`).
|
|
48
|
+
|
|
49
|
+
## 2. Teams (organizations only)
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
gh api orgs/<org>/teams --jq '.[] | {slug, privacy}'
|
|
53
|
+
gh api repos/<owner>/<repo>/teams --jq '.[] | {slug, permission}'
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Both teams must exist, be visible (`privacy: closed`, not `secret`), and have at least **write** on the repo
|
|
57
|
+
(`push`); admins get `admin` or `maintain`. If something is missing, the commands are (each after a yes):
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
gh api -X POST orgs/<org>/teams -f name=editors -f privacy=closed
|
|
61
|
+
gh api -X PUT orgs/<org>/teams/editors/repos/<owner>/<repo> -f permission=push
|
|
62
|
+
gh api -X PUT orgs/<org>/teams/admins/repos/<owner>/<repo> -f permission=admin
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Adding people to the teams is the human's step (GitHub → the organization → Teams).
|
|
66
|
+
|
|
67
|
+
## 3. `.github/CODEOWNERS`
|
|
68
|
+
|
|
69
|
+
Patterns are `.gitignore`-style, paths from the repo root, case-sensitive. **The last matching line wins.** No `!`,
|
|
70
|
+
no `[ ]`. Several owners on one line: **any one** of them can approve. Owners must have write access.
|
|
71
|
+
|
|
72
|
+
Variant (a), with `contentDir` = `cms/content`:
|
|
73
|
+
|
|
74
|
+
```gitignore
|
|
75
|
+
# Everything else (code, schema, settings): admins
|
|
76
|
+
* @<org>/admins
|
|
77
|
+
|
|
78
|
+
# Content and the images next to entries: editors, admins too
|
|
79
|
+
/cms/content/ @<org>/editors @<org>/admins
|
|
80
|
+
|
|
81
|
+
# Only if images live outside contentDir
|
|
82
|
+
/public/images/ @<org>/editors @<org>/admins
|
|
83
|
+
|
|
84
|
+
# Keep last: nobody but admins changes the owners
|
|
85
|
+
/.github/CODEOWNERS @<org>/admins
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
- Variant (b): only the first and the last line.
|
|
89
|
+
- Variant (c): per-folder lines under `/cms/content/`, for example `/cms/content/legal/ @<org>/admins` after the
|
|
90
|
+
`/cms/content/` line (later lines win).
|
|
91
|
+
- Personal account: users instead of teams, `@alice @bob` (each must be a collaborator).
|
|
92
|
+
- `cms/schema.json` is outside `/cms/content/`, so it stays with the admins. Use the schema's real `contentDir`.
|
|
93
|
+
|
|
94
|
+
If the file exists, show a diff and change only what the human agreed to. After the PR is merged, check it:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
gh api "repos/<owner>/<repo>/codeowners/errors?ref=<base>" --jq '.errors'
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`[]` means GitHub accepted every line. Each error has `line`, `kind` and `message`; fix and repeat.
|
|
101
|
+
|
|
102
|
+
## 4. Ruleset on the base branch
|
|
103
|
+
|
|
104
|
+
This replaces the simple ruleset from [production § 5](production.md#5-protect-the-base-branch) or adds to it (rules
|
|
105
|
+
from several rulesets add up; the strictest wins). Check what exists first:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
gh api repos/<owner>/<repo>/rulesets --jq '.[] | {id, name, target, enforcement}'
|
|
109
|
+
gh api repos/<owner>/<repo>/rules/branches/<base>
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Write the body to a temp file outside the repo, show it, and after a yes run
|
|
113
|
+
`gh api -X POST repos/<owner>/<repo>/rulesets --input <file>`:
|
|
114
|
+
|
|
115
|
+
```json
|
|
116
|
+
{
|
|
117
|
+
"name": "Editlet: review before merge",
|
|
118
|
+
"target": "branch",
|
|
119
|
+
"enforcement": "active",
|
|
120
|
+
"conditions": { "ref_name": { "include": ["refs/heads/<base>"], "exclude": [] } },
|
|
121
|
+
"bypass_actors": [],
|
|
122
|
+
"rules": [
|
|
123
|
+
{ "type": "deletion" },
|
|
124
|
+
{ "type": "non_fast_forward" },
|
|
125
|
+
{
|
|
126
|
+
"type": "pull_request",
|
|
127
|
+
"parameters": {
|
|
128
|
+
"required_approving_review_count": 1,
|
|
129
|
+
"require_code_owner_review": true,
|
|
130
|
+
"require_last_push_approval": true,
|
|
131
|
+
"dismiss_stale_reviews_on_push": true,
|
|
132
|
+
"required_review_thread_resolution": false
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
]
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
- `require_last_push_approval`: someone other than the last pusher must approve, so nobody approves their own edit.
|
|
140
|
+
- `enforcement` is `active`. `evaluate` exists only on GitHub Enterprise.
|
|
141
|
+
- **One admin only?** See § 7 before creating this.
|
|
142
|
+
|
|
143
|
+
## 5. Who may create branches, and who may touch code
|
|
144
|
+
|
|
145
|
+
**Branch creation** (every plan that has rulesets). Editors may create only Editlet branches: `<prefix>*`, where the
|
|
146
|
+
prefix is `git.branchPrefix` of the schema (default `editlet/`). In fnmatch `*` does not match `/`, so the pattern is
|
|
147
|
+
`<prefix>**/*`, below for the default:
|
|
148
|
+
|
|
149
|
+
```json
|
|
150
|
+
{
|
|
151
|
+
"name": "Editlet: editors create only editlet/ branches",
|
|
152
|
+
"target": "branch",
|
|
153
|
+
"enforcement": "active",
|
|
154
|
+
"conditions": { "ref_name": { "include": ["~ALL"], "exclude": ["refs/heads/editlet/**/*"] } },
|
|
155
|
+
"bypass_actors": [{ "actor_type": "Team", "actor_id": <admins team id>, "bypass_mode": "always" }],
|
|
156
|
+
"rules": [{ "type": "creation" }]
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Get the team id with `gh api orgs/<org>/teams/admins --jq .id`. Personal account: use the owner as a `User` actor
|
|
161
|
+
(`gh api users/<login> --jq .id`); if GitHub refuses that, ask the human to add the bypass in the UI (Settings → Rules
|
|
162
|
+
→ the ruleset → Bypass list → Repository admin) and read the ruleset back to see the actor it stored.
|
|
163
|
+
|
|
164
|
+
**Push rules** (organization, private or internal repo, Team plan or higher). Editors cannot push anything outside
|
|
165
|
+
the content folders, to any branch, even through the API. `ignored_file_paths` are the allowed exceptions:
|
|
166
|
+
|
|
167
|
+
```json
|
|
168
|
+
{
|
|
169
|
+
"name": "Editlet: editors push only content",
|
|
170
|
+
"target": "push",
|
|
171
|
+
"enforcement": "active",
|
|
172
|
+
"bypass_actors": [{ "actor_type": "Team", "actor_id": <admins team id>, "bypass_mode": "always" }],
|
|
173
|
+
"rules": [
|
|
174
|
+
{
|
|
175
|
+
"type": "file_path_restriction",
|
|
176
|
+
"parameters": {
|
|
177
|
+
"restricted_file_paths": ["**/*", ".*", ".*/**/*"],
|
|
178
|
+
"ignored_file_paths": ["cms/content/**/*"]
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
]
|
|
182
|
+
}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Add the media folder to `ignored_file_paths` if it is outside `contentDir` (`public/images/**/*`). `.*` and `.*/**/*`
|
|
186
|
+
cover dotfiles and `.github/`. Public repos have no push rules: there `CODEOWNERS` keeps code changes waiting for an
|
|
187
|
+
admin's approval, and the branch screen lists "Other files this merge brings in".
|
|
188
|
+
|
|
189
|
+
## 6. What editors can still do
|
|
190
|
+
|
|
191
|
+
Editors need the **Write** role: the editor refuses to work without push access. Write also lets them:
|
|
192
|
+
|
|
193
|
+
- push to any existing branch that no ruleset protects (add `{ "type": "update" }` to the branch-creation ruleset
|
|
194
|
+
to stop that; admins bypass it);
|
|
195
|
+
- **merge a pull request once every rule passes.** With variant (a) an editor can merge after another editor
|
|
196
|
+
approves. If only admins should merge, use variant (b);
|
|
197
|
+
- add labels, close pull requests and issues.
|
|
198
|
+
|
|
199
|
+
Say this to the human in plain words. Triage is not enough (no write); custom roles need GitHub Enterprise.
|
|
200
|
+
|
|
201
|
+
## 7. One admin
|
|
202
|
+
|
|
203
|
+
With `require_last_push_approval` and code owned by `@<org>/admins`, a PR from the only admin that touches code can
|
|
204
|
+
never be approved: there is no second admin. Offer two ways and let the human choose:
|
|
205
|
+
|
|
206
|
+
1. Add a second admin (recommended).
|
|
207
|
+
2. Let admins bypass the base ruleset **for pull requests only**: `"bypass_actors": [{ "actor_type": "Team",
|
|
208
|
+
"actor_id": <admins team id>, "bypass_mode": "pull_request" }]`. The admin still has to open a PR, but can merge
|
|
209
|
+
it without approval. The cost: whoever holds an admin token can merge code alone.
|
|
210
|
+
|
|
211
|
+
The same applies to this setup PR: merge it (rule 3) before § 4.
|
|
212
|
+
|
|
213
|
+
## 8. Check
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
gh api repos/<owner>/<repo>/rules/branches/<base> --jq '.[] | {type, parameters}'
|
|
217
|
+
gh api repos/<owner>/<repo>/rules/branches/doctor-probe --jq '[.[].type]'
|
|
218
|
+
gh api repos/<owner>/<repo>/rules/branches/editlet/doctor-probe --jq '[.[].type]'
|
|
219
|
+
gh api "repos/<owner>/<repo>/rulesets?targets=push" --jq '.[] | {id, name, enforcement}'
|
|
220
|
+
gh api "repos/<owner>/<repo>/codeowners/errors?ref=<base>" --jq '.errors'
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
The branches need not exist. Expect: `pull_request` with `require_code_owner_review: true` and
|
|
224
|
+
`require_last_push_approval: true` on the base; `creation` on `doctor-probe` but **not** on `editlet/doctor-probe` (if it
|
|
225
|
+
is there, the editor cannot create branches at all: fix the exclude pattern); the push ruleset when § 5 applies; no
|
|
226
|
+
CODEOWNERS errors. `doctor.mjs --url <site>` runs the same checks (`github.codeowners`, `github.code-owner-review`,
|
|
227
|
+
`github.creations`, `github.push-rules`, `github.labels`).
|
|
228
|
+
|
|
229
|
+
What you cannot check with the admin's token: how it feels for an editor. Ask the human to sign in to `?editlet` with an
|
|
230
|
+
editor account, save an entry (a branch appears, the pull request asks for the right reviewers), and, on a private
|
|
231
|
+
repo with push rules, see that a change to `cms/schema.json` is refused.
|
|
232
|
+
|
|
233
|
+
## What the human does, as a checklist for your final message
|
|
234
|
+
|
|
235
|
+
1. Add people to the teams (or invite the collaborators).
|
|
236
|
+
2. Review and merge the `CODEOWNERS` PR.
|
|
237
|
+
3. Say yes to each ruleset command, or create them in the UI with the same values.
|
|
238
|
+
4. Test once with an editor account (§ 8).
|