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
@@ -0,0 +1,96 @@
1
+ import { type CodeHostWords, type GhStatus, type MergedPullRequest, type OpenPullRequest, type RepoVisibility } from "./GitHub.ts";
2
+ /****************
3
+ * ### `CodeHost`
4
+ * Which company's server a repo's code is on, and the ONE chooser of how to talk to it: `GitHub` or `GitLab`.
5
+ *
6
+ * ```ts
7
+ * const host = CodeHost.of(config) // an `EpicConfig`, or `{ main, codeHost }`
8
+ * host.status() // => "ready", "missing" or "logged-out"
9
+ * host.words.pullRequest // => "merge request" on GitLab
10
+ * host.openPullRequest({ ... }) // => its address
11
+ * CodeHost.kindOfAddress("git@gitlab.acme.com:a/b.git") // => "gitlab"
12
+ * ```
13
+ *
14
+ * - The setting is `codeHost` in `.epic/config.json5`; a key left out is worked out from the `origin` remote each
15
+ * time it's read: `kindOfAddress()`.
16
+ * - Every caller asks this class; no other code compares host names or kinds.
17
+ * - Its position: `GitHub`, `GitLab` and `EpicHome` beside it, so plain `node` loads it (`EpicConfig` does);
18
+ * NEVER an alias, an `enum` or a parameter property.
19
+ * - All `static`: no state.
20
+ ****************/
21
+ export declare class CodeHost {
22
+ /** The values `codeHost` can take. */
23
+ static readonly KINDS: readonly CodeHostKind[];
24
+ /** Whether `value` is one of `KINDS`. */
25
+ static isKind(value: unknown): value is CodeHostKind;
26
+ /**
27
+ * Whose address git address `address` is: a host naming `gitlab` is GitLab's, `github.com` GitHub's, anything else
28
+ * (no address, a local path, `git.acme.com`) GitHub's by default.
29
+ * - the HOST only, so `github.com:me/gitlab-tools.git` stays GitHub's
30
+ */
31
+ static kindOfAddress(address: string | null | undefined): CodeHostKind;
32
+ /**
33
+ * Whether git address `address` names a host that doesn't say whose it is (`git.acme.com`): `epic init`'s question.
34
+ * - no address, or a local path: `false`: no host to ask about
35
+ */
36
+ static isUnknownAddress(address: string | null | undefined): boolean;
37
+ /** The host of git address `address`, when it has one: `git.acme.com`. */
38
+ static hostOf(address: string | null | undefined): string | undefined;
39
+ /**
40
+ * How to talk to the code host of `config`: `GitHub`, or the `GitLab` of its `origin`.
41
+ * - `config`: an `EpicConfig`, or `{ main, codeHost }` for settings not written yet
42
+ * - reads `origin` from `.git/config`, only for GitLab: it needs the host
43
+ */
44
+ static of(config: CodeHostConfig): CodeHostClient;
45
+ /** The `origin` remote's address in main checkout `main`, as `.git/config` says it; none: `undefined`.
46
+ * - no `git` run: every `EpicConfig` without a `codeHost` asks, the page server's included
47
+ */
48
+ static originOf(main: string): string | undefined;
49
+ /** What a person reads about code host `kind` (a report's lines, with no client to hand); `host`: GitLab's. */
50
+ static wordsFor(kind: CodeHostKind | undefined, host?: string): CodeHostWords;
51
+ /** The repo page `<epic-commit>` links under, for `kind`'s git address `address`; `null` for one that isn't. */
52
+ static commitBase(kind: CodeHostKind, address: string | null | undefined): string | null;
53
+ /**
54
+ * This person's login on `host`, its command asked, for a name to suggest.
55
+ * - GitHub's is kept (`EpicHome.refreshGithub()`): pages show it, never running `gh`
56
+ */
57
+ static loginOn(host: CodeHostClient): string | undefined;
58
+ }
59
+ /** The code hosts `epic` works with. */
60
+ export type CodeHostKind = "github" | "gitlab";
61
+ /** What `CodeHost.of()` takes: an `EpicConfig`, or just the two values it needs. */
62
+ export type CodeHostConfig = {
63
+ main: string;
64
+ codeHost: CodeHostKind;
65
+ };
66
+ /**
67
+ * One code host's operations: `GitHub`'s statics and a `GitLab` both are one of these.
68
+ * - `status()`, `login()`, `isLogin()`: whether its command is there and logged in, and as whom
69
+ * - `isOrganization()`, `ownerIn()`, `repoIn()`: an owner's kind, and what a git address names
70
+ * - `requiresPullRequest()`, `mergedPullRequests()`, `openPullRequestOf()`, `openPullRequest()`: work proposed
71
+ * through a pull or merge request
72
+ * - `createRepo()`, `addressOf()`, `letTeamPush()`: a shared repo made and opened up for the team
73
+ * - `commitBase()`: the page commit links go under
74
+ * - `words`: what a person reads
75
+ */
76
+ export type CodeHostClient = {
77
+ kind: CodeHostKind;
78
+ words: CodeHostWords;
79
+ status(): GhStatus;
80
+ login(): string | undefined;
81
+ isLogin(name: string): boolean;
82
+ isOrganization(owner: string): boolean;
83
+ ownerIn(address: string): string | undefined;
84
+ repoIn(address: string): string | undefined;
85
+ commitBase(address: string | null | undefined): string | null;
86
+ requiresPullRequest(fullName: string, branch: string): boolean;
87
+ mergedPullRequests(branch: string, base: string, cwd: string): MergedPullRequest[];
88
+ openPullRequestOf(branch: string, base: string, cwd: string): string | undefined;
89
+ openPullRequest(request: OpenPullRequest): string;
90
+ createRepo(fullName: string, options?: {
91
+ visibility?: RepoVisibility;
92
+ description?: string;
93
+ }): void;
94
+ addressOf(fullName: string): string;
95
+ letTeamPush(fullName: string, branch: string): string | undefined;
96
+ };
@@ -0,0 +1,89 @@
1
+ var __defProp = Object.defineProperty;
2
+ var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
3
+
4
+ // src/config/CodeHost.ts
5
+ import { readFileSync } from "node:fs";
6
+ import { join } from "node:path";
7
+ import { EpicHome } from "./EpicHome.js";
8
+ import {
9
+ GitHub
10
+ } from "./GitHub.js";
11
+ import { GitLab } from "./GitLab.js";
12
+ var CodeHost = class _CodeHost {
13
+ static {
14
+ __name(this, "CodeHost");
15
+ }
16
+ /** The values `codeHost` can take. */
17
+ static KINDS = ["github", "gitlab"];
18
+ /** Whether `value` is one of `KINDS`. */
19
+ static isKind(value) {
20
+ return _CodeHost.KINDS.includes(value);
21
+ }
22
+ /**
23
+ * Whose address git address `address` is: a host naming `gitlab` is GitLab's, `github.com` GitHub's, anything else
24
+ * (no address, a local path, `git.acme.com`) GitHub's by default.
25
+ * - the HOST only, so `github.com:me/gitlab-tools.git` stays GitHub's
26
+ */
27
+ static kindOfAddress(address) {
28
+ return hostSays(address) ?? "github";
29
+ }
30
+ /**
31
+ * Whether git address `address` names a host that doesn't say whose it is (`git.acme.com`): `epic init`'s question.
32
+ * - no address, or a local path: `false`: no host to ask about
33
+ */
34
+ static isUnknownAddress(address) {
35
+ return Boolean(GitLab.partsOf(address)) && !hostSays(address);
36
+ }
37
+ /** The host of git address `address`, when it has one: `git.acme.com`. */
38
+ static hostOf(address) {
39
+ return GitLab.partsOf(address)?.host;
40
+ }
41
+ /**
42
+ * How to talk to the code host of `config`: `GitHub`, or the `GitLab` of its `origin`.
43
+ * - `config`: an `EpicConfig`, or `{ main, codeHost }` for settings not written yet
44
+ * - reads `origin` from `.git/config`, only for GitLab: it needs the host
45
+ */
46
+ static of(config) {
47
+ return config.codeHost === "gitlab" ? GitLab.ofAddress(_CodeHost.originOf(config.main)) : GitHub;
48
+ }
49
+ /** The `origin` remote's address in main checkout `main`, as `.git/config` says it; none: `undefined`.
50
+ * - no `git` run: every `EpicConfig` without a `codeHost` asks, the page server's included
51
+ */
52
+ static originOf(main) {
53
+ return REMOTE_ORIGIN.exec(readConfig(join(main, ".git", "config")))?.[1]?.trim() || void 0;
54
+ }
55
+ /** What a person reads about code host `kind` (a report's lines, with no client to hand); `host`: GitLab's. */
56
+ static wordsFor(kind, host) {
57
+ return kind === "gitlab" ? GitLab.wordsOn(host) : GitHub.words;
58
+ }
59
+ /** The repo page `<epic-commit>` links under, for `kind`'s git address `address`; `null` for one that isn't. */
60
+ static commitBase(kind, address) {
61
+ return kind === "gitlab" ? GitLab.ofAddress(address).commitBase(address) : GitHub.commitBase(address);
62
+ }
63
+ /**
64
+ * This person's login on `host`, its command asked, for a name to suggest.
65
+ * - GitHub's is kept (`EpicHome.refreshGithub()`): pages show it, never running `gh`
66
+ */
67
+ static loginOn(host) {
68
+ return host === GitHub ? EpicHome.refreshGithub() : host.login();
69
+ }
70
+ };
71
+ function hostSays(address) {
72
+ const host = CodeHost.hostOf(address);
73
+ if (!host) return void 0;
74
+ if (/gitlab/i.test(host)) return "gitlab";
75
+ return /(^|\.)github\.com$/i.test(host) ? "github" : void 0;
76
+ }
77
+ __name(hostSays, "hostSays");
78
+ function readConfig(file) {
79
+ try {
80
+ return readFileSync(file, "utf8");
81
+ } catch {
82
+ return "";
83
+ }
84
+ }
85
+ __name(readConfig, "readConfig");
86
+ var REMOTE_ORIGIN = /\[remote "origin"\][^[]*?\burl\s*=\s*(.+)/;
87
+ export {
88
+ CodeHost
89
+ };
@@ -1,3 +1,4 @@
1
+ import { type CodeHostKind } from "./CodeHost.ts";
1
2
  import { Editor } from "./Editor.ts";
2
3
  /****************
3
4
  * ### `EpicConfig`
@@ -153,6 +154,8 @@ export declare class EpicConfig {
153
154
  get baseBranch(): string;
154
155
  /** whether the base branch can't be pushed to: work reaches it only through a pull request */
155
156
  get baseBranchProtected(): boolean;
157
+ /** where the code is hosted, `github` or `gitlab`: ask `CodeHost.of(config)` how to talk to it */
158
+ get codeHost(): CodeHostKind;
156
159
  /**
157
160
  * the folder NEW worktrees go in, `<worktreesFolder>/<name>`: `worktreesFolder`, from the main checkout
158
161
  * - existing ones may still be in the old place: `worktreesFolders`
@@ -565,8 +568,11 @@ export type EpicOldLayout = {
565
568
  * epic folder is missing
566
569
  * - `baseBranch`: the branch worktrees start from and merge into (the remote's default branch, from git):
567
570
  * the worktree hook, `epic worktree merge-main`, `epic merge`, the behind-main notice
571
+ * - `codeHost`: where the code is hosted, `"github"` or `"gitlab"`: `CodeHost.of()` picks `gh` or `glab` by it
572
+ * - left out, it's worked out from the `origin` remote each time it's read (`CodeHost.kindOfAddress()`):
573
+ * `epic init` writes the value it settled on, for an address that doesn't say (`--host`)
568
574
  * - `baseBranchProtected`: the base branch can't be pushed to, and work reaches it only through a pull request
569
- * (`false`, the default; `epic init` turns it on with `--protected-base`, or when GitHub says so)
575
+ * (`false`, the default; `epic init` turns it on with `--protected-base`, or when the code host says so)
570
576
  * - `epic init` opens a pull request instead of committing on it; `epic merge` refuses
571
577
  * - the worktree hook and `epic worktree merge-main` fast-forward the local base branch from `origin` first
572
578
  * (`BaseBranch`); `epic worktree remove --branches` counts a merged pull request as merged (a squash too)
@@ -659,6 +665,7 @@ export type EpicSettings = {
659
665
  contentRemote: string;
660
666
  baseBranch: string;
661
667
  baseBranchProtected: boolean;
668
+ codeHost: CodeHostKind;
662
669
  worktreesFolder: string;
663
670
  installCommand: string;
664
671
  installOnCreate: boolean;
@@ -683,7 +690,7 @@ export type EpicSettings = {
683
690
  oldLayout: EpicOldLayout;
684
691
  };
685
692
  /** The keys whose value comes from the repo itself, when a file leaves them out (`EpicConfig.defaultsFor()`). */
686
- type RepoKey = "contentFolder" | "baseBranch" | "worktreesFolder" | "installCommand" | "installOnCreate" | "windowsFolder";
693
+ type RepoKey = "contentFolder" | "codeHost" | "baseBranch" | "worktreesFolder" | "installCommand" | "installOnCreate" | "windowsFolder";
687
694
  /**
688
695
  * `EpicConfig.DEFAULTS`: every key of `EpicSettings` with no per-repo value, the same in any repo
689
696
  * - the window names are the repo's; only a window's layout and settings are here
@@ -11,6 +11,7 @@ import { RealPath } from "spell/server/RealPath";
11
11
  import { EngineFiles } from "./EngineFiles.mjs";
12
12
  import { peerRepos } from "spell/server/page/settings";
13
13
  import { PeopleColors } from "./PeopleColors.js";
14
+ import { CodeHost } from "./CodeHost.js";
14
15
  import { Editor, EDITOR_IDS } from "./Editor.js";
15
16
  import { VoiceColor } from "./VoiceColor.js";
16
17
  var EpicConfig = class _EpicConfig {
@@ -184,6 +185,10 @@ var EpicConfig = class _EpicConfig {
184
185
  get baseBranchProtected() {
185
186
  return this.settings.baseBranchProtected;
186
187
  }
188
+ /** where the code is hosted, `github` or `gitlab`: ask `CodeHost.of(config)` how to talk to it */
189
+ get codeHost() {
190
+ return this.settings.codeHost;
191
+ }
187
192
  /**
188
193
  * the folder NEW worktrees go in, `<worktreesFolder>/<name>`: `worktreesFolder`, from the main checkout
189
194
  * - existing ones may still be in the old place: `worktreesFolders`
@@ -776,6 +781,7 @@ var EpicConfig = class _EpicConfig {
776
781
  contentRemote: this.contentRemote,
777
782
  baseBranch: this.baseBranch,
778
783
  baseBranchProtected: this.baseBranchProtected,
784
+ codeHost: this.codeHost,
779
785
  worktreesFolder: this.worktreesFolder,
780
786
  installCommand: this.installCommand,
781
787
  installOnCreate: this.installOnCreate,
@@ -874,6 +880,7 @@ var EpicConfig = class _EpicConfig {
874
880
  return {
875
881
  ...defaults,
876
882
  contentFolder,
883
+ codeHost: CodeHost.kindOfAddress(CodeHost.originOf(main)),
877
884
  baseBranch: written.baseBranch === void 0 ? _EpicConfig.baseBranchOf(main) : "main",
878
885
  worktreesFolder: `../${repo}.worktrees`,
879
886
  installCommand,
@@ -937,6 +944,7 @@ var EpicConfig = class _EpicConfig {
937
944
  contentRemote: valueOf(given, "contentRemote", defaults.contentRemote, file, "", { empty: true }),
938
945
  baseBranch: valueOf(given, "baseBranch", defaults.baseBranch, file),
939
946
  baseBranchProtected: valueOf(given, "baseBranchProtected", defaults.baseBranchProtected, file),
947
+ codeHost: codeHostOf(given, defaults.codeHost, file),
940
948
  worktreesFolder: valueOf(given, "worktreesFolder", defaults.worktreesFolder, file),
941
949
  installCommand: valueOf(given, "installCommand", defaults.installCommand, file, "", { empty: true }),
942
950
  installOnCreate: valueOf(given, "installOnCreate", defaults.installOnCreate, file),
@@ -1024,6 +1032,14 @@ function warnOnce(message) {
1024
1032
  `);
1025
1033
  }
1026
1034
  __name(warnOnce, "warnOnce");
1035
+ function codeHostOf(given, fallback, file) {
1036
+ const value = given.codeHost;
1037
+ if (value === void 0) return fallback;
1038
+ if (!CodeHost.isKind(value))
1039
+ throw new TypeError(`EpicConfig: ${file}'s "codeHost" must be "github" or "gitlab", not ${JSON.stringify(value)}`);
1040
+ return value;
1041
+ }
1042
+ __name(codeHostOf, "codeHostOf");
1027
1043
  function valueOf(given, key, fallback, file, prefix = "", { empty: emptyOk = false } = {}) {
1028
1044
  const value = given[key];
1029
1045
  if (value === void 0) return fallback;
@@ -169,7 +169,7 @@ function currentUrl(url, renames) {
169
169
  }
170
170
  __name(currentUrl, "currentUrl");
171
171
  function normalUrl(url) {
172
- return url.trim().toLowerCase().replace(/^[a-z+]+:\/\//, "").replace(/^[^@/]+@/, "").replace(/^([^/:]+):(?!\d)/, "$1/").replace(/\/+$/, "").replace(/\.git$/, "");
172
+ return url.trim().toLowerCase().replace(/^[a-z+]+:\/\//, "").replace(/^[^@/]+@/, "").replace(/^([^/:]+):(?!\d)/, "$1/").replace(/\/+$/, "").replace(/\/-$/, "").replace(/\.git$/, "");
173
173
  }
174
174
  __name(normalUrl, "normalUrl");
175
175
  function isFolder(path) {
@@ -20,14 +20,20 @@
20
20
  * - STATIC: `gh` is the machine's.
21
21
  * - Its position: node's own modules only, so plain `node` loads it (beside `EpicHome`, which does);
22
22
  * NEVER an alias, an `enum` or a parameter property.
23
+ * - One of the two code hosts: callers ask `CodeHost.of()`, which hands back this class or a `GitLab`;
24
+ * nothing else tells them apart. `run()` runs `glab` for `GitLab` too: one runner.
23
25
  ****************/
24
26
  export declare class GitHub {
27
+ /** Which code host this is: `CodeHost`'s word for it. */
28
+ static readonly kind = "github";
29
+ /** What a person reads about this host: what work is proposed through, and how to get its command. */
30
+ static readonly words: CodeHostWords;
25
31
  /** The `gh` to run: `$SPELL_EPIC_GH`, else `gh` on the `PATH`. Read on every call: a test sets it. */
26
32
  static command(): string;
27
33
  /**
28
34
  * Run `gh <args>`: `{ ok, out, err }`, `out` and `err` trimmed.
29
- * - `command`: the `gh` to run, default `command()`
30
- * - a missing `gh`, a timeout or a failing command is `ok: false`; NEVER throws
35
+ * - `command`: the command to run, default `command()`; `GitLab` passes its `glab` here
36
+ * - a missing command, a timeout or a failing command is `ok: false`; NEVER throws
31
37
  */
32
38
  static run(args: string[], { command, timeout, cwd }?: GhRunOptions): GhResult;
33
39
  /**
@@ -39,6 +45,13 @@ export declare class GitHub {
39
45
  static login(command?: string): string | undefined;
40
46
  /** Whether `name` is a GitHub login: letters, digits and single hyphens, at most 39. */
41
47
  static isLogin(name: string): boolean;
48
+ /**
49
+ * The repo page `<epic-commit>` links under, for git address `address`: `https://github.com/o/r`, which takes
50
+ * `/commit/<sha>`; `null` for an address that isn't GitHub's.
51
+ */
52
+ static commitBase(address: string | null | undefined): string | null;
53
+ /** Nothing to do: a new GitHub repo's main takes pushes from everyone added to it. `CodeHost`'s other side. */
54
+ static letTeamPush(): string | undefined;
42
55
  /** Whether GitHub account `owner` is an organization, not a person; `false` when gh can't say. NEVER throws. */
43
56
  static isOrganization(owner: string): boolean;
44
57
  /**
@@ -66,6 +79,8 @@ export declare class GitHub {
66
79
  * - SIDE EFFECT: a pull request on GitHub
67
80
  */
68
81
  static openPullRequest({ branch, base, title, body, cwd }: OpenPullRequest): string;
82
+ /** The address of the pull request of `branch` into `base` that's open, from checkout `cwd`; none: `undefined`. NEVER throws. */
83
+ static openPullRequestOf(branch: string, base: string, cwd: string): string | undefined;
69
84
  /** `gh <args>`'s output as JSON; `undefined` when it failed or wasn't JSON. NEVER throws. */
70
85
  private static json;
71
86
  /**
@@ -84,6 +99,23 @@ export declare class GitHub {
84
99
  */
85
100
  static addressOf(fullName: string): string;
86
101
  }
102
+ /** What a person reads about a code host: `GitHub.words`, `GitLab`'s; the ONE place that says "merge request". */
103
+ export type CodeHostWords = {
104
+ /** its name: GitHub, GitLab */
105
+ name: string;
106
+ /** its command: `gh`, `glab` */
107
+ command: string;
108
+ /** what work is proposed through, in a sentence: `pull request`, `merge request` */
109
+ pullRequest: string;
110
+ /** that, starting a sentence */
111
+ PullRequest: string;
112
+ /** one of them, as this host numbers it: `#12`, `!12` */
113
+ number: (id: number) => string;
114
+ /** the lines to run to get its command, logged in, two spaces in */
115
+ install: string[];
116
+ /** the line that opens one by hand, for a branch already pushed */
117
+ openCommand: (base: string, branch: string) => string;
118
+ };
87
119
  /** What `GitHub.run()` returns. */
88
120
  export type GhResult = {
89
121
  ok: boolean;
@@ -7,14 +7,26 @@ var GitHub = class _GitHub {
7
7
  static {
8
8
  __name(this, "GitHub");
9
9
  }
10
+ /** Which code host this is: `CodeHost`'s word for it. */
11
+ static kind = "github";
12
+ /** What a person reads about this host: what work is proposed through, and how to get its command. */
13
+ static words = {
14
+ name: "GitHub",
15
+ command: "gh",
16
+ pullRequest: "pull request",
17
+ PullRequest: "Pull request",
18
+ number: /* @__PURE__ */ __name((id) => `#${id}`, "number"),
19
+ install: [" brew install gh (other systems: https://cli.github.com)", " gh auth login"],
20
+ openCommand: /* @__PURE__ */ __name((base, branch) => `gh pr create --base ${base} --head ${branch} --fill`, "openCommand")
21
+ };
10
22
  /** The `gh` to run: `$SPELL_EPIC_GH`, else `gh` on the `PATH`. Read on every call: a test sets it. */
11
23
  static command() {
12
24
  return process.env[GH_ENV] || "gh";
13
25
  }
14
26
  /**
15
27
  * Run `gh <args>`: `{ ok, out, err }`, `out` and `err` trimmed.
16
- * - `command`: the `gh` to run, default `command()`
17
- * - a missing `gh`, a timeout or a failing command is `ok: false`; NEVER throws
28
+ * - `command`: the command to run, default `command()`; `GitLab` passes its `glab` here
29
+ * - a missing command, a timeout or a failing command is `ok: false`; NEVER throws
18
30
  */
19
31
  static run(args, { command = _GitHub.command(), timeout = TIMEOUT_MS, cwd } = {}) {
20
32
  try {
@@ -45,6 +57,18 @@ var GitHub = class _GitHub {
45
57
  static isLogin(name) {
46
58
  return LOGIN.test(name);
47
59
  }
60
+ /**
61
+ * The repo page `<epic-commit>` links under, for git address `address`: `https://github.com/o/r`, which takes
62
+ * `/commit/<sha>`; `null` for an address that isn't GitHub's.
63
+ */
64
+ static commitBase(address) {
65
+ const repo = _GitHub.repoIn(String(address ?? "").trim());
66
+ return repo ? `https://github.com/${repo}` : null;
67
+ }
68
+ /** Nothing to do: a new GitHub repo's main takes pushes from everyone added to it. `CodeHost`'s other side. */
69
+ static letTeamPush() {
70
+ return void 0;
71
+ }
48
72
  /** Whether GitHub account `owner` is an organization, not a person; `false` when gh can't say. NEVER throws. */
49
73
  static isOrganization(owner) {
50
74
  return _GitHub.run(["api", `users/${owner}`, "-q", ".type"]).out === "Organization";
@@ -104,11 +128,8 @@ var GitHub = class _GitHub {
104
128
  * - SIDE EFFECT: a pull request on GitHub
105
129
  */
106
130
  static openPullRequest({ branch, base, title, body, cwd }) {
107
- const open = _GitHub.json(
108
- ["pr", "list", "--head", branch, "--base", base, "--state", "open", "--json", "url"],
109
- { cwd, timeout: NETWORK_MS }
110
- );
111
- if (Array.isArray(open) && open[0]?.url) return open[0].url;
131
+ const open = _GitHub.openPullRequestOf(branch, base, cwd);
132
+ if (open) return open;
112
133
  const run = _GitHub.run(["pr", "create", "--base", base, "--head", branch, "--title", title, "--body", body], {
113
134
  cwd,
114
135
  timeout: CREATE_TIMEOUT_MS
@@ -116,6 +137,14 @@ var GitHub = class _GitHub {
116
137
  if (!run.ok) throw new Error(`gh pr create failed: ${run.err || run.out || "no reason given"}`, { cause: run });
117
138
  return run.out.split("\n").at(-1) ?? "";
118
139
  }
140
+ /** The address of the pull request of `branch` into `base` that's open, from checkout `cwd`; none: `undefined`. NEVER throws. */
141
+ static openPullRequestOf(branch, base, cwd) {
142
+ const open = _GitHub.json(
143
+ ["pr", "list", "--head", branch, "--base", base, "--state", "open", "--json", "url"],
144
+ { cwd, timeout: NETWORK_MS }
145
+ );
146
+ return Array.isArray(open) ? open[0]?.url || void 0 : void 0;
147
+ }
119
148
  /** `gh <args>`'s output as JSON; `undefined` when it failed or wasn't JSON. NEVER throws. */
120
149
  static json(args, options) {
121
150
  const run = _GitHub.run(args, options);
@@ -0,0 +1,138 @@
1
+ import { type CodeHostWords, type GhStatus, type MergedPullRequest, type OpenPullRequest, type RepoVisibility } from "./GitHub.ts";
2
+ /****************
3
+ * ### `GitLab`
4
+ * GitLab's command, `glab`, for the epic tools: the same operations as `GitHub`, on one GitLab instance.
5
+ *
6
+ * ```ts
7
+ * const lab = GitLab.ofAddress("git@git.acme.com:team/sub/app.git")
8
+ * lab.status() // => "ready", "missing" or "logged-out"
9
+ * lab.repoIn("https://git.acme.com/a/b/c") // => "a/b/c"
10
+ * lab.createRepo("team/sub/app.epics") // => the project made, private; throws with glab's words
11
+ * ```
12
+ *
13
+ * - One instance per repo, unlike `GitHub`'s statics: a repo's GitLab may be any host (`git.acme.com`).
14
+ * - Every call names that host, so a self-hosted address works from anywhere: `glab api --hostname`, `glab auth
15
+ * status --hostname`, `glab mr create --repo <its address>`.
16
+ * - Callers ask `CodeHost.of()`, never this class.
17
+ * - It leans on `glab api`, whose answers are GitLab's documented JSON, not `glab`'s printed tables;
18
+ * `glab mr create` is the one exception, and even so its address is read back from the API when it can't be parsed.
19
+ * - It makes a project through the API, never `glab repo create`, whose `--skipGitInit` still adds a local remote
20
+ * (https://gitlab.com/gitlab-org/cli/-/issues/8533).
21
+ * - NOT tried against a real GitLab yet: README-epics.md's "On GitLab" says so.
22
+ * - Its position: `GitHub` beside it (the one runner) and nothing else of ours, so plain `node` loads it;
23
+ * NEVER an alias, an `enum` or a parameter property.
24
+ ****************/
25
+ export declare class GitLab {
26
+ /** Which code host this is: `CodeHost`'s word for it. */
27
+ readonly kind = "gitlab";
28
+ /** the instance: `gitlab.com`, `git.acme.com`; none: `glab` picks */
29
+ readonly host: string | undefined;
30
+ /** the repo's path on it: `team/sub/app`; none for a repo with no GitLab address */
31
+ readonly repoPath: string | undefined;
32
+ /** whether the repo is reached over SSH: a project made for it is too */
33
+ readonly usesSsh: boolean;
34
+ /** - `host`, `repoPath`, `usesSsh`: as the fields; `ofAddress()` works them out from a git address */
35
+ constructor({ host, repoPath, usesSsh }?: {
36
+ host?: string;
37
+ repoPath?: string;
38
+ usesSsh?: boolean;
39
+ });
40
+ /**
41
+ * The `GitLab` of the repo at git address `address`: `git@host:group/sub/p.git`, `ssh://git@host/group/sub/p`,
42
+ * `https://host/group/sub/p.git`; self-hosted hosts too.
43
+ * - no address, or one naming no host (a local path): `glab` picks the host, and there's no repo path
44
+ */
45
+ static ofAddress(address: string | null | undefined): GitLab;
46
+ /**
47
+ * The host, the path and the protocol in git address `address`; `undefined` for a local path or anything else.
48
+ * - scp-like (`git@host:a/b.git`) and `ssh://` are SSH, an `ssh://` port dropped (`glab` knows the web host);
49
+ * `https://` keeps its port
50
+ */
51
+ static partsOf(address: string | null | undefined): {
52
+ host: string;
53
+ path: string;
54
+ ssh: boolean;
55
+ } | undefined;
56
+ /** The `glab` to run: `$SPELL_EPIC_GLAB`, else `glab` on the `PATH`. Read on every call: a test sets it. */
57
+ static command(): string;
58
+ /** What a person reads about this host. */
59
+ get words(): CodeHostWords;
60
+ /** What a person reads about GitLab at `host`: self-hosted, how to log in names it. */
61
+ static wordsOn(host?: string): CodeHostWords;
62
+ /** Run `glab <args>`: as `GitHub.run()`, `glab` by default. NEVER throws. */
63
+ private run;
64
+ /** Call GitLab's API on this repo's host. NEVER throws. */
65
+ private api;
66
+ /** `glab api <endpoint>`'s answer as JSON; `undefined` when it failed or wasn't JSON. NEVER throws. */
67
+ private json;
68
+ /** Whether `glab` can work: `ready`, `missing` (`glab version` doesn't run) or `logged-out`. NEVER throws. */
69
+ status(command?: string): GhStatus;
70
+ /** The GitLab username `glab` is logged in as; `undefined` for none (missing, logged out, offline). NEVER throws. */
71
+ login(): string | undefined;
72
+ /** Whether `name` is a GitLab username. */
73
+ isLogin(name: string): boolean;
74
+ /** Whether namespace `owner` is a GitLab group, subgroups too, not a person's; `false` when glab can't say. NEVER throws. */
75
+ isOrganization(owner: string): boolean;
76
+ /** The group or user in git address `address`, subgroups included: `team/sub`; `undefined` without one. */
77
+ ownerIn(address: string): string | undefined;
78
+ /** The project path in git address `address`, `team/sub/app`; `undefined` for an address naming no host. */
79
+ repoIn(address: string): string | undefined;
80
+ /**
81
+ * The repo page `<epic-commit>` links under, for git address `address`: `https://host/team/sub/app/-`, which takes
82
+ * `/commit/<sha>`; `null` for an address naming no host.
83
+ * - the `/-` is GitLab's own: a page's `repo` attribute carries it, so the element needs no rule for GitLab
84
+ */
85
+ commitBase(address: string | null | undefined): string | null;
86
+ /**
87
+ * Whether a merge request is the only way into `branch` of project `fullName`: its protected branches, any rule
88
+ * naming `branch` (`*-stable` too), with no push level the caller reaches.
89
+ * - nobody may push (level 0), or levels above the caller's: `true`; a level by user or group it can't check: counts
90
+ * as reachable
91
+ * - `false` for anything else: no rule, no right to read it, offline, `glab` missing. NEVER throws.
92
+ */
93
+ requiresPullRequest(fullName: string, branch: string): boolean;
94
+ /**
95
+ * The merge requests of `branch` into `base` that GitLab merged: `{ number, url, head }` (`head`: its last commit),
96
+ * newest first; `[]` when `glab` can't say. NEVER throws.
97
+ */
98
+ mergedPullRequests(branch: string, base: string, _cwd: string): MergedPullRequest[];
99
+ /** The address of the merge request of `branch` into `base` that's open; none: `undefined`. NEVER throws. */
100
+ openPullRequestOf(branch: string, base: string, _cwd: string): string | undefined;
101
+ /** This repo's merge requests of `branch` into `base`, by state; `[]` when `glab` can't say. */
102
+ private requestsOf;
103
+ /**
104
+ * Open a merge request of `branch` into `base`, from checkout `cwd`: its address.
105
+ * - one open already: that one's address
106
+ * - never asks anything: `--yes`, with title and description given
107
+ * - `body` empty: the title, `glab` otherwise asking for one
108
+ * - throws an `Error` with glab's own words when it can't
109
+ * - SIDE EFFECT: a merge request on GitLab
110
+ */
111
+ openPullRequest({ branch, base, title, body, cwd }: OpenPullRequest): string;
112
+ /** The repo's own address, for `--repo`: `https://host/team/sub/app`; none without a host and path. */
113
+ private get repoAddress();
114
+ /**
115
+ * Make GitLab project `fullName` (`team/sub/name`, or `username/name`), empty: private, unless `visibility` says.
116
+ * - through the API (the class's note): `POST projects`, under the group, or the person's own namespace
117
+ * - throws an `Error` with glab's own words when it can't (a name taken, no right to make one there)
118
+ * - SIDE EFFECT: a new project on GitLab
119
+ */
120
+ createRepo(fullName: string, { visibility, description }?: {
121
+ visibility?: RepoVisibility;
122
+ description?: string;
123
+ }): void;
124
+ /**
125
+ * GitLab project `fullName`'s address for git: SSH when this repo is reached over SSH, else HTTPS, so a push goes
126
+ * the way this person's already do.
127
+ * - throws an `Error` with glab's words when glab can't find it
128
+ */
129
+ addressOf(fullName: string): string;
130
+ /**
131
+ * Let every teammate push to `branch` of project `fullName`: run once the branch exists (its first push), which is
132
+ * when GitLab protects a new project's default branch, Developers kept out.
133
+ * - a line saying what to do by hand when it couldn't (no right to, offline); `undefined` when it's done
134
+ * - NEVER throws: a project it can't open up is still a project
135
+ * - SIDE EFFECT: the rule removed from the project
136
+ */
137
+ letTeamPush(fullName: string, branch: string): string | undefined;
138
+ }