spell 0.8.8 → 0.8.9

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 (92) hide show
  1. package/README-epics.md +60 -20
  2. package/app/package.json +1 -1
  3. package/app/spaces/@spell/guides/SpellUI/SpellUI.spellml +486 -486
  4. package/app/spaces/@spell/sites/SpellApp/SpellApp.spellml +50 -124
  5. package/dist/app/app/pages/SiteBoardView.css +5 -5
  6. package/dist/app/app/pages/SiteBoardView.js +1 -1
  7. package/dist/app/app/pages/SiteEditorPage.js +6 -3
  8. package/dist/app/app/pages/SiteEdits.js +27 -10
  9. package/dist/app/app/pages/SiteWrites.js +11 -0
  10. package/dist/app/app/runner/spellRuntime.js +1 -0
  11. package/dist/epic/cli/EpicProgram.js +15 -6
  12. package/dist/epic/cli/epicGroups.js +5 -0
  13. package/dist/epic/command/BaseBranch.js +1 -1
  14. package/dist/epic/command/PullRequest.d.ts +45 -0
  15. package/dist/epic/command/PullRequest.js +100 -0
  16. package/dist/epic/command/RepoInit.d.ts +96 -47
  17. package/dist/epic/command/RepoInit.js +222 -96
  18. package/dist/epic/command/Requests.js +2 -1
  19. package/dist/epic/command/Worktrees.d.ts +5 -3
  20. package/dist/epic/command/Worktrees.js +9 -8
  21. package/dist/epic/components/__pack/epics.entry.js +43 -43
  22. package/dist/epic/components/__pack/epics.pack.js +2 -2
  23. package/dist/epic/config/CodeHost.d.ts +96 -0
  24. package/dist/epic/config/CodeHost.js +89 -0
  25. package/dist/epic/config/EpicConfig.d.ts +9 -2
  26. package/dist/epic/config/EpicConfig.js +16 -0
  27. package/dist/epic/config/EpicRepo.js +1 -1
  28. package/dist/epic/config/GitHub.d.ts +34 -2
  29. package/dist/epic/config/GitHub.js +36 -7
  30. package/dist/epic/config/GitLab.d.ts +138 -0
  31. package/dist/epic/config/GitLab.js +297 -0
  32. package/dist/epic/tool/PlanCommits.d.ts +7 -4
  33. package/dist/epic/tool/PlanCommits.js +7 -5
  34. package/dist/epic/tool/PlanDocCommands.js +3 -4
  35. package/dist/epic/tool/PlanDocFiles.d.ts +3 -1
  36. package/dist/epic/tool/PlanDocFiles.js +10 -3
  37. package/dist/parser/core/classes/View.d.ts +20 -0
  38. package/dist/parser/core/classes/View.js +91 -17
  39. package/dist/parser/core/core.declarations.json5 +18 -0
  40. package/dist/parser/core/core.scopes.js +5 -0
  41. package/dist/parser/core/sites.d.ts +10 -0
  42. package/dist/parser/core/sites.js +12 -0
  43. package/dist/parser/parser/tokenizer/Tokenizer.d.ts +9 -1
  44. package/dist/parser/parser/tokenizer/Tokenizer.js +43 -5
  45. package/dist/parser/parser/tokenizer/Tokens.d.ts +4 -0
  46. package/dist/parser/parser/tokenizer/Tokens.js +4 -0
  47. package/dist/parser/parser/tokenizer/tokenizer.types.d.ts +5 -0
  48. package/dist/parser/parser/tokenizer/tokenizer.types.js +2 -0
  49. package/dist/parser/py/core/spell_core/apps.py +2 -0
  50. package/dist/parser/spell/PARSING.md +21 -0
  51. package/dist/parser/spell/SpellParser.d.ts +2 -0
  52. package/dist/parser/spell/SpellParser.js +58 -3
  53. package/dist/parser/spell/SpellxTokenizer.js +2 -1
  54. package/dist/parser/spell/SpellxTwin.d.ts +4 -1
  55. package/dist/parser/spell/SpellxTwin.js +10 -3
  56. package/dist/parser/spell/builtinTypes.js +24 -1
  57. package/dist/parser/spell/ingest/PlaceIngest.js +3 -1
  58. package/dist/parser/spell/languages/Language.d.ts +11 -2
  59. package/dist/parser/spell/languages/en/words.js +3 -2
  60. package/dist/parser/spell/languages/es/words.js +7 -4
  61. package/dist/parser/spell/rules/Statement.js +1 -1
  62. package/dist/parser/spell/rules/classes/DrawSlot.js +6 -1
  63. package/dist/parser/spell/rules/sites/SitePage.d.ts +3 -3
  64. package/dist/parser/spell/rules/sites/SitePage.js +2 -2
  65. package/dist/parser/spell/rules/sites/sites.en.js +1 -1
  66. package/dist/parser/spell/rules/sites/sites.es.js +1 -1
  67. package/dist/parser/spell/rules/sites/sites.shared.d.ts +2 -2
  68. package/dist/parser/spell/spell.types.d.ts +7 -0
  69. package/dist/parser/spell/spellSyntax.es.json +6 -6
  70. package/dist/parser/spell/spellSyntax.json +6 -6
  71. package/dist/parser/spellx/SpellxView.js +2 -1
  72. package/dist/ui/components/ui-parts/UIHeader.d.ts +12 -2
  73. package/dist/ui/components/ui-parts/UIHeader.en.d.ts +5 -2
  74. package/dist/ui/components/ui-parts/UIHeader.en.js +6 -3
  75. package/dist/ui/components/ui-parts/UIHeader.js +45 -5
  76. package/dist/ui/components/ui-parts/UIParts.css +18 -0
  77. package/dist/ui/components/ui-parts/UIParts.css.inline.js +1 -1
  78. package/dist/ui/jsx.d.ts +4 -4
  79. package/dist/ui/vocabulary/defaults.generated.js +1 -1
  80. package/dist/util/spell/constants.js +1 -1
  81. package/epic/.claude-plugin/plugin.json +1 -1
  82. package/epic/.codex-plugin/plugin.json +1 -1
  83. package/epic/package.json +1 -1
  84. package/epic/skills/epic/SKILL.md +2 -2
  85. package/epic/skills/epic/guide.md +2 -3
  86. package/epic/skills/isolate/SKILL.md +25 -27
  87. package/epic/src/AGENTS.md +5 -0
  88. package/epic/vscode/package.json +1 -1
  89. package/epic/vscode/spell-epic.vsix +0 -0
  90. package/package.json +1 -1
  91. package/parser/package.json +1 -1
  92. package/ui/package.json +1 -1
