@theholocron/cli 5.0.0-alpha.32 → 5.0.0-alpha.326
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.md +412 -97
- package/dist/cli.mjs +21214 -7773
- package/dist/cli.mjs.map +1 -1
- package/dist/compose-C3tl5zsP.mjs +295 -0
- package/dist/index-BgltZujd.d.mts +812 -0
- package/dist/index-KMWrNLpJ.d.mts +2440 -0
- package/dist/index.d.mts +272 -568
- package/dist/index.mjs +533 -266
- package/dist/plugin/capabilities.d.mts +2 -807
- package/dist/plugin/capabilities.mjs +51 -4
- package/dist/presets.d.mts +223 -0
- package/dist/presets.mjs +423 -0
- package/package.json +30 -25
|
@@ -1,23 +1,47 @@
|
|
|
1
1
|
import { ProviderApiError } from "@theholocron/http-client";
|
|
2
|
-
|
|
2
|
+
// src/plugin/capabilities/capabilities.ts
|
|
3
|
+
/** How many providers each capability resolves to: one (`"single"`) or several active at once (`"many"`). */
|
|
3
4
|
const CARDINALITY = {
|
|
5
|
+
/** `source` has exactly one provider. */
|
|
4
6
|
source: "single",
|
|
7
|
+
/** `ci` has exactly one provider. */
|
|
5
8
|
ci: "single",
|
|
9
|
+
/** `secrets` has exactly one provider. */
|
|
6
10
|
secrets: "single",
|
|
11
|
+
/** `environments` has exactly one provider. */
|
|
7
12
|
environments: "single",
|
|
13
|
+
/** `issues` has exactly one provider. */
|
|
8
14
|
issues: "single",
|
|
15
|
+
/** `deployment` has exactly one provider. */
|
|
9
16
|
deployment: "single",
|
|
17
|
+
/** `storage` has exactly one provider. */
|
|
10
18
|
storage: "single",
|
|
19
|
+
/** `auth` has exactly one provider. */
|
|
11
20
|
auth: "single",
|
|
21
|
+
/** `vault` has exactly one provider. */
|
|
12
22
|
vault: "single",
|
|
23
|
+
/** `dns` has exactly one provider. */
|
|
13
24
|
dns: "single",
|
|
25
|
+
/** `tooling` can have several providers active at once. */
|
|
14
26
|
tooling: "many",
|
|
27
|
+
/** `notifications` can have several providers active at once. */
|
|
15
28
|
notifications: "many",
|
|
29
|
+
/** `analytics` can have several providers active at once. */
|
|
16
30
|
analytics: "many",
|
|
31
|
+
/** `errors` has exactly one provider. */
|
|
17
32
|
errors: "single",
|
|
33
|
+
/** `logs` has exactly one provider. */
|
|
18
34
|
logs: "single",
|
|
35
|
+
/** `monitoring` has exactly one provider. */
|
|
36
|
+
monitoring: "single",
|
|
37
|
+
/** `wiki` has exactly one provider. */
|
|
19
38
|
wiki: "single",
|
|
20
|
-
workers
|
|
39
|
+
/** `workers` has exactly one provider. */
|
|
40
|
+
workers: "single",
|
|
41
|
+
/** `tunnels` has exactly one provider. */
|
|
42
|
+
tunnels: "single",
|
|
43
|
+
/** `credentials` can have several providers, tried in order. */
|
|
44
|
+
credentials: "many"
|
|
21
45
|
};
|
|
22
46
|
/**
|
|
23
47
|
* No capabilities are strictly required — repos without secrets (e.g. org
|
|
@@ -25,11 +49,34 @@ const CARDINALITY = {
|
|
|
25
49
|
* own requirements at call time.
|
|
26
50
|
*/
|
|
27
51
|
const REQUIRED_CAPABILITIES = [];
|
|
52
|
+
/**
|
|
53
|
+
* A provider could not finish an edit because the bot lacks a permission it should not keep. Carries what a person
|
|
54
|
+
* needs to give it for one run and take it away again, so `setup` can walk them through it.
|
|
55
|
+
*/
|
|
56
|
+
var ElevationRequiredError = class extends Error {
|
|
57
|
+
elevation;
|
|
58
|
+
/** Lets a caller tell this error from any other by name, across package copies. */
|
|
59
|
+
name = "ElevationRequiredError";
|
|
60
|
+
constructor(message, elevation, options) {
|
|
61
|
+
super(message, options);
|
|
62
|
+
this.elevation = elevation;
|
|
63
|
+
}
|
|
64
|
+
};
|
|
65
|
+
/**
|
|
66
|
+
* A provider cannot do a read because it has no token for it. A check that meets this skips with the message instead
|
|
67
|
+
* of failing: the token is missing, not wrong.
|
|
68
|
+
*/
|
|
69
|
+
var MissingTokenError = class extends Error {
|
|
70
|
+
/** Lets a caller tell this error from any other by name, across package copies. */
|
|
71
|
+
name = "MissingTokenError";
|
|
72
|
+
};
|
|
73
|
+
/** A webhook payload failed signature verification, so it must not be trusted. */
|
|
28
74
|
var WebhookVerificationError = class extends Error {
|
|
75
|
+
/** Lets a caller tell this error from any other by name, across package copies. */
|
|
29
76
|
name = "WebhookVerificationError";
|
|
30
77
|
};
|
|
78
|
+
/** Whether `key` is a capability that can have several providers active at once. */
|
|
31
79
|
function isMulti(key) {
|
|
32
80
|
return CARDINALITY[key] === "many";
|
|
33
81
|
}
|
|
34
|
-
|
|
35
|
-
export { CARDINALITY, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, isMulti };
|
|
82
|
+
export { CARDINALITY, ElevationRequiredError, MissingTokenError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, isMulti };
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
import { n as Capability, r as ComposedPreset, t as compose } from "./index-BgltZujd.mjs";
|
|
2
|
+
/** Options for the audit capability. */
|
|
3
|
+
interface AuditOptions {
|
|
4
|
+
/** Enable Knip unused-export analysis (default: false). */
|
|
5
|
+
knip?: boolean;
|
|
6
|
+
/** Enable Lighthouse performance audits (default: false). */
|
|
7
|
+
performance?: boolean;
|
|
8
|
+
/** Path to the Lighthouse config file. */
|
|
9
|
+
lighthouseConfig?: string;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Adds bundle-size measuring (`measure-bundle`) + optional Knip (`lint:unused`) and
|
|
13
|
+
* Lighthouse (`test:perf`) auditing. Each task is marked `required` — `holocron setup`
|
|
14
|
+
* derives the branch-protection checks from the manifest.
|
|
15
|
+
* Requires: node
|
|
16
|
+
*/
|
|
17
|
+
declare function audit({ knip, performance, lighthouseConfig }?: AuditOptions): Capability;
|
|
18
|
+
/**
|
|
19
|
+
* Adds a documentation site deployed to Cloudflare Pages with PR previews.
|
|
20
|
+
* Sets org/domain, wires Cloudflare + DNS providers, and adds the codecov
|
|
21
|
+
* `extraRequiredChecks` (enabled for all docs repos).
|
|
22
|
+
* Requires: node
|
|
23
|
+
*/
|
|
24
|
+
declare function docs(): Capability;
|
|
25
|
+
/**
|
|
26
|
+
* Adjusts a repo to be a monorepo — sets uses_external_packages: true
|
|
27
|
+
* (workspaces pull in many deps). Compose after the base capabilities.
|
|
28
|
+
* Requires: node
|
|
29
|
+
*
|
|
30
|
+
* @example
|
|
31
|
+
* const preset = compose(node(), typecheck(), nextjs(), monorepo());
|
|
32
|
+
*/
|
|
33
|
+
declare function monorepo(): Capability;
|
|
34
|
+
/** Options for the Next.js preset. */
|
|
35
|
+
interface NextjsOptions {
|
|
36
|
+
/** Extra `with:` inputs merged into the `test:unit` task entry. */
|
|
37
|
+
test?: Record<string, unknown>;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Bundle preset for Next.js application repos. Returns a Capability[] that
|
|
41
|
+
* includes react() so callers only need compose(node(), typecheck(), nextjs()).
|
|
42
|
+
* compose() deduplicates, so adding react() explicitly is harmless.
|
|
43
|
+
*
|
|
44
|
+
* Adds: Vercel deployment and Cypress user-flow tests on top of react().
|
|
45
|
+
* Requires (via react()): node, typecheck
|
|
46
|
+
*
|
|
47
|
+
* @example
|
|
48
|
+
* const preset = compose(node(), typecheck(), nextjs({ test: { "wait-on-url": "http://localhost:3000" } }));
|
|
49
|
+
*/
|
|
50
|
+
declare function nextjs({ test: testOverrides }?: NextjsOptions): Capability[];
|
|
51
|
+
/**
|
|
52
|
+
* Base capability for all theholocron Node.js repositories.
|
|
53
|
+
* Contributes: GitHub source/CI/issues providers, strict branch protection,
|
|
54
|
+
* and the standard task set, spoken as flat task ids: the `lint` suite's leaves
|
|
55
|
+
* (`lint:code`, `lint:editorconfig`, `lint:markdown`, `lint:data`, `lint:commits`),
|
|
56
|
+
* `format`, `scan:secrets`, `test:unit`, `scan:code`, `annotate`, `mark-stale`,
|
|
57
|
+
* `greet`, `update-deps` and `label`. Does NOT include typecheck — add that separately.
|
|
58
|
+
* The gating tasks (lint leaves, `format`, `scan:secrets`, `test:unit`) are marked
|
|
59
|
+
* `required` — `holocron setup` derives their branch-protection check contexts from
|
|
60
|
+
* the manifest. A repo overrides a task by listing it again; `compose()` also lets
|
|
61
|
+
* the old dotted name (`verification.unitTests`, …) override the id it became.
|
|
62
|
+
*/
|
|
63
|
+
declare function node(): Capability;
|
|
64
|
+
/** Options for the React capability. */
|
|
65
|
+
interface ReactOptions {
|
|
66
|
+
/** Extra `with:` inputs merged into the `test:unit` task entry (e.g. run-chromatic). */
|
|
67
|
+
test?: Record<string, unknown>;
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Adds React/Storybook UI testing and browser runtime config.
|
|
71
|
+
* Contributes: secrets provider, browser runtime property, Storybook + interaction
|
|
72
|
+
* test jobs, `lint:unused` (Knip) + `test:perf` (Lighthouse), and the UI `extraRequiredChecks`.
|
|
73
|
+
* Requires: node, typecheck
|
|
74
|
+
*
|
|
75
|
+
* Pass `test` overrides to merge repo-specific options into the single `test:unit`
|
|
76
|
+
* entry so the sync tool sees one complete entry rather than two
|
|
77
|
+
* conflicting ones:
|
|
78
|
+
*
|
|
79
|
+
* @example
|
|
80
|
+
* compose(node(), typecheck(), react({ test: { "run-chromatic": { projects: [...] } } }))
|
|
81
|
+
*/
|
|
82
|
+
declare function react({ test: testOverrides }?: ReactOptions): Capability;
|
|
83
|
+
/**
|
|
84
|
+
* Adds TypeScript type-checking to a repo. Marked `required` — `holocron setup`
|
|
85
|
+
* derives the `Typecheck / Conclusion` branch-protection check from the manifest.
|
|
86
|
+
* Requires: node
|
|
87
|
+
*/
|
|
88
|
+
declare function typecheck(): Capability;
|
|
89
|
+
/**
|
|
90
|
+
* Adds the Fern engineering wiki (wiki.theholocron.dev/<repo>) to a repo.
|
|
91
|
+
* Provisions docs/wiki/{decisions,standards,specifications}/ and wires the
|
|
92
|
+
* wiki CI workflow to publish on push to main.
|
|
93
|
+
*
|
|
94
|
+
* Compose with docsPreset() for repos that have engineering content to publish:
|
|
95
|
+
*
|
|
96
|
+
* ```ts
|
|
97
|
+
* const preset = compose(docsPreset(), wiki());
|
|
98
|
+
* ```
|
|
99
|
+
*/
|
|
100
|
+
declare function wiki(): Capability;
|
|
101
|
+
/** Cloudflare account ID for the theholocron org. */
|
|
102
|
+
export declare const CLOUDFLARE_ACCOUNT_ID = "9c558af98664d13fc89b7e0a0d93d5a8";
|
|
103
|
+
/** A composed preset for a TypeScript library that also publishes a documentation site. */
|
|
104
|
+
type DocsPreset = ComposedPreset;
|
|
105
|
+
/** A composed preset for a documentation-only site with no TypeScript source. */
|
|
106
|
+
type DocsSitePreset = ComposedPreset;
|
|
107
|
+
/**
|
|
108
|
+
* Preset for theholocron repos that are TypeScript libraries AND publish a
|
|
109
|
+
* documentation site (e.g. configs, utils, holocron, clients).
|
|
110
|
+
*
|
|
111
|
+
* Includes the "audit / Conclusion" check in `extraRequiredChecks` so branch
|
|
112
|
+
* protection works for repos that add the audit workflow explicitly. The
|
|
113
|
+
* tasks are intentionally left repo-specific — add the ones you want as flat ids:
|
|
114
|
+
* tasks: [...preset.tasks, { name: "measure-bundle", required: true }, "lint:unused", ...]
|
|
115
|
+
*
|
|
116
|
+
* For docs-only sites without TypeScript source, use docsSitePreset() instead.
|
|
117
|
+
*
|
|
118
|
+
* @example
|
|
119
|
+
* const preset = docsPreset();
|
|
120
|
+
* export default defineConfig({
|
|
121
|
+
* ...preset,
|
|
122
|
+
* description: "...",
|
|
123
|
+
* homepage: "https://docs.theholocron.dev/my-lib/",
|
|
124
|
+
* repo: { ...preset.repo, name: "theholocron/my-lib", topics: ["typescript"] },
|
|
125
|
+
* tasks: [...preset.tasks, { name: "measure-bundle", required: true }, { name: "release", with: { "run-build": true } }, "sync-repo"],
|
|
126
|
+
* providers: { ...preset.providers, secrets: "github" },
|
|
127
|
+
* });
|
|
128
|
+
*/
|
|
129
|
+
export declare function docsPreset(): DocsPreset;
|
|
130
|
+
/**
|
|
131
|
+
* Preset for theholocron repos that are documentation-only sites with no
|
|
132
|
+
* TypeScript source to check (e.g. skills, themes). No typecheck, no audit.
|
|
133
|
+
*
|
|
134
|
+
* @example
|
|
135
|
+
* const preset = docsSitePreset();
|
|
136
|
+
* export default defineConfig({
|
|
137
|
+
* ...preset,
|
|
138
|
+
* description: "...",
|
|
139
|
+
* repo: { ...preset.repo, name: "theholocron/my-site" },
|
|
140
|
+
* tasks: [...preset.tasks, { name: "release", with: { "run-build": false } }, "sync-repo"],
|
|
141
|
+
* providers: { ...preset.providers, secrets: "github" },
|
|
142
|
+
* });
|
|
143
|
+
*/
|
|
144
|
+
export declare function docsSitePreset(): DocsSitePreset;
|
|
145
|
+
/**
|
|
146
|
+
* Wraps any composed preset with monorepo-specific overrides
|
|
147
|
+
* (sets uses_external_packages: true).
|
|
148
|
+
*
|
|
149
|
+
* For new configs, prefer: compose(node(), typecheck(), ..., monorepo())
|
|
150
|
+
*
|
|
151
|
+
* @example
|
|
152
|
+
* const preset = monorepo(nextjs());
|
|
153
|
+
*/
|
|
154
|
+
export declare function monorepoPreset(base: ComposedPreset): ComposedPreset;
|
|
155
|
+
/**
|
|
156
|
+
* Preset for single-package Next.js application repos. Includes Vercel
|
|
157
|
+
* deployment, Lighthouse audit, Storybook + interaction + user-flow tests,
|
|
158
|
+
* and the derived Conclusion checks.
|
|
159
|
+
*
|
|
160
|
+
* @example
|
|
161
|
+
* const preset = nextjs({ test: { "wait-on-url": "http://localhost:3000", "run-chromatic": true } });
|
|
162
|
+
* export default defineConfig({
|
|
163
|
+
* ...preset,
|
|
164
|
+
* repo: { ...preset.repo, name: "theholocron/my-app", topics: ["nextjs"] },
|
|
165
|
+
* tasks: [
|
|
166
|
+
* ...preset.tasks,
|
|
167
|
+
* "sync-repo",
|
|
168
|
+
* { name: "deploy-docs", with: { storybook: [{ name: "" }] } },
|
|
169
|
+
* ],
|
|
170
|
+
* });
|
|
171
|
+
*/
|
|
172
|
+
export declare function nextjsPreset(options?: NextjsOptions): ComposedPreset;
|
|
173
|
+
/**
|
|
174
|
+
* Base preset for theholocron Node.js repositories.
|
|
175
|
+
* Spread the returned fragments into `defineConfig()`.
|
|
176
|
+
*
|
|
177
|
+
* @example
|
|
178
|
+
* const preset = node();
|
|
179
|
+
* export default defineConfig({
|
|
180
|
+
* ...preset,
|
|
181
|
+
* repo: { ...preset.repo, name: "theholocron/my-lib" },
|
|
182
|
+
* tasks: [...preset.tasks, { name: "release", with: { "run-build": true } }],
|
|
183
|
+
* });
|
|
184
|
+
*/
|
|
185
|
+
export declare function nodePreset(): ComposedPreset;
|
|
186
|
+
/**
|
|
187
|
+
* Preset for single-package React/Vite application repos. Includes Storybook,
|
|
188
|
+
* interaction tests, Knip + Lighthouse audit, and the UI extraRequiredChecks.
|
|
189
|
+
*
|
|
190
|
+
* Pass `test` overrides to merge repo-specific options (e.g. run-chromatic)
|
|
191
|
+
* into the single `test:unit` entry so the sync tool sees one complete entry:
|
|
192
|
+
*
|
|
193
|
+
* @example
|
|
194
|
+
* const preset = react({
|
|
195
|
+
* test: { "run-chromatic": { projects: [{ tokenName: "default", workingDir: "." }] } },
|
|
196
|
+
* });
|
|
197
|
+
* export default defineConfig({
|
|
198
|
+
* ...preset,
|
|
199
|
+
* repo: { ...preset.repo, name: "theholocron/my-app" },
|
|
200
|
+
* tasks: [...preset.tasks, "sync-repo", { name: "deploy-docs", with: { storybook: [{ name: "" }] } }],
|
|
201
|
+
* });
|
|
202
|
+
*/
|
|
203
|
+
export declare function reactPreset(options?: ReactOptions): ComposedPreset;
|
|
204
|
+
/** The capability factories, for composing your own preset with compose(). */
|
|
205
|
+
export declare const withCapabilities: {
|
|
206
|
+
/** Bundle size auditing, with Knip and Lighthouse when asked. */
|
|
207
|
+
withAudit: typeof audit;
|
|
208
|
+
/** A documentation site deployed to Cloudflare Pages with pull request previews. */
|
|
209
|
+
withDocs: typeof docs;
|
|
210
|
+
/** Settings for a monorepo's workspaces. */
|
|
211
|
+
withMonorepo: typeof monorepo;
|
|
212
|
+
/** A Next.js application: Vercel deployment and Cypress tests on top of React. */
|
|
213
|
+
withNextjs: typeof nextjs;
|
|
214
|
+
/** The base library tasks for a Node project, without type-checking. */
|
|
215
|
+
withNode: typeof node;
|
|
216
|
+
/** Adds React and Storybook UI testing. */
|
|
217
|
+
withReact: typeof react;
|
|
218
|
+
/** Adds TypeScript type-checking. */
|
|
219
|
+
withTypecheck: typeof typecheck;
|
|
220
|
+
/** Publishes the engineering wiki. */
|
|
221
|
+
withWiki: typeof wiki;
|
|
222
|
+
};
|
|
223
|
+
export { type AuditOptions, type Capability, type ComposedPreset, type DocsPreset, type DocsSitePreset, type NextjsOptions, type ReactOptions, compose };
|