spell 0.8.7 → 0.8.8

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 (243) hide show
  1. package/README-epics.md +96 -36
  2. package/app/package.json +25 -1
  3. package/dist/cli/publish/PublishedPackage.d.ts +2 -1
  4. package/dist/cli/publish/PublishedPackage.js +6 -3
  5. package/dist/cli/publish/ScratchInstall.d.ts +14 -3
  6. package/dist/cli/publish/ScratchInstall.js +69 -8
  7. package/dist/epic/cli/EpicProgram.js +7 -1
  8. package/dist/epic/cli/epicGroups.js +2 -1
  9. package/dist/epic/command/BaseBranch.d.ts +35 -0
  10. package/dist/epic/command/BaseBranch.js +58 -0
  11. package/dist/epic/command/EpicCheckout.d.ts +1 -1
  12. package/dist/epic/command/EpicCheckout.js +4 -4
  13. package/dist/epic/command/EpicGuide.js +3 -2
  14. package/dist/epic/command/EpicTools.d.ts +5 -0
  15. package/dist/epic/command/EpicTools.js +14 -3
  16. package/dist/epic/command/MainMerge.d.ts +26 -15
  17. package/dist/epic/command/MainMerge.js +60 -16
  18. package/dist/epic/command/RepoInit.d.ts +116 -8
  19. package/dist/epic/command/RepoInit.js +308 -13
  20. package/dist/epic/command/Requests.d.ts +1 -0
  21. package/dist/epic/command/Requests.js +6 -1
  22. package/dist/epic/command/SessionMoves.js +2 -1
  23. package/dist/epic/command/SkillsCheck.js +3 -2
  24. package/dist/epic/command/Stock.js +3 -1
  25. package/dist/epic/command/TurnEnd.d.ts +1 -1
  26. package/dist/epic/command/TurnEnd.js +4 -3
  27. package/dist/epic/command/Worktrees.d.ts +18 -3
  28. package/dist/epic/command/Worktrees.js +38 -7
  29. package/dist/epic/command/command.types.d.ts +3 -0
  30. package/dist/epic/components/__pack/epics.entry.js +43 -43
  31. package/dist/epic/components/__pack/epics.pack.js +36 -12794
  32. package/dist/epic/config/EngineFiles.mjs +60 -0
  33. package/dist/epic/config/EpicConfig.d.ts +12 -2
  34. package/dist/epic/config/EpicConfig.js +9 -1
  35. package/dist/epic/config/GitHub.d.ts +41 -1
  36. package/dist/epic/config/GitHub.js +75 -3
  37. package/dist/epic/config/LayeredSettings.js +3 -2
  38. package/dist/epic/server/EpicServer.d.ts +1 -1
  39. package/dist/epic/server/EpicServer.js +26 -12
  40. package/dist/epic/tool/InboxPoller.mjs +2 -1
  41. package/dist/epic/tool/MigrateCommands.js +6 -8
  42. package/dist/epic/tool/PlanDocFiles.js +3 -2
  43. package/dist/epic/tool/ServedFolders.d.ts +1 -1
  44. package/dist/epic/tool/ServedFolders.js +4 -4
  45. package/dist/epic/tools/PageInboxes.js +3 -3
  46. package/dist/epic/tools/_assets/commands.entry.js +149 -68
  47. package/dist/epic/tools/_assets/commands.js +20 -2073
  48. package/dist/epic/tools/_assets/core-reference.entry.js +244 -124
  49. package/dist/epic/tools/_assets/core-reference.js +20 -2142
  50. package/dist/epic/tools/_assets/emoji/cldr/0.js +2 -2
  51. package/dist/epic/tools/_assets/emoji/cldr/a.js +2 -2
  52. package/dist/epic/tools/_assets/emoji/cldr/b.js +2 -2
  53. package/dist/epic/tools/_assets/emoji/cldr/c.js +2 -2
  54. package/dist/epic/tools/_assets/emoji/cldr/d.js +2 -2
  55. package/dist/epic/tools/_assets/emoji/cldr/e.js +2 -2
  56. package/dist/epic/tools/_assets/emoji/cldr/f.js +2 -2
  57. package/dist/epic/tools/_assets/emoji/cldr/g.js +2 -2
  58. package/dist/epic/tools/_assets/emoji/cldr/h.js +2 -2
  59. package/dist/epic/tools/_assets/emoji/cldr/i.js +2 -2
  60. package/dist/epic/tools/_assets/emoji/cldr/j.js +2 -2
  61. package/dist/epic/tools/_assets/emoji/cldr/k.js +2 -2
  62. package/dist/epic/tools/_assets/emoji/cldr/l.js +2 -2
  63. package/dist/epic/tools/_assets/emoji/cldr/m.js +2 -2
  64. package/dist/epic/tools/_assets/emoji/cldr/n.js +2 -2
  65. package/dist/epic/tools/_assets/emoji/cldr/o.js +2 -2
  66. package/dist/epic/tools/_assets/emoji/cldr/p.js +2 -2
  67. package/dist/epic/tools/_assets/emoji/cldr/r.js +2 -2
  68. package/dist/epic/tools/_assets/emoji/cldr/s.js +2 -2
  69. package/dist/epic/tools/_assets/emoji/cldr/t.js +2 -2
  70. package/dist/epic/tools/_assets/emoji/cldr/u.js +2 -2
  71. package/dist/epic/tools/_assets/emoji/cldr/v.js +2 -2
  72. package/dist/epic/tools/_assets/emoji/cldr/w.js +2 -2
  73. package/dist/epic/tools/_assets/emoji/cldr/x.js +2 -2
  74. package/dist/epic/tools/_assets/emoji/cldr/y.js +2 -2
  75. package/dist/epic/tools/_assets/emoji/cldr/z.js +2 -2
  76. package/dist/epic/tools/_assets/emoji/fomantic/0.js +2 -2
  77. package/dist/epic/tools/_assets/emoji/fomantic/a.js +2 -2
  78. package/dist/epic/tools/_assets/emoji/fomantic/b.js +2 -2
  79. package/dist/epic/tools/_assets/emoji/fomantic/c.js +2 -2
  80. package/dist/epic/tools/_assets/emoji/fomantic/d.js +2 -2
  81. package/dist/epic/tools/_assets/emoji/fomantic/e.js +2 -2
  82. package/dist/epic/tools/_assets/emoji/fomantic/f.js +2 -2
  83. package/dist/epic/tools/_assets/emoji/fomantic/g.js +2 -2
  84. package/dist/epic/tools/_assets/emoji/fomantic/h.js +2 -2
  85. package/dist/epic/tools/_assets/emoji/fomantic/i.js +2 -2
  86. package/dist/epic/tools/_assets/emoji/fomantic/j.js +2 -2
  87. package/dist/epic/tools/_assets/emoji/fomantic/k.js +2 -2
  88. package/dist/epic/tools/_assets/emoji/fomantic/l.js +2 -2
  89. package/dist/epic/tools/_assets/emoji/fomantic/m.js +2 -2
  90. package/dist/epic/tools/_assets/emoji/fomantic/n.js +2 -2
  91. package/dist/epic/tools/_assets/emoji/fomantic/o.js +2 -2
  92. package/dist/epic/tools/_assets/emoji/fomantic/p.js +2 -2
  93. package/dist/epic/tools/_assets/emoji/fomantic/q.js +2 -2
  94. package/dist/epic/tools/_assets/emoji/fomantic/r.js +2 -2
  95. package/dist/epic/tools/_assets/emoji/fomantic/s.js +2 -2
  96. package/dist/epic/tools/_assets/emoji/fomantic/t.js +2 -2
  97. package/dist/epic/tools/_assets/emoji/fomantic/u.js +2 -2
  98. package/dist/epic/tools/_assets/emoji/fomantic/v.js +2 -2
  99. package/dist/epic/tools/_assets/emoji/fomantic/w.js +2 -2
  100. package/dist/epic/tools/_assets/emoji/fomantic/x.js +2 -2
  101. package/dist/epic/tools/_assets/emoji/fomantic/y.js +2 -2
  102. package/dist/epic/tools/_assets/emoji/fomantic/z.js +2 -2
  103. package/dist/epic/tools/_assets/goals-live.js +318 -210
  104. package/dist/epic/tools/_assets/highlight.min.js +5764 -5269
  105. package/dist/epic/tools/_assets/lazy/code-engine.js +5 -1270
  106. package/dist/epic/tools/_assets/lazy/markdown-engine.js +67 -1513
  107. package/dist/epic/tools/_assets/lazy/markdown-sanitizer.js +3 -753
  108. package/dist/epic/tools/_assets/spell-comments.entry.js +282 -159
  109. package/dist/epic/tools/_assets/spell-comments.js +24 -3716
  110. package/dist/epic/tools/_assets/spell-doc-comments.js +1243 -816
  111. package/dist/epic/tools/_assets/spell-doc-helpers.js +298 -165
  112. package/dist/epic/tools/_assets/spell-doc-runtime.js +2760 -1415
  113. package/dist/epic/tools/_assets/spell-doc-toolbar.js +396 -227
  114. package/dist/epic/tools/_assets/spell-syntax.entry.js +505 -285
  115. package/dist/epic/tools/_assets/spell-syntax.js +22 -2916
  116. package/dist/epic/tools/_assets/spell-ui-sources.js +102 -60
  117. package/dist/epic/tools/_assets/spell-ui.entry.js +108 -40
  118. package/dist/epic/tools/_assets/spell-ui.js +3131 -46465
  119. package/dist/epic/tools/pages.d.ts +5 -6
  120. package/dist/epic/tools/pages.js +7 -6
  121. package/dist/epic/window.mjs +2 -3
  122. package/dist/ui/components/ui-accordion/UIAccordion.d.ts +1 -0
  123. package/dist/ui/components/ui-ad/UIAd.d.ts +1 -0
  124. package/dist/ui/components/ui-breadcrumbs/UIBreadcrumb.d.ts +1 -0
  125. package/dist/ui/components/ui-breadcrumbs/UIBreadcrumbs.d.ts +1 -0
  126. package/dist/ui/components/ui-button/UIButton.d.ts +8 -3
  127. package/dist/ui/components/ui-button/UIButton.fallback.d.ts +8 -3
  128. package/dist/ui/components/ui-button/UIButtons.d.ts +1 -0
  129. package/dist/ui/components/ui-button/UIOr.d.ts +1 -0
  130. package/dist/ui/components/ui-calendar/UICalendar.d.ts +6 -0
  131. package/dist/ui/components/ui-calendar/UICalendar.fallback.d.ts +6 -0
  132. package/dist/ui/components/ui-card/UICards.d.ts +31 -0
  133. package/dist/ui/components/ui-checkbox/UICheckbox.d.ts +7 -0
  134. package/dist/ui/components/ui-checkbox/UICheckbox.fallback.d.ts +7 -0
  135. package/dist/ui/components/ui-comment/UIComment.d.ts +1 -0
  136. package/dist/ui/components/ui-comment/UIComments.d.ts +1 -0
  137. package/dist/ui/components/ui-components/UIComponents.d.ts +1 -0
  138. package/dist/ui/components/ui-dimmer/UIDimmer.d.ts +1 -0
  139. package/dist/ui/components/ui-divider/UIDivider.d.ts +2 -0
  140. package/dist/ui/components/ui-dropdown/UIDropdown.d.ts +6 -0
  141. package/dist/ui/components/ui-dropdown/UIDropdown.fallback.d.ts +6 -0
  142. package/dist/ui/components/ui-embed/UIEmbed.d.ts +1 -0
  143. package/dist/ui/components/ui-emoji/UIEmoji.d.ts +1 -0
  144. package/dist/ui/components/ui-feed/UIFeed.d.ts +1 -0
  145. package/dist/ui/components/ui-feed/UIFeedEvent.d.ts +1 -0
  146. package/dist/ui/components/ui-flag/UIFlag.d.ts +1 -0
  147. package/dist/ui/components/ui-flyout/UIFlyout.d.ts +1 -0
  148. package/dist/ui/components/ui-form/UIFields.d.ts +1 -0
  149. package/dist/ui/components/ui-form/UIRepeat.d.ts +1 -0
  150. package/dist/ui/components/ui-grid/UIColumn.d.ts +1 -0
  151. package/dist/ui/components/ui-grid/UIGrid.d.ts +1 -0
  152. package/dist/ui/components/ui-grid/UIRow.d.ts +1 -0
  153. package/dist/ui/components/ui-icon/UIIcon.d.ts +3 -2
  154. package/dist/ui/components/ui-icon/UIIcons.d.ts +1 -0
  155. package/dist/ui/components/ui-icon-picker/UIIconPicker.d.ts +6 -0
  156. package/dist/ui/components/ui-icon-picker/UIIconPicker.fallback.d.ts +6 -0
  157. package/dist/ui/components/ui-image/UIImages.d.ts +1 -0
  158. package/dist/ui/components/ui-include/UIInclude.d.ts +1 -0
  159. package/dist/ui/components/ui-input/UIInput.fallback.d.ts +9 -2
  160. package/dist/ui/components/ui-items/UIItems.d.ts +1 -0
  161. package/dist/ui/components/ui-keys/UIKeys.d.ts +1 -0
  162. package/dist/ui/components/ui-label/UILabel.d.ts +2 -0
  163. package/dist/ui/components/ui-label/UILabels.d.ts +1 -0
  164. package/dist/ui/components/ui-list/UIList.d.ts +2 -0
  165. package/dist/ui/components/ui-loader/UILoader.d.ts +1 -0
  166. package/dist/ui/components/ui-message/UIMessage.d.ts +2 -0
  167. package/dist/ui/components/ui-modal/UIModal.d.ts +1 -0
  168. package/dist/ui/components/ui-nag/UINag.d.ts +1 -0
  169. package/dist/ui/components/ui-page/UIPage.d.ts +15 -0
  170. package/dist/ui/components/ui-page/UIPage.es.d.ts +1 -0
  171. package/dist/ui/components/ui-parts/UIActions.d.ts +1 -0
  172. package/dist/ui/components/ui-parts/UIAuthor.d.ts +1 -0
  173. package/dist/ui/components/ui-parts/UIAvatar.d.ts +1 -0
  174. package/dist/ui/components/ui-parts/UIContent.d.ts +1 -0
  175. package/dist/ui/components/ui-parts/UIDate.d.ts +1 -0
  176. package/dist/ui/components/ui-parts/UIDescription.d.ts +1 -0
  177. package/dist/ui/components/ui-parts/UIDetail.d.ts +1 -0
  178. package/dist/ui/components/ui-parts/UIExtra.d.ts +1 -0
  179. package/dist/ui/components/ui-parts/UIHeader.d.ts +3 -1
  180. package/dist/ui/components/ui-parts/UIMeta.d.ts +1 -0
  181. package/dist/ui/components/ui-parts/UIParts.types.d.ts +15 -1
  182. package/dist/ui/components/ui-parts/UISummary.d.ts +1 -0
  183. package/dist/ui/components/ui-parts/UITitle.d.ts +1 -0
  184. package/dist/ui/components/ui-parts/UIValue.d.ts +1 -0
  185. package/dist/ui/components/ui-placeholder/UIPlaceholder.d.ts +1 -0
  186. package/dist/ui/components/ui-placeholder/UIPlaceholderHeader.d.ts +1 -0
  187. package/dist/ui/components/ui-placeholder/UIPlaceholderImage.d.ts +1 -0
  188. package/dist/ui/components/ui-placeholder/UIPlaceholderLine.d.ts +1 -0
  189. package/dist/ui/components/ui-placeholder/UIPlaceholderParagraph.d.ts +1 -0
  190. package/dist/ui/components/ui-progress/UIProgress.d.ts +2 -0
  191. package/dist/ui/components/ui-quote/UIQuote.d.ts +1 -0
  192. package/dist/ui/components/ui-rail/UIRail.d.ts +1 -0
  193. package/dist/ui/components/ui-rating/UIRating.d.ts +6 -0
  194. package/dist/ui/components/ui-rating/UIRating.fallback.d.ts +6 -0
  195. package/dist/ui/components/ui-reveal/UIReveal.d.ts +1 -0
  196. package/dist/ui/components/ui-search/UISearch.fallback.d.ts +13 -1
  197. package/dist/ui/components/ui-section/UISections.d.ts +1 -0
  198. package/dist/ui/components/ui-segment/UISegment.d.ts +2 -0
  199. package/dist/ui/components/ui-segment/UISegments.d.ts +1 -0
  200. package/dist/ui/components/ui-select/UISelect.d.ts +6 -0
  201. package/dist/ui/components/ui-select/UISelect.fallback.d.ts +6 -0
  202. package/dist/ui/components/ui-shape/UISide.d.ts +4 -0
  203. package/dist/ui/components/ui-sidebar/UIPushable.d.ts +1 -0
  204. package/dist/ui/components/ui-sidebar/UIPusher.d.ts +1 -0
  205. package/dist/ui/components/ui-sidebar/UISidebar.d.ts +1 -0
  206. package/dist/ui/components/ui-sides/UISides.d.ts +6 -0
  207. package/dist/ui/components/ui-sides/UISides.fallback.d.ts +6 -0
  208. package/dist/ui/components/ui-slider/UISlider.d.ts +7 -0
  209. package/dist/ui/components/ui-slider/UISlider.fallback.d.ts +7 -0
  210. package/dist/ui/components/ui-space/UISpace.d.ts +1 -0
  211. package/dist/ui/components/ui-statistic/UIStatistic.d.ts +1 -0
  212. package/dist/ui/components/ui-statistic/UIStatistics.d.ts +1 -0
  213. package/dist/ui/components/ui-step/UIStep.d.ts +1 -0
  214. package/dist/ui/components/ui-step/UISteps.d.ts +1 -0
  215. package/dist/ui/components/ui-table/UICell.d.ts +1 -0
  216. package/dist/ui/components/ui-terms/UITerm.d.ts +1 -0
  217. package/dist/ui/components/ui-terms/UITerms.d.ts +1 -0
  218. package/dist/ui/components/ui-theme-editor/UIColorChip.d.ts +1 -0
  219. package/dist/ui/components/ui-theme-editor/UIThemeToken.d.ts +1 -0
  220. package/dist/ui/components/ui-toast/UIToast.d.ts +1 -0
  221. package/dist/ui/components/ui-toc/UIToc.d.ts +1 -0
  222. package/dist/ui/components/ui-transition/UITransition.d.ts +1 -0
  223. package/dist/ui/components/ui-video/UIAudio.d.ts +1 -0
  224. package/dist/ui/components/ui-video/UIVideo.d.ts +1 -0
  225. package/dist/ui/components/ui-visibility/UIVisibility.d.ts +1 -0
  226. package/dist/ui/components/ui-zoom/UIZoom.d.ts +1 -0
  227. package/dist/util/spell/constants.js +1 -1
  228. package/epic/.claude-plugin/plugin.json +1 -1
  229. package/epic/.codex-plugin/plugin.json +1 -1
  230. package/epic/hooks/handoff.mjs +4 -3
  231. package/epic/hooks/worktree.mjs +22 -3
  232. package/epic/package.json +41 -2
  233. package/epic/skills/details/SKILL.md +2 -1
  234. package/epic/skills/epic/SKILL.md +7 -1
  235. package/epic/skills/epic/guide.md +4 -0
  236. package/epic/skills/isolate/SKILL.md +35 -0
  237. package/epic/src/AGENTS.md +6 -2
  238. package/epic/templates/durable.html +1 -1
  239. package/epic/vscode/package.json +1 -1
  240. package/epic/vscode/spell-epic.vsix +0 -0
  241. package/package.json +1 -1
  242. package/parser/package.json +1 -1
  243. package/ui/package.json +15 -2
package/README-epics.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  ```sh
4
4
  git clone git@github.com:ana/my-app.git && cd my-app
5
- node ~/www/spell/bin/spell.mjs epic init # from a clone of Spell, below
5
+ npx spell@next epic init
6
6
  ```
7
7
 
8
8
  <details>
@@ -139,21 +139,7 @@ beside the main checkout rather than inside it.
139
139
  You need Claude Code, VS Code, git, Node 24.11 or later, and GitHub's command, `gh`.
140
140
  These steps are for the FIRST person on a team; everyone after them: "A teammate joins", below.
141
141
 
142
- ### 1. A clone of Spell
143
-
144
- The epic tools run from a clone, once per machine, and the VS Code extension is built in it:
145
-
146
- ```sh
147
- git clone https://github.com/spell-app/spell.git ~/www/spell
148
- cd ~/www/spell
149
- corepack enable
150
- yarn install
151
- ```
152
-
153
- - `~/www/spell` is only the convention these pages use: anywhere will do, and the commands below follow it.
154
- - `corepack: command not found`, and the rest of a first setup: [Setup from zero](README.md#setup-from-zero).
155
-
156
- ### 2. GitHub's command, logged in
142
+ ### 1. GitHub's command, logged in
157
143
 
158
144
  `epic init` uses it to make the team's epic repo, so install it first.
159
145
  On macOS, with Homebrew:
@@ -169,13 +155,13 @@ gh auth login
169
155
  - Without it, `epic init` still sets everything else up, and says how to get it.
170
156
  Run `epic init` again once you're logged in: it makes the epic repo then.
171
157
 
172
- ### 3. `epic init`, in your repo
158
+ ### 2. `epic init`, in your repo
173
159
 
174
160
  From any folder of your repo, a git repo with at least one commit:
175
161
 
176
162
  ```sh
177
163
  cd ~/www/my-app
178
- node ~/www/spell/bin/spell.mjs epic init
164
+ npx spell@next epic init
179
165
  ```
180
166
 
181
167
  <details>
@@ -242,10 +228,11 @@ _Ana's first `epic init`, against the same stand-in for GitHub as the top of thi
242
228
  then a summary, then each step; a gray line before each slow one (GitHub, the push, the server).
243
229
  The settings it wrote are in the file, not printed._
244
230
 
245
- - That runs the clone's `spell epic`, which runs the epic tool beside it.
231
+ - That fetches Spell's package and runs its `spell epic`, which runs the epic tool installed beside it.
246
232
  Once `epic` is on your `PATH` (its plugin step puts it there), `epic init` is the same thing.
247
- - 🌱 No clone, once a `spell@next` with `spell epic` is published: `npx spell@next epic init`.
248
- The extension still needs a clone (below).
233
+ - `epic` and the plugin then run from npm's cache (`~/.npm/_npx`):
234
+ after `npm cache clean`, run this line again.
235
+ - Your project doesn't need yarn: an npm repo works, and yarn, pnpm and bun repos are found by their lock files.
249
236
 
250
237
  In a terminal, it asks every question FIRST but the commit, each `? ` and the question in yellow, then sums up the
251
238
  answers (`> Your name : Ana`, the values bold) before it does anything.
@@ -344,6 +331,25 @@ Gemfile.lock bundle install
344
331
 
345
332
  </details>
346
333
 
334
+ <details>
335
+ <summary>npm or yarn: what your repo needs</summary>
336
+
337
+ Your repo doesn't need yarn.
338
+ A plain npm repo, with a `package-lock.json`, works:
339
+ - `epic init` writes `npm install` as the install command, and every new worktree runs it.
340
+ - `epic worktree merge-main` rewrites a `package-lock.json` that both sides changed with
341
+ `npm install --package-lock-only`, then installs.
342
+ `pnpm-lock.yaml`, `yarn.lock` and `bun.lock` get their own tools the same way.
343
+ - Vitest snapshots are updated with your repo's own runner: `npx vitest run ... --update` for npm.
344
+ With no Vitest in your `package.json` (Jest, say), nothing runs, and a snapshot both sides changed is an ordinary
345
+ conflict, for you to resolve or to list in `.epic/generators.json5`.
346
+
347
+ Yarn is on your machine for one reason: the clone of Spell that `epic` runs from uses it,
348
+ in its own folder, for its own install and to format pages.
349
+ No command runs yarn in your repo.
350
+
351
+ </details>
352
+
347
353
  Then check that `epic` answers:
348
354
 
349
355
  ```sh
@@ -362,18 +368,14 @@ epic ... (...) .../epic
362
368
  - `--version` names the code that answers: its commit, its branch and the folder it's in.
363
369
  - `~/.local/bin`, where the plugin step links `epic`, may not be on your `PATH`: put the link wherever yours looks.
364
370
 
365
- 🌱 Planned: the plugin from Claude Code's marketplace, with no clone.
366
- The marketplace entry exists, but the plugin's `epic` command needs a clone's install to run.
371
+ 🌱 Planned: the plugin from Claude Code's marketplace, without `npx`.
367
372
 
368
373
  ### And the extension
369
374
 
370
375
  The Review tab, where you mark up a page, and the moves between windows need Spell's VS Code extension:
371
376
  the same one in VS Code or Cursor, which runs VS Code's extensions.
372
- No script installs it:
373
- three commands and a reload, in [the extension's README](epic/README-vscode.md#install-it--three-commands-and-a-reload).
374
- - build it in the clone's `epic/vscode/` folder
375
- - install the `.vsix`
376
- - reload your windows
377
+ `epic init` installs it, from the package: reload your windows when it says so (**Developer: Reload Window**).
378
+ From a clone of Spell instead: [the extension's README](epic/README-vscode.md#install-it--three-commands-and-a-reload).
377
379
 
378
380
  In Cursor, the epic tools use `cursor` where VS Code's take `code`: they tell from the window they run in.
379
381
  - Say it outright with `editor` in `.epic/config.json5` (below), or for one machine `SPELL_EPIC_EDITOR=cursor`.
@@ -403,11 +405,11 @@ and CLONES it, beside the code repo:
403
405
 
404
406
  ```sh
405
407
  git clone git@github.com:ana/my-app.git && cd my-app
406
- node ~/www/spell/bin/spell.mjs epic init
408
+ npx spell@next epic init
407
409
  ```
408
410
 
409
411
  - What it printed: the top of this page.
410
- - They need the clone of Spell first (step 1 above).
412
+ - The plugin and the extension are set up on their machine by the same line.
411
413
  - It asks your name and your colour, as it asked the first person, from any folder of the code repo:
412
414
  it finds the repo's main checkout from wherever it runs.
413
415
  - The epic repo is private, unless the first person chose public: they add each teammate to it on GitHub,
@@ -520,6 +522,67 @@ A comment you leave on a page is shared with the plans, the moment the turn's sy
520
522
  in the page's review inbox, a file never committed.
521
523
  What your agent makes of a mark lands in the epic page, under your name, which everyone shares.
522
524
 
525
+ ## <a id="when-main-takes-only-pull-requests"></a>When main takes only pull requests
526
+
527
+ Plenty of GitHub orgs refuse direct pushes to `main`.
528
+ Tell the repo so with one setting, and nothing `epic` does tries to land there:
529
+
530
+ ```sh
531
+ epic init --protected-base
532
+ ```
533
+
534
+ `baseBranchProtected` in `.epic/config.json5` says the base branch can't be pushed to,
535
+ and work reaches it only through a pull request.
536
+
537
+ **You usually don't have to say so.**
538
+ With `gh` logged in and a GitHub remote, `epic init` asks GitHub whether a rule requires a pull request into the branch
539
+ (a ruleset's `pull_request` rule and, if you're allowed to read it, classic branch protection),
540
+ turns the setting on, and says so in one line.
541
+ If it can't find out, it carries on without it.
542
+ A config that already says `false` stays `false`, and `epic init` tells you how to change it.
543
+
544
+ **Setting up the repo goes through a pull request too.**
545
+ `epic init` never commits on `main`:
546
+ - `.epic/config.json5` and `.gitignore` go on a new branch, `epic-setup`, which it pushes.
547
+ - It opens the pull request with `gh pr create`, or prints exactly what to run without `gh`.
548
+ - Your local `main` is left clean: the two files aren't in it until the merge.
549
+ - Epics start working in the repo once it's merged and you've run `git pull`.
550
+ Teammates can join then.
551
+
552
+ Ran `epic init` before the rule existed, and its push was refused?
553
+ It left a commit on your local `main`, and it says what to do:
554
+ `epic init --protected-base` takes that commit back and moves it onto `epic-setup`.
555
+
556
+ **The epic repo is the exception, and it has to stay one.**
557
+ Your plans live in `<repo>.epics`, and every turn pushes straight to its main branch.
558
+ An org-wide rule requiring pull requests must leave that repo out, or the plans stop syncing.
559
+ The setting changes nothing about it.
560
+
561
+ **What changes with the setting on:**
562
+
563
+ | Where | What it does instead |
564
+ | --- | --- |
565
+ | `epic merge <name>` | refuses, in one line saying to open a pull request |
566
+ | `/epic done`, `/isolate done` | no "Merge now": "Push and open a pull request", or "Leave it" |
567
+ | a standing epic's phase | pushed and put in a pull request, rather than merged at once |
568
+ | a new worktree, `epic worktree merge-main` | fast-forward your local `main` from `origin` first |
569
+ | `epic worktree remove --branches` | a branch whose pull request GitHub merged counts as merged, a squash included |
570
+
571
+ Local `main` only moves when you pull, so those fast-forwards keep it from going stale.
572
+ They happen only when it's safe: fast-forward only, nothing uncommitted.
573
+ Offline, or with `main` diverged, they carry on from what you have, and say so.
574
+
575
+ A branch is deleted only if all its commits are in `main`,
576
+ or a merged pull request holds its last commit: a commit made after the merge keeps the branch.
577
+ Asking GitHub takes `gh`; without it, the branch stays, and the line says why.
578
+
579
+ **After a pull request merges,** in the main checkout:
580
+
581
+ ```sh
582
+ git pull
583
+ epic worktree remove <name> --branches
584
+ ```
585
+
523
586
  ## <a id="with-codex"></a>With Codex (or another agent)
524
587
 
525
588
  ```sh
@@ -692,6 +755,7 @@ It's ONE file per repo, `.epic/config.json5` in the main checkout, read by
692
755
  | `contentFolder` | `"../<repo>.epics"` | the epic repo: epics, sagas, guides, pages |
693
756
  | `contentRemote` | the epic repo's address, once it's made (or `--remote`); `""` until then | where every turn pulls the epic repo from and pushes it to, and what a teammate's `epic init` clones; `""`: the plans stay on this machine |
694
757
  | `baseBranch` | from git: the remote's default branch, else `main` or `master`, else the branch the main checkout is on | the branch worktrees start from and merge into |
758
+ | `baseBranchProtected` | `false`, unless `--protected-base` or GitHub says otherwise | the base branch can't be pushed to, and work reaches it only through a pull request ([below](#when-main-takes-only-pull-requests)) |
695
759
  | `worktreesFolder` | `"../<repo>.worktrees"` | where new worktrees go, one folder each, `<worktreesFolder>/<name>` |
696
760
  | `installCommand` | from the lock file; `""` with none | what makes a new worktree ready to run, from its root; `""`: nothing to install |
697
761
  | `installOnCreate` | `true` with an install | whether the worktree hook runs the install before it hands the worktree over |
@@ -842,9 +906,8 @@ epic server url ~/www/my-app.epics/epics/seo/seo.plan.html
842
906
 
843
907
  What you'd trip on today, roughly in the order you'd meet it.
844
908
 
845
- 1. **It all runs from a clone of Spell.**
846
- `epic init` and the epic tools run from one, and the VS Code extension is built and installed by hand in its
847
- `epic/vscode/`.
909
+ 1. **Everything runs from npm's cache.**
910
+ `npx spell@next epic init` installs nothing permanent: after `npm cache clean`, run it again.
848
911
  2. **Sharing needs GitHub.**
849
912
  `epic init` makes the epic repo only through GitHub's `gh`;
850
913
  anywhere else, make it by hand and pass `--remote <address>`.
@@ -856,7 +919,6 @@ What you'd trip on today, roughly in the order you'd meet it.
856
919
  5. **A few skills reach for Spell's own tools.**
857
920
  Where a skill wants the repo's house style or text-rewriting skill, its example is Spell's.
858
921
  - Saved prompts go to `~/.spell/prompts/`.
859
- - `epic worktree merge-main` updates Vitest snapshots with Spell's own command, `yarn vp test run --update`.
860
922
  6. **Claude Code first.**
861
923
  The skills run in Codex too, but five stay Claude Code's, and so do waking a session from the page, session
862
924
  titles and window moves ([With Codex](#with-codex)); any other agent follows `epic guide`.
@@ -896,8 +958,6 @@ What you'd trip on today, roughly in the order you'd meet it.
896
958
  its epics planned, built in worktrees and reviewed on their pages, each reply and comment under its writer's name,
897
959
  every comment seen by the team and answered by its writer's own agent, Claude Code or Codex.
898
960
  **Not yet:**
899
- - setting up without a clone: `npx spell@next epic init` needs a `spell@next` with `spell epic` in it, which isn't
900
- published yet, and the VS Code extension is built in a clone
901
961
  - Cursor tried by a person: its windows, the Review tab's place, a move between windows
902
962
  - Send waking an agent other than Claude Code, and the Codex side tried with a real Codex
903
963
  - a host other than GitHub, without making the epic repo by hand
package/app/package.json CHANGED
@@ -1,10 +1,34 @@
1
1
  {
2
2
  "name": "spell-app",
3
- "version": "0.8.7",
3
+ "version": "0.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "spell": {
7
7
  "commands": "../dist/app/cli/commands.js",
8
8
  "hooks": "../dist/app/cli/hooks.js"
9
+ },
10
+ "pageServer": {
11
+ "routes": [
12
+ "../dist/app/spaces/server/node/routes/appRoutes.js"
13
+ ],
14
+ "pageScripts": [
15
+ {
16
+ "src": "/element/spell-language.js",
17
+ "file": "app/dist-element/spell-language.js",
18
+ "skip": [
19
+ "/components/"
20
+ ]
21
+ }
22
+ ],
23
+ "componentSets": {
24
+ "app": {
25
+ "name": "App UI",
26
+ "dir": "app/docs",
27
+ "assets": "../ui/site/_assets"
28
+ }
29
+ },
30
+ "engineRoutes": {
31
+ "/element/": "app/dist-element"
32
+ }
9
33
  }
10
34
  }
@@ -54,7 +54,8 @@ export declare class PublishedPackage {
54
54
  /**
55
55
  * One of the kit's folders, built into the ONE package: its code into `dist/<folder>/`, its `files` into
56
56
  * `<folder>/`, and a `<folder>/package.json` naming its commands (`"spell": { "commands" }`), which the published
57
- * kit finds by its `"spell": { "folders" }` (`kitFolders()`).
57
+ * kit finds by its `"spell": { "folders" }` (`kitFolders()`), and its `"pageServer"`, at the built paths:
58
+ * the folder's own settings stay readable (the epic server's route modules, `repoSettings()`).
58
59
  */
59
60
  private stageFolder;
60
61
  /** `report`'s counts added to the package's own. */
@@ -58,7 +58,8 @@ var PublishedPackage = class {
58
58
  /**
59
59
  * One of the kit's folders, built into the ONE package: its code into `dist/<folder>/`, its `files` into
60
60
  * `<folder>/`, and a `<folder>/package.json` naming its commands (`"spell": { "commands" }`), which the published
61
- * kit finds by its `"spell": { "folders" }` (`kitFolders()`).
61
+ * kit finds by its `"spell": { "folders" }` (`kitFolders()`), and its `"pageServer"`, at the built paths:
62
+ * the folder's own settings stay readable (the epic server's route modules, `repoSettings()`).
62
63
  */
63
64
  async stageFolder(folder) {
64
65
  const name = basename(folder.root);
@@ -68,14 +69,16 @@ var PublishedPackage = class {
68
69
  mkdirSync(dirname(join(folderStage, file)), { recursive: true });
69
70
  cpSync(join(folder.root, file), join(folderStage, file), { recursive: true });
70
71
  }
72
+ const fromFolder = /* @__PURE__ */ __name((path) => builtPath(path).replace(/^(\.\/)?dist\//, `../${DIST}/${name}/`), "fromFolder");
71
73
  const entry = folder.manifest.spell;
72
- const shipped = Object.entries(entry ?? {}).map(([key, path]) => [key, builtPath(path).replace(/^(\.\/)?dist\//, `../${DIST}/${name}/`)]).filter(([, path]) => existsSync(join(folderStage, path)));
74
+ const shipped = Object.entries(entry ?? {}).map(([key, path]) => [key, fromFolder(path)]).filter(([, path]) => existsSync(join(folderStage, path)));
73
75
  const manifest = {
74
76
  name: folder.manifest.name,
75
77
  version: this.version,
76
78
  private: true,
77
79
  type: "module",
78
- ...shipped.length && { spell: Object.fromEntries(shipped) }
80
+ ...shipped.length && { spell: Object.fromEntries(shipped) },
81
+ ...folder.manifest.pageServer ? { pageServer: mapStrings(folder.manifest.pageServer, fromFolder) } : {}
79
82
  };
80
83
  mkdirSync(folderStage, { recursive: true });
81
84
  writeFileSync(join(folderStage, "package.json"), `${JSON.stringify(manifest, null, 2)}
@@ -2,12 +2,14 @@ import type { PackedPackage, PublishCheck } from "spell/cli/publish";
2
2
  /****************
3
3
  * ### ScratchInstall
4
4
  * The packed packages, installed the way someone outside would: a project in the system's temp folder, far from any
5
- * checkout, `npm install`s every `.tgz`, then three checks run there (epic `repo-split` P19's Verify):
5
+ * checkout, `npm install`s every `.tgz`, then these checks run there (epic `repo-split` P19's Verify):
6
6
  * 1. node imports `spell/util` and `spell/parser/parser`
7
7
  * 2. a page Vite builds, importing `spell/ui/ui-button` and `spell/element`, draws a `<ui-button>` in headless Chromium,
8
8
  * with ONE element base: the button's class extends the page's own `E.DOMElement`, and the built page holds one
9
9
  * `class DOMElement`
10
10
  * 3. `npx spell help` runs; and `npx epic --help`, when `spell-epic` is among them
11
+ * 4. with `spell-epic`: `epic init` in a scratch git repo starts the epic server, under a scratch `HOME`, on a free port;
12
+ * an epic page and the epics pack answer (epic `epic-engine` I246: it started only from a checkout)
11
13
  * - Third-party packages come from the npm registry: it needs the network.
12
14
  * - Each package's name is pinned to its `.tgz` (`overrides`), so the packages' dependencies on each other
13
15
  * (`spell` on `spell-ui` ...) find the packed ones, never the registry's.
@@ -19,7 +21,7 @@ export declare class ScratchInstall {
19
21
  /** The scratch project's folder. */
20
22
  readonly dir: string;
21
23
  constructor(packed: PackedPackage[]);
22
- /** Install, then run the three checks; every result, passed or failed. NEVER throws. */
24
+ /** Install, then run the checks; every result, passed or failed. NEVER throws. */
23
25
  run(): Promise<PublishCheck[]>;
24
26
  /** `npm install` every packed file, each name pinned to its file. */
25
27
  private install;
@@ -29,12 +31,21 @@ export declare class ScratchInstall {
29
31
  private spellHelp;
30
32
  /** `npx epic --help`, from the installed `spell-epic`: its bin runs `spell`'s built epic command. */
31
33
  private epicHelp;
34
+ /**
35
+ * `epic init` in a scratch git repo, under a scratch `HOME` and on a free port: the epic server starts from the
36
+ * install, then an epic page and the epics pack answer. The server is stopped again, whatever happens.
37
+ * - `--no-plugin`: no Claude Code, no editor, no network; `--no-commit`, `--no-remote`: nothing to push
38
+ */
39
+ private epicServer;
32
40
  /**
33
41
  * A page importing `spell-ui` and `spell/element`, built by the installed Vite, served, and opened in headless
34
42
  * Chromium: it draws a `<ui-button>`, whose class extends the page's own `E.DOMElement`.
35
43
  */
36
44
  private page;
37
- /** Run `command` in the scratch folder; its output. Throws with its stderr when it fails. */
45
+ /**
46
+ * Run `command` in the scratch folder (or `cwd`); its output. Throws with its stderr when it fails.
47
+ * - `env`: added to this process's; the checkout's own `epic` variables never reach it
48
+ */
38
49
  private exec;
39
50
  /** One check, from `work`'s result or failure. */
40
51
  private step;
@@ -19,7 +19,7 @@ var ScratchInstall = class {
19
19
  }
20
20
  /** The scratch project's folder. */
21
21
  dir;
22
- /** Install, then run the three checks; every result, passed or failed. NEVER throws. */
22
+ /** Install, then run the checks; every result, passed or failed. NEVER throws. */
23
23
  async run() {
24
24
  const checks = [];
25
25
  const install = this.step("npm install of every .tgz, outside the checkout", () => this.install());
@@ -28,8 +28,10 @@ var ScratchInstall = class {
28
28
  checks.push(this.step("node imports spell/util and spell/parser/parser", () => this.nodeImports()));
29
29
  checks.push(await this.asyncStep("a Vite page draws <ui-button>, with one DOMElement", () => this.page()));
30
30
  checks.push(this.step("npx spell help runs", () => this.spellHelp()));
31
- if (this.packed.some((pkg) => pkg.name === "spell-epic"))
31
+ if (this.packed.some((pkg) => pkg.name === "spell-epic")) {
32
32
  checks.push(this.step("npx epic --help runs (spell-epic's bin, on spell's code)", () => this.epicHelp()));
33
+ checks.push(await this.asyncStep("the epic server starts and serves an epic page", () => this.epicServer()));
34
+ }
33
35
  }
34
36
  if (checks.every((check) => check.ok)) rmSync(this.dir, { recursive: true, force: true });
35
37
  else checks.push({ check: "scratch project kept, to look into", ok: true, detail: this.dir });
@@ -49,7 +51,7 @@ var ScratchInstall = class {
49
51
  dependencies,
50
52
  overrides
51
53
  });
52
- this.exec("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], 6e5);
54
+ this.exec("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], { timeout: 6e5 });
53
55
  return `${this.packed.length} packages in ${this.dir}`;
54
56
  }
55
57
  /** Node imports two names, from the installed packages' built files. */
@@ -73,6 +75,56 @@ var ScratchInstall = class {
73
75
  if (!/epic/.test(help)) throw new Error(`printed no help: ${help.slice(0, 200)}`);
74
76
  return `${help.split("\n").length} lines`;
75
77
  }
78
+ /**
79
+ * `epic init` in a scratch git repo, under a scratch `HOME` and on a free port: the epic server starts from the
80
+ * install, then an epic page and the epics pack answer. The server is stopped again, whatever happens.
81
+ * - `--no-plugin`: no Claude Code, no editor, no network; `--no-commit`, `--no-remote`: nothing to push
82
+ */
83
+ async epicServer() {
84
+ const home = join(this.dir, "epic-home");
85
+ const repo = join(this.dir, "epic-repo");
86
+ for (const folder of [home, repo]) mkdirSync(folder, { recursive: true });
87
+ const port = await SRV.freePort();
88
+ const env = {
89
+ HOME: home,
90
+ CLAUDE_CONFIG_DIR: join(home, ".claude"),
91
+ SPELL_EPIC_PORT: String(port),
92
+ GIT_DIR: void 0,
93
+ GIT_INDEX_FILE: void 0,
94
+ GIT_WORK_TREE: void 0
95
+ };
96
+ const epic = /* @__PURE__ */ __name((...args) => this.exec("npx", ["--no-install", "epic", ...args], { cwd: repo, env }), "epic");
97
+ this.exec("git", ["init", "-q"], { cwd: repo, env });
98
+ this.exec(
99
+ "git",
100
+ [
101
+ "-c",
102
+ "user.name=Scratch",
103
+ "-c",
104
+ "user.email=scratch@example.com",
105
+ "commit",
106
+ "-q",
107
+ "--allow-empty",
108
+ "-m",
109
+ "scratch"
110
+ ],
111
+ { cwd: repo, env }
112
+ );
113
+ try {
114
+ epic("init", "--no-plugin", "--no-remote", "--no-commit", "--name", "Scratch", "--color", "teal");
115
+ epic("create", "hello", "--title", "Hello");
116
+ const base = `http://127.0.0.1:${port}`;
117
+ const page = await answerOf(`${base}/epics/hello/hello.plan.html`);
118
+ if (!page.includes("<epic-page")) throw new Error("its epic page holds no <epic-page>");
119
+ const pack = await answerOf(`${base}/_epic/pack/epics.pack.js`);
120
+ return `port ${port}: an epic page, ${page.length} bytes; the epics pack, ${pack.length} bytes`;
121
+ } finally {
122
+ try {
123
+ epic("server", "stop");
124
+ } catch {
125
+ }
126
+ }
127
+ }
76
128
  /**
77
129
  * A page importing `spell-ui` and `spell/element`, built by the installed Vite, served, and opened in headless
78
130
  * Chromium: it draws a `<ui-button>`, whose class extends the page's own `E.DOMElement`.
@@ -85,7 +137,7 @@ var ScratchInstall = class {
85
137
  this.exec(
86
138
  "npx",
87
139
  ["--no-install", "vp", "build", "page", "--outDir", "../page-dist", "--emptyOutDir", "--minify", "false"],
88
- 3e5
140
+ { timeout: 3e5 }
89
141
  );
90
142
  const built = join(this.dir, "page-dist");
91
143
  const definitions = readdirSync(built, { recursive: true, withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".js")).map((entry) => readFileSync(join(entry.parentPath, entry.name), "utf8").match(DOM_ELEMENT_CLASS)?.length ?? 0).reduce((sum, count) => sum + count, 0);
@@ -112,15 +164,18 @@ var ScratchInstall = class {
112
164
  ////////////////
113
165
  // ## Helpers
114
166
  ////////////////
115
- /** Run `command` in the scratch folder; its output. Throws with its stderr when it fails. */
116
- exec(command, args, timeout = 12e4) {
167
+ /**
168
+ * Run `command` in the scratch folder (or `cwd`); its output. Throws with its stderr when it fails.
169
+ * - `env`: added to this process's; the checkout's own `epic` variables never reach it
170
+ */
171
+ exec(command, args, { timeout = 12e4, cwd = this.dir, env = {} } = {}) {
117
172
  try {
118
173
  return execFileSync(command, args, {
119
- cwd: this.dir,
174
+ cwd,
120
175
  encoding: "utf8",
121
176
  timeout,
122
177
  stdio: ["ignore", "pipe", "pipe"],
123
- env: { ...process.env, npm_config_update_notifier: "false" }
178
+ env: { ...process.env, EPIC_CHECKOUT: void 0, npm_config_update_notifier: "false", ...env }
124
179
  });
125
180
  } catch (error) {
126
181
  const { stderr, stdout } = error;
@@ -145,6 +200,12 @@ var ScratchInstall = class {
145
200
  }
146
201
  };
147
202
  var DOM_ELEMENT_CLASS = /\bclass DOMElement\b|\bDOMElement = class\b/g;
203
+ async function answerOf(url) {
204
+ const reply = await fetch(url);
205
+ if (!reply.ok) throw new Error(`${url} answered ${reply.status}`);
206
+ return reply.text();
207
+ }
208
+ __name(answerOf, "answerOf");
148
209
  var PAGE_HTML = `<!doctype html>
149
210
  <html>
150
211
  <head><meta charset="utf-8" /><title>spell scratch</title></head>
@@ -447,7 +447,7 @@ var EpicProgram = class _EpicProgram {
447
447
  this.verb(epic.command("init"), (args) => new RepoInit().run(args)).description(
448
448
  "set this repo up for epics, the one command to start (npx spell@next epic init): the plugin, its .epic/config.json5, the epic repo beside it (made, or cloned from the team's), shared on GitHub, the links and their .gitignore lines, your name and colour, then the epic server; safe to run again"
449
449
  ).usage(
450
- "[--name <name>] [--color <colour>] [--content-repo <name> | --remote <address> | --no-remote] [--public] [--no-plugin] [--no-commit] [--no-server] [--dry-run] [--json]"
450
+ "[--name <name>] [--color <colour>] [--content-repo <name> | --remote <address> | --no-remote] [--public] [--protected-base] [--no-plugin] [--no-commit] [--no-server] [--dry-run] [--json]"
451
451
  ).addHelpText("after", INIT_HELP);
452
452
  this.verb(epic.command("whoami"), (args) => new PersonCommands().whoami(args)).description(
453
453
  "who you are on the epics: your short name (kept, else your GitHub login, else git's user.name), your full name and GitHub login; with a name, keeps it; --rename also writes it over the old one on every page"
@@ -812,6 +812,7 @@ The keys (folders print absolute; the file's are relative to the main checkout)
812
812
  contentFolder the epic repo: epics, guides, sagas, the logs
813
813
  contentRemote its address, which everyone pulls from and pushes to ("": none); epic init writes it
814
814
  baseBranch the branch worktrees start from and merge into
815
+ baseBranchProtected whether the base branch takes only pull requests: epic init opens one, epic merge refuses
815
816
  worktreesFolder where new worktrees go, <worktreesFolder>/<name>; may be beside the repo
816
817
  (../spell-app.worktrees), the old .claude/worktrees still read then
817
818
  installCommand what makes a new worktree ready to run
@@ -883,6 +884,8 @@ From any folder of the repo (a worktree's too), each step skipped when it's done
883
884
  with the plans, in the epic repo's people/
884
885
  the commit .epic/config.json5 and .gitignore committed on the base branch ("Commit ... on main?",
885
886
  yes suggested); on another branch it says so; --no-commit skips it
887
+ a base branch that takes only pull requests: they go on a new branch, epic-setup, which it
888
+ pushes and opens a pull request for; local main stays as it was
886
889
  the epic server started, serving this repo: its address printed; --no-server skips it
887
890
  Then push the base branch: a teammate's epic init then clones the plans.
888
891
 
@@ -891,6 +894,9 @@ Then push the base branch: a teammate's epic init then clones the plans.
891
894
  --public makes the epic repo public without asking; with no terminal to ask in, it's private unless --public.
892
895
  A public one shows everything in the plans (epic pages, guides, comments) to anyone.
893
896
 
897
+ --protected-base: the base branch takes only pull requests (baseBranchProtected in the config). Without it,
898
+ epic init asks GitHub, with gh logged in and a GitHub remote, and says in one line when it found so.
899
+
894
900
  --name <name> is the name you go by on the epics, kept in ~/.spell-epic/person.json5 (epic whoami);
895
901
  without it, epic init asks in a terminal, suggesting your GitHub login (else git's user.name), and takes that
896
902
  anywhere else.
@@ -387,7 +387,7 @@ var GROUP_VERBS = {
387
387
  example: "epic worktree remove seo",
388
388
  flags: {
389
389
  "--force": "git's: one with changes too",
390
- "--branches": "and its branch in each repo, when merged (git branch -d)"
390
+ "--branches": "and its branch in each repo, when merged (git branch -d; a merged pull request counts, where main takes only those)"
391
391
  }
392
392
  },
393
393
  {
@@ -1240,6 +1240,7 @@ var VERB_FLAGS = {
1240
1240
  "--public": "make the epic repo public, without asking (else asked, or private)",
1241
1241
  "--no-plugin": "don't install the epic plugin for Claude Code",
1242
1242
  "--no-commit": "don't commit .epic/config.json5 and .gitignore on the base branch",
1243
+ "--protected-base": "the base branch takes only pull requests: put the two files on a new branch, epic-setup, and open one",
1243
1244
  "--no-server": "don't start the epic server",
1244
1245
  "--dry-run": "only say what it would do",
1245
1246
  "--json": "print what it did as JSON"
@@ -0,0 +1,35 @@
1
+ /****************
2
+ * ### `BaseBranch`
3
+ * Bringing the LOCAL base branch up to date with `origin`, for a repo whose base branch takes only pull requests
4
+ * (`baseBranchProtected`).
5
+ * - Why: new worktrees are cut from local `main`, and `epic worktree merge-main` merges local `main`.
6
+ * Nothing lands on it here any more, so without this it goes stale the moment GitHub merges a pull request.
7
+ * - Who: the worktree hook, before it makes a new worktree; `MainMerge`, before it merges.
8
+ * - Safe or not at all: fast-forward only, and only over a clean checkout.
9
+ * Offline, diverged, ahead or dirty, it changes nothing, says so in one line, and the caller carries on.
10
+ * - Its position: node's own modules and the kit's `Git` only, so plain `node` loads it (the worktree hook);
11
+ * NEVER an `enum` or a parameter property.
12
+ * - All `static`: no state.
13
+ ****************/
14
+ export declare class BaseBranch {
15
+ /**
16
+ * Fast-forward branch `base` of main checkout `main` from `origin`, when that can be done safely.
17
+ * - `base` checked out there: `git merge --ff-only`, only with nothing uncommitted there
18
+ * - `base` not checked out there: `git fetch origin <base>:<base>`, which git itself does only as a fast-forward
19
+ * - NEVER throws
20
+ * - SIDE EFFECT: a fetch, and the local branch and its checkout moved
21
+ */
22
+ static catchUp(main: string, base: string): BaseCatchUp;
23
+ }
24
+ /**
25
+ * What `BaseBranch.catchUp()` did.
26
+ * - `action`:
27
+ * - `fast-forwarded`: it moved; `current`: nothing to do
28
+ * - `no remote`: no `origin`, or it has no such branch
29
+ * - `offline`, `ahead`, `diverged`, `dirty`, `failed`: left as it was
30
+ * - `line`: what to tell the person; `""`: nothing worth saying
31
+ */
32
+ export type BaseCatchUp = {
33
+ action: "fast-forwarded" | "current" | "no remote" | "offline" | "ahead" | "diverged" | "dirty" | "failed";
34
+ line: string;
35
+ };
@@ -0,0 +1,58 @@
1
+ var __defProp = Object.defineProperty;
2
+ var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
3
+
4
+ // src/command/BaseBranch.ts
5
+ import { Git } from "spell/server/Git";
6
+ var BaseBranch = class {
7
+ static {
8
+ __name(this, "BaseBranch");
9
+ }
10
+ /**
11
+ * Fast-forward branch `base` of main checkout `main` from `origin`, when that can be done safely.
12
+ * - `base` checked out there: `git merge --ff-only`, only with nothing uncommitted there
13
+ * - `base` not checked out there: `git fetch origin <base>:<base>`, which git itself does only as a fast-forward
14
+ * - NEVER throws
15
+ * - SIDE EFFECT: a fetch, and the local branch and its checkout moved
16
+ */
17
+ static catchUp(main, base) {
18
+ if (!Git.out(["remote", "get-url", "origin"], main)) return { action: "no remote", line: "" };
19
+ const fetched = Git.run(["fetch", "-q", "origin", base], main, { timeout: NETWORK_TIMEOUT });
20
+ if (!fetched.ok) {
21
+ const why = firstLine(fetched.err) || "the fetch failed";
22
+ return { action: "offline", line: `couldn't reach origin (${why}): going on from local ${base}, maybe behind` };
23
+ }
24
+ const theirs = `refs/remotes/origin/${base}`;
25
+ const ours = `refs/heads/${base}`;
26
+ const [local, remote] = [Git.out(["rev-parse", ours], main), Git.out(["rev-parse", theirs], main)];
27
+ if (!local || !remote) return { action: "no remote", line: "" };
28
+ if (local === remote) return { action: "current", line: "" };
29
+ const behind = Git.out(["rev-list", "--count", `${ours}..${theirs}`], main) ?? "0";
30
+ const ahead = Git.out(["rev-list", "--count", `${theirs}..${ours}`], main) ?? "0";
31
+ if (ahead !== "0")
32
+ return behind === "0" ? {
33
+ action: "ahead",
34
+ line: `local ${base} is ${ahead} commit(s) ahead of origin's, which only a pull request can bring there`
35
+ } : {
36
+ action: "diverged",
37
+ line: `local ${base} and origin's have diverged (${ahead} commit(s) only here): going on from local ${base}`
38
+ };
39
+ const onBase = Git.out(["branch", "--show-current"], main) === base;
40
+ if (onBase && Git.out(["status", "--porcelain", "--untracked-files=no"], main))
41
+ return { action: "dirty", line: `local ${base} has uncommitted changes: not fast-forwarded, going on from it` };
42
+ const moved = onBase ? Git.run(["merge", "-q", "--ff-only", theirs], main, { timeout: NETWORK_TIMEOUT }) : Git.run(["fetch", "-q", "origin", `${base}:${base}`], main, { timeout: NETWORK_TIMEOUT });
43
+ if (!moved.ok)
44
+ return {
45
+ action: "failed",
46
+ line: `couldn't fast-forward local ${base} (${firstLine(moved.err) || "git said no"}): going on from it`
47
+ };
48
+ return { action: "fast-forwarded", line: `local ${base} fast-forwarded from origin (${behind} commit(s))` };
49
+ }
50
+ };
51
+ var NETWORK_TIMEOUT = 6e4;
52
+ function firstLine(text) {
53
+ return text.split("\n")[0]?.trim() ?? "";
54
+ }
55
+ __name(firstLine, "firstLine");
56
+ export {
57
+ BaseBranch
58
+ };
@@ -37,7 +37,7 @@ export declare class EpicCheckout {
37
37
  */
38
38
  static mustGit(args: string[], cwd: string, options?: SRV.GitOptions): string;
39
39
  /**
40
- * The checkout this code is in: `src/command/` is two folders down.
40
+ * The checkout this code is in (`EngineFiles.root`; the `epic/` of the `spell` package, in an npm install).
41
41
  * - static: where the running `epic`'s own copy of every tool is (`EpicTools`)
42
42
  */
43
43
  static readonly CODE_ROOT: string;