package/README-epics.md CHANGED
@@ -72,9 +72,9 @@ and you mark it up when you have time.
72
72
  What that's like, and why: [the epic engine's front page](epic/README.md).
73
73
 
74
74
  Three things to know before you start:
75
- - **Sharing works only with GitHub, for now.**
76
- `epic init` makes the team's epic repo with GitHub's command, `gh`.
77
- GitLab, Bitbucket or a bare git server work too, but you make the repo by hand and pass its address
75
+ - **Sharing works with GitHub and GitLab.**
76
+ `epic init` makes the team's epic repo with the host's own command: `gh`, or `glab` ([On GitLab](#on-gitlab)).
77
+ Bitbucket or a bare git server work too, but you make the repo by hand and pass its address
78
78
  (`epic init --remote <address>`).
79
79
  - **Claude Code first, Codex beside it.**
80
80
  The skills run in both, from one copy; the moves between worktrees and windows are Claude Code's,
@@ -136,7 +136,8 @@ beside the main checkout rather than inside it.
136
136
 
137
137
  ## Setting it up: one command, and an extension
138
138
 
139
- You need Claude Code, VS Code, git, Node 24.11 or later, and GitHub's command, `gh`.
139
+ You need Claude Code, VS Code, git, Node 24.11 or later, and your code host's command: GitHub's `gh`, or GitLab's `glab`
140
+ ([On GitLab](#on-gitlab)).
140
141
  These steps are for the FIRST person on a team; everyone after them: "A teammate joins", below.
141
142
 
142
143
  ### 1. GitHub's command, logged in
@@ -266,8 +267,8 @@ Then, in order, each step under a bold heading, the files in a gray table, a gra
266
267
  A file already there is kept as it is.
267
268
  3. Makes the epic folder, `../<repo>.epics`, a git repo of its own.
268
269
  It holds the four folders, a README, and a `.gitignore` for what's never committed.
269
- 4. Makes the epic repo on GitHub: private unless you said public, under your account,
270
- or under the organization your code repo is on.
270
+ 4. Makes the epic repo on GitHub or GitLab: private unless you said public, under your account,
271
+ or under the organization or group your code repo is on.
271
272
  It pushes the epic repo there, and writes its address in the config, `contentRemote`.
272
273
  5. Links each of the four folders in at the checkout's root; every new worktree gets the same links.
273
274
  6. Lists the links in a block of your `.gitignore`.
@@ -412,10 +413,10 @@ npx spell@next epic init
412
413
  - The plugin and the extension are set up on their machine by the same line.
413
414
  - It asks your name and your colour, as it asked the first person, from any folder of the code repo:
414
415
  it finds the repo's main checkout from wherever it runs.
415
- - The epic repo is private, unless the first person chose public: they add each teammate to it on GitHub,
416
+ - The epic repo is private, unless the first person chose public: they add each teammate to it on GitHub or GitLab,
416
417
  with write access, since every turn pushes.
417
- - Joining needs no `gh`: plain git clones the epic repo.
418
- With `gh` logged in, though, your short name defaults to your GitHub login.
418
+ - Joining needs no `gh` or `glab`: plain git clones the epic repo.
419
+ With one logged in, though, your short name defaults to your login there.
419
420
  - The plugin step and the extension are once per machine, so a teammate does those too.
420
421
 
421
422
  ### Who you are
@@ -524,7 +525,8 @@ What your agent makes of a mark lands in the epic page, under your name, which e
524
525
 
525
526
  ## <a id="when-main-takes-only-pull-requests"></a>When main takes only pull requests
526
527
 
527
- Plenty of GitHub orgs refuse direct pushes to `main`.
528
+ Plenty of GitHub orgs and GitLab groups refuse direct pushes to `main`.
529
+ Below, "pull request" means a GitLab merge request too; on GitLab, `epic` says "merge request".
528
530
  Tell the repo so with one setting, and nothing `epic` does tries to land there:
529
531
 
530
532
  ```sh
@@ -535,8 +537,9 @@ epic init --protected-base
535
537
  and work reaches it only through a pull request.
536
538
 
537
539
  **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
+ With `gh` or `glab` logged in, `epic init` asks the host whether the branch takes only requests
541
+ (GitHub: a ruleset's `pull_request` rule and, if you're allowed to read it, classic branch protection;
542
+ GitLab: the project's protected branches: nobody allowed to push, or a push level above yours),
540
543
  turns the setting on, and says so in one line.
541
544
  If it can't find out, it carries on without it.
542
545
  A config that already says `false` stays `false`, and `epic init` tells you how to change it.
@@ -544,7 +547,7 @@ A config that already says `false` stays `false`, and `epic init` tells you how
544
547
  **Setting up the repo goes through a pull request too.**
545
548
  `epic init` never commits on `main`:
546
549
  - `.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`.
550
+ - It opens the pull request with `gh` or `glab`, or prints exactly what to run without one.
548
551
  - Your local `main` is left clean: the two files aren't in it until the merge.
549
552
  - Epics start working in the repo once it's merged and you've run `git pull`.
550
553
  Teammates can join then.
@@ -566,7 +569,7 @@ The setting changes nothing about it.
566
569
  | `/epic done`, `/isolate done` | no "Merge now": "Push and open a pull request", or "Leave it" |
567
570
  | a standing epic's phase | pushed and put in a pull request, rather than merged at once |
568
571
  | 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 |
572
+ | `epic worktree remove --branches` | a branch whose pull request the code host merged counts as merged, a squash included |
570
573
 
571
574
  Local `main` only moves when you pull, so those fast-forwards keep it from going stale.
572
575
  They happen only when it's safe: fast-forward only, nothing uncommitted.
@@ -574,7 +577,9 @@ Offline, or with `main` diverged, they carry on from what you have, and say so.
574
577
 
575
578
  A branch is deleted only if all its commits are in `main`,
576
579
  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.
580
+ Asking the host takes `gh` or `glab`; without it, the branch stays, and the line says why.
581
+
582
+ To push a branch and open its pull request by hand: `epic pr <name>` ([the CLI page](epic/README-cli.md)).
578
583
 
579
584
  **After a pull request merges,** in the main checkout:
580
585
 
@@ -583,6 +588,37 @@ git pull
583
588
  epic worktree remove <name> --branches
584
589
  ```
585
590
 
591
+ ## <a id="on-gitlab"></a>On GitLab
592
+
593
+ `epic init` works on GitLab, self-hosted too, as it does on GitHub: the shared epic repo made, and a setup merge request
594
+ where `main` is protected.
595
+ **So far this has run only against a stand-in `glab`**: a script that answers as GitLab's API documents,
596
+ with real `git` pushes to a local repo whose hook refuses `main`.
597
+ No real GitLab has been tried yet, so expect rough edges and tell us.
598
+
599
+ You need GitLab's command, `glab`, logged in:
600
+
601
+ ```sh
602
+ brew install glab # other systems: https://gitlab.com/gitlab-org/cli
603
+ glab auth login # gitlab.com
604
+ glab auth login --hostname git.acme.com # your own GitLab
605
+ ```
606
+
607
+ - **Which host:** `codeHost` in `.epic/config.json5`, `"github"` or `"gitlab"`.
608
+ Left out, it's read off the `origin` address each time: a host with `gitlab` in it is GitLab, `github.com` GitHub,
609
+ anything else GitHub.
610
+ - **A self-hosted GitLab whose address doesn't say so** (`git.acme.com`): `epic init --host gitlab`.
611
+ In a terminal it asks; with no terminal it stays on GitHub and says so in one line.
612
+ - **Groups and subgroups:** the epic repo goes under the group your code is in (`group/sub/my-app.epics`),
613
+ else your own namespace.
614
+ - **The epic repo must take pushes from teammates, every turn.**
615
+ GitLab protects a new project's default branch, so Developers can't push.
616
+ `epic init` unprotects it right after the first push.
617
+ If it can't (no right to), it says so in one line: unprotect it in the project's
618
+ Settings › Repository › Protected branches, or nobody else can sync.
619
+ An epic repo you made yourself (`--remote`) is yours to open up.
620
+ - **Commit links** on the epic pages go to GitLab's `/-/commit/<sha>`.
621
+
586
622
  ## <a id="with-codex"></a>With Codex (or another agent)
587
623
 
588
624
  ```sh
@@ -755,7 +791,8 @@ It's ONE file per repo, `.epic/config.json5` in the main checkout, read by
755
791
  | `contentFolder` | `"../<repo>.epics"` | the epic repo: epics, sagas, guides, pages |
756
792
  | `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 |
757
793
  | `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)) |
794
+ | `codeHost` | the value it settled on: `--host`, else the `origin` address's, else GitHub; left out, worked out from `origin` each time | where the code is hosted, `"github"` or `"gitlab"`: picks `gh` or `glab` ([On GitLab](#on-gitlab)) |
795
+ | `baseBranchProtected` | `false`, unless `--protected-base` or the code host 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)) |
759
796
  | `worktreesFolder` | `"../<repo>.worktrees"` | where new worktrees go, one folder each, `<worktreesFolder>/<name>` |
760
797
  | `installCommand` | from the lock file; `""` with none | what makes a new worktree ready to run, from its root; `""`: nothing to install |
761
798
  | `installOnCreate` | `true` with an install | whether the worktree hook runs the install before it hands the worktree over |
@@ -908,9 +945,10 @@ What you'd trip on today, roughly in the order you'd meet it.
908
945
 
909
946
  1. **Everything runs from npm's cache.**
910
947
  `npx spell@next epic init` installs nothing permanent: after `npm cache clean`, run it again.
911
- 2. **Sharing needs GitHub.**
912
- `epic init` makes the epic repo only through GitHub's `gh`;
948
+ 2. **Sharing needs GitHub or GitLab.**
949
+ `epic init` makes the epic repo through `gh` or `glab`;
913
950
  anywhere else, make it by hand and pass `--remote <address>`.
951
+ GitLab has run only against a stand-in `glab`, not a real server ([On GitLab](#on-gitlab)).
914
952
  3. **The review controls reach the DEFAULT repo only.**
915
953
  A second repo's pages draw, but their buttons, comments and details pages talk to the default repo's inbox.
916
954
  `epic repos default <name>` picks which repo that is.
@@ -954,13 +992,15 @@ What you'd trip on today, roughly in the order you'd meet it.
954
992
  - `spell rename imports` renames in the peers `repos.json5` names, so never in your project
955
993
  - `spell publish` publishes only the kit's folders that have a `"spellPublish"`
956
994
 
957
- **Real today:** a repo that isn't Spell, set up with one command, its plans shared by a team through GitHub,
995
+ **Real today:** a repo that isn't Spell, set up with one command, its plans shared by a team through GitHub
996
+ (GitLab is built, and tried only against a stand-in `glab`),
958
997
  its epics planned, built in worktrees and reviewed on their pages, each reply and comment under its writer's name,
959
998
  every comment seen by the team and answered by its writer's own agent, Claude Code or Codex.
960
999
  **Not yet:**
961
1000
  - Cursor tried by a person: its windows, the Review tab's place, a move between windows
962
1001
  - Send waking an agent other than Claude Code, and the Codex side tried with a real Codex
963
- - a host other than GitHub, without making the epic repo by hand
1002
+ - a real GitLab, gitlab.com or self-hosted: `glab`'s flags are from its documentation, not a run against a server
1003
+ - a host other than GitHub or GitLab, without making the epic repo by hand
964
1004
  - two repos reviewed from one server
965
1005
  - the keys added since the first outside run, tried anywhere but Spell's own repos:
966
1006
  - `app`
package/app/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spell-app",
3
- "version": "0.8.8",
3
+ "version": "0.8.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "spell": {