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.
- package/README-epics.md +96 -36
- package/app/package.json +25 -1
- package/dist/cli/publish/PublishedPackage.d.ts +2 -1
- package/dist/cli/publish/PublishedPackage.js +6 -3
- package/dist/cli/publish/ScratchInstall.d.ts +14 -3
- package/dist/cli/publish/ScratchInstall.js +69 -8
- package/dist/epic/cli/EpicProgram.js +7 -1
- package/dist/epic/cli/epicGroups.js +2 -1
- package/dist/epic/command/BaseBranch.d.ts +35 -0
- package/dist/epic/command/BaseBranch.js +58 -0
- package/dist/epic/command/EpicCheckout.d.ts +1 -1
- package/dist/epic/command/EpicCheckout.js +4 -4
- package/dist/epic/command/EpicGuide.js +3 -2
- package/dist/epic/command/EpicTools.d.ts +5 -0
- package/dist/epic/command/EpicTools.js +14 -3
- package/dist/epic/command/MainMerge.d.ts +26 -15
- package/dist/epic/command/MainMerge.js +60 -16
- package/dist/epic/command/RepoInit.d.ts +116 -8
- package/dist/epic/command/RepoInit.js +308 -13
- package/dist/epic/command/Requests.d.ts +1 -0
- package/dist/epic/command/Requests.js +6 -1
- package/dist/epic/command/SessionMoves.js +2 -1
- package/dist/epic/command/SkillsCheck.js +3 -2
- package/dist/epic/command/Stock.js +3 -1
- package/dist/epic/command/TurnEnd.d.ts +1 -1
- package/dist/epic/command/TurnEnd.js +4 -3
- package/dist/epic/command/Worktrees.d.ts +18 -3
- package/dist/epic/command/Worktrees.js +38 -7
- package/dist/epic/command/command.types.d.ts +3 -0
- package/dist/epic/components/__pack/epics.entry.js +43 -43
- package/dist/epic/components/__pack/epics.pack.js +36 -12794
- package/dist/epic/config/EngineFiles.mjs +60 -0
- package/dist/epic/config/EpicConfig.d.ts +12 -2
- package/dist/epic/config/EpicConfig.js +9 -1
- package/dist/epic/config/GitHub.d.ts +41 -1
- package/dist/epic/config/GitHub.js +75 -3
- package/dist/epic/config/LayeredSettings.js +3 -2
- package/dist/epic/server/EpicServer.d.ts +1 -1
- package/dist/epic/server/EpicServer.js +26 -12
- package/dist/epic/tool/InboxPoller.mjs +2 -1
- package/dist/epic/tool/MigrateCommands.js +6 -8
- package/dist/epic/tool/PlanDocFiles.js +3 -2
- package/dist/epic/tool/ServedFolders.d.ts +1 -1
- package/dist/epic/tool/ServedFolders.js +4 -4
- package/dist/epic/tools/PageInboxes.js +3 -3
- package/dist/epic/tools/_assets/commands.entry.js +149 -68
- package/dist/epic/tools/_assets/commands.js +20 -2073
- package/dist/epic/tools/_assets/core-reference.entry.js +244 -124
- package/dist/epic/tools/_assets/core-reference.js +20 -2142
- package/dist/epic/tools/_assets/emoji/cldr/0.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/a.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/b.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/c.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/d.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/e.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/f.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/g.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/h.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/i.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/j.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/k.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/l.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/m.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/n.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/o.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/p.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/r.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/s.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/t.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/u.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/v.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/w.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/x.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/y.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/z.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/0.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/a.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/b.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/c.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/d.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/e.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/f.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/g.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/h.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/i.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/j.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/k.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/l.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/m.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/n.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/o.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/p.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/q.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/r.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/s.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/t.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/u.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/v.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/w.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/x.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/y.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/z.js +2 -2
- package/dist/epic/tools/_assets/goals-live.js +318 -210
- package/dist/epic/tools/_assets/highlight.min.js +5764 -5269
- package/dist/epic/tools/_assets/lazy/code-engine.js +5 -1270
- package/dist/epic/tools/_assets/lazy/markdown-engine.js +67 -1513
- package/dist/epic/tools/_assets/lazy/markdown-sanitizer.js +3 -753
- package/dist/epic/tools/_assets/spell-comments.entry.js +282 -159
- package/dist/epic/tools/_assets/spell-comments.js +24 -3716
- package/dist/epic/tools/_assets/spell-doc-comments.js +1243 -816
- package/dist/epic/tools/_assets/spell-doc-helpers.js +298 -165
- package/dist/epic/tools/_assets/spell-doc-runtime.js +2760 -1415
- package/dist/epic/tools/_assets/spell-doc-toolbar.js +396 -227
- package/dist/epic/tools/_assets/spell-syntax.entry.js +505 -285
- package/dist/epic/tools/_assets/spell-syntax.js +22 -2916
- package/dist/epic/tools/_assets/spell-ui-sources.js +102 -60
- package/dist/epic/tools/_assets/spell-ui.entry.js +108 -40
- package/dist/epic/tools/_assets/spell-ui.js +3131 -46465
- package/dist/epic/tools/pages.d.ts +5 -6
- package/dist/epic/tools/pages.js +7 -6
- package/dist/epic/window.mjs +2 -3
- package/dist/ui/components/ui-accordion/UIAccordion.d.ts +1 -0
- package/dist/ui/components/ui-ad/UIAd.d.ts +1 -0
- package/dist/ui/components/ui-breadcrumbs/UIBreadcrumb.d.ts +1 -0
- package/dist/ui/components/ui-breadcrumbs/UIBreadcrumbs.d.ts +1 -0
- package/dist/ui/components/ui-button/UIButton.d.ts +8 -3
- package/dist/ui/components/ui-button/UIButton.fallback.d.ts +8 -3
- package/dist/ui/components/ui-button/UIButtons.d.ts +1 -0
- package/dist/ui/components/ui-button/UIOr.d.ts +1 -0
- package/dist/ui/components/ui-calendar/UICalendar.d.ts +6 -0
- package/dist/ui/components/ui-calendar/UICalendar.fallback.d.ts +6 -0
- package/dist/ui/components/ui-card/UICards.d.ts +31 -0
- package/dist/ui/components/ui-checkbox/UICheckbox.d.ts +7 -0
- package/dist/ui/components/ui-checkbox/UICheckbox.fallback.d.ts +7 -0
- package/dist/ui/components/ui-comment/UIComment.d.ts +1 -0
- package/dist/ui/components/ui-comment/UIComments.d.ts +1 -0
- package/dist/ui/components/ui-components/UIComponents.d.ts +1 -0
- package/dist/ui/components/ui-dimmer/UIDimmer.d.ts +1 -0
- package/dist/ui/components/ui-divider/UIDivider.d.ts +2 -0
- package/dist/ui/components/ui-dropdown/UIDropdown.d.ts +6 -0
- package/dist/ui/components/ui-dropdown/UIDropdown.fallback.d.ts +6 -0
- package/dist/ui/components/ui-embed/UIEmbed.d.ts +1 -0
- package/dist/ui/components/ui-emoji/UIEmoji.d.ts +1 -0
- package/dist/ui/components/ui-feed/UIFeed.d.ts +1 -0
- package/dist/ui/components/ui-feed/UIFeedEvent.d.ts +1 -0
- package/dist/ui/components/ui-flag/UIFlag.d.ts +1 -0
- package/dist/ui/components/ui-flyout/UIFlyout.d.ts +1 -0
- package/dist/ui/components/ui-form/UIFields.d.ts +1 -0
- package/dist/ui/components/ui-form/UIRepeat.d.ts +1 -0
- package/dist/ui/components/ui-grid/UIColumn.d.ts +1 -0
- package/dist/ui/components/ui-grid/UIGrid.d.ts +1 -0
- package/dist/ui/components/ui-grid/UIRow.d.ts +1 -0
- package/dist/ui/components/ui-icon/UIIcon.d.ts +3 -2
- package/dist/ui/components/ui-icon/UIIcons.d.ts +1 -0
- package/dist/ui/components/ui-icon-picker/UIIconPicker.d.ts +6 -0
- package/dist/ui/components/ui-icon-picker/UIIconPicker.fallback.d.ts +6 -0
- package/dist/ui/components/ui-image/UIImages.d.ts +1 -0
- package/dist/ui/components/ui-include/UIInclude.d.ts +1 -0
- package/dist/ui/components/ui-input/UIInput.fallback.d.ts +9 -2
- package/dist/ui/components/ui-items/UIItems.d.ts +1 -0
- package/dist/ui/components/ui-keys/UIKeys.d.ts +1 -0
- package/dist/ui/components/ui-label/UILabel.d.ts +2 -0
- package/dist/ui/components/ui-label/UILabels.d.ts +1 -0
- package/dist/ui/components/ui-list/UIList.d.ts +2 -0
- package/dist/ui/components/ui-loader/UILoader.d.ts +1 -0
- package/dist/ui/components/ui-message/UIMessage.d.ts +2 -0
- package/dist/ui/components/ui-modal/UIModal.d.ts +1 -0
- package/dist/ui/components/ui-nag/UINag.d.ts +1 -0
- package/dist/ui/components/ui-page/UIPage.d.ts +15 -0
- package/dist/ui/components/ui-page/UIPage.es.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIActions.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIAuthor.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIAvatar.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIContent.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIDate.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIDescription.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIDetail.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIExtra.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIHeader.d.ts +3 -1
- package/dist/ui/components/ui-parts/UIMeta.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIParts.types.d.ts +15 -1
- package/dist/ui/components/ui-parts/UISummary.d.ts +1 -0
- package/dist/ui/components/ui-parts/UITitle.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIValue.d.ts +1 -0
- package/dist/ui/components/ui-placeholder/UIPlaceholder.d.ts +1 -0
- package/dist/ui/components/ui-placeholder/UIPlaceholderHeader.d.ts +1 -0
- package/dist/ui/components/ui-placeholder/UIPlaceholderImage.d.ts +1 -0
- package/dist/ui/components/ui-placeholder/UIPlaceholderLine.d.ts +1 -0
- package/dist/ui/components/ui-placeholder/UIPlaceholderParagraph.d.ts +1 -0
- package/dist/ui/components/ui-progress/UIProgress.d.ts +2 -0
- package/dist/ui/components/ui-quote/UIQuote.d.ts +1 -0
- package/dist/ui/components/ui-rail/UIRail.d.ts +1 -0
- package/dist/ui/components/ui-rating/UIRating.d.ts +6 -0
- package/dist/ui/components/ui-rating/UIRating.fallback.d.ts +6 -0
- package/dist/ui/components/ui-reveal/UIReveal.d.ts +1 -0
- package/dist/ui/components/ui-search/UISearch.fallback.d.ts +13 -1
- package/dist/ui/components/ui-section/UISections.d.ts +1 -0
- package/dist/ui/components/ui-segment/UISegment.d.ts +2 -0
- package/dist/ui/components/ui-segment/UISegments.d.ts +1 -0
- package/dist/ui/components/ui-select/UISelect.d.ts +6 -0
- package/dist/ui/components/ui-select/UISelect.fallback.d.ts +6 -0
- package/dist/ui/components/ui-shape/UISide.d.ts +4 -0
- package/dist/ui/components/ui-sidebar/UIPushable.d.ts +1 -0
- package/dist/ui/components/ui-sidebar/UIPusher.d.ts +1 -0
- package/dist/ui/components/ui-sidebar/UISidebar.d.ts +1 -0
- package/dist/ui/components/ui-sides/UISides.d.ts +6 -0
- package/dist/ui/components/ui-sides/UISides.fallback.d.ts +6 -0
- package/dist/ui/components/ui-slider/UISlider.d.ts +7 -0
- package/dist/ui/components/ui-slider/UISlider.fallback.d.ts +7 -0
- package/dist/ui/components/ui-space/UISpace.d.ts +1 -0
- package/dist/ui/components/ui-statistic/UIStatistic.d.ts +1 -0
- package/dist/ui/components/ui-statistic/UIStatistics.d.ts +1 -0
- package/dist/ui/components/ui-step/UIStep.d.ts +1 -0
- package/dist/ui/components/ui-step/UISteps.d.ts +1 -0
- package/dist/ui/components/ui-table/UICell.d.ts +1 -0
- package/dist/ui/components/ui-terms/UITerm.d.ts +1 -0
- package/dist/ui/components/ui-terms/UITerms.d.ts +1 -0
- package/dist/ui/components/ui-theme-editor/UIColorChip.d.ts +1 -0
- package/dist/ui/components/ui-theme-editor/UIThemeToken.d.ts +1 -0
- package/dist/ui/components/ui-toast/UIToast.d.ts +1 -0
- package/dist/ui/components/ui-toc/UIToc.d.ts +1 -0
- package/dist/ui/components/ui-transition/UITransition.d.ts +1 -0
- package/dist/ui/components/ui-video/UIAudio.d.ts +1 -0
- package/dist/ui/components/ui-video/UIVideo.d.ts +1 -0
- package/dist/ui/components/ui-visibility/UIVisibility.d.ts +1 -0
- package/dist/ui/components/ui-zoom/UIZoom.d.ts +1 -0
- package/dist/util/spell/constants.js +1 -1
- package/epic/.claude-plugin/plugin.json +1 -1
- package/epic/.codex-plugin/plugin.json +1 -1
- package/epic/hooks/handoff.mjs +4 -3
- package/epic/hooks/worktree.mjs +22 -3
- package/epic/package.json +41 -2
- package/epic/skills/details/SKILL.md +2 -1
- package/epic/skills/epic/SKILL.md +7 -1
- package/epic/skills/epic/guide.md +4 -0
- package/epic/skills/isolate/SKILL.md +35 -0
- package/epic/src/AGENTS.md +6 -2
- package/epic/templates/durable.html +1 -1
- package/epic/vscode/package.json +1 -1
- package/epic/vscode/spell-epic.vsix +0 -0
- package/package.json +1 -1
- package/parser/package.json +1 -1
- 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
|
-
|
|
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.
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
|
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
|
-
-
|
|
248
|
-
|
|
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,
|
|
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
|
-
|
|
373
|
-
|
|
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
|
-
|
|
408
|
+
npx spell@next epic init
|
|
407
409
|
```
|
|
408
410
|
|
|
409
411
|
- What it printed: the top of this page.
|
|
410
|
-
-
|
|
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. **
|
|
846
|
-
`epic init`
|
|
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.
|
|
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,
|
|
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
|
|
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
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
/**
|
|
116
|
-
|
|
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
|
|
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
|
|
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;
|