editlet 0.0.0-stage → 0.1.0-alpha.1

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 +140 -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,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).