@theholocron/cli 5.0.0-alpha.43 → 5.0.0-alpha.430

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.
@@ -1,23 +1,51 @@
1
1
  import { ProviderApiError } from "@theholocron/http-client";
2
- //#region src/plugin/capabilities.ts
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: "single"
39
+ /** `workers` has exactly one provider. */
40
+ workers: "single",
41
+ /** `tunnels` has exactly one provider. */
42
+ tunnels: "single",
43
+ /** `projects` has exactly one provider. */
44
+ projects: "single",
45
+ /** `ideas` has exactly one provider. Optional: no repo has to declare it. */
46
+ ideas: "single",
47
+ /** `credentials` can have several providers, tried in order. */
48
+ credentials: "many"
21
49
  };
22
50
  /**
23
51
  * No capabilities are strictly required — repos without secrets (e.g. org
@@ -25,11 +53,34 @@ const CARDINALITY = {
25
53
  * own requirements at call time.
26
54
  */
27
55
  const REQUIRED_CAPABILITIES = [];
56
+ /**
57
+ * A provider could not finish an edit because the bot lacks a permission it should not keep. Carries what a person
58
+ * needs to give it for one run and take it away again, so `setup` can walk them through it.
59
+ */
60
+ var ElevationRequiredError = class extends Error {
61
+ elevation;
62
+ /** Lets a caller tell this error from any other by name, across package copies. */
63
+ name = "ElevationRequiredError";
64
+ constructor(message, elevation, options) {
65
+ super(message, options);
66
+ this.elevation = elevation;
67
+ }
68
+ };
69
+ /**
70
+ * A provider cannot do a read because it has no token for it. A check that meets this skips with the message instead
71
+ * of failing: the token is missing, not wrong.
72
+ */
73
+ var MissingTokenError = class extends Error {
74
+ /** Lets a caller tell this error from any other by name, across package copies. */
75
+ name = "MissingTokenError";
76
+ };
77
+ /** A webhook payload failed signature verification, so it must not be trusted. */
28
78
  var WebhookVerificationError = class extends Error {
79
+ /** Lets a caller tell this error from any other by name, across package copies. */
29
80
  name = "WebhookVerificationError";
30
81
  };
82
+ /** Whether `key` is a capability that can have several providers active at once. */
31
83
  function isMulti(key) {
32
84
  return CARDINALITY[key] === "many";
33
85
  }
34
- //#endregion
35
- export { CARDINALITY, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, isMulti };
86
+ export { CARDINALITY, ElevationRequiredError, MissingTokenError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, isMulti };
@@ -0,0 +1,221 @@
1
+ import { mr as compose, vr as Capability, yr as ComposedPreset } from "./index-BFrWaQ3Y.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.<domain>/<repo>`, the default zone from `presets/constants`) 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
+ /** A composed preset for a TypeScript library that also publishes a documentation site. */
102
+ type DocsPreset = ComposedPreset;
103
+ /** A composed preset for a documentation-only site with no TypeScript source. */
104
+ type DocsSitePreset = ComposedPreset;
105
+ /**
106
+ * Preset for theholocron repos that are TypeScript libraries AND publish a
107
+ * documentation site (e.g. configs, utils, holocron, clients).
108
+ *
109
+ * Includes the "audit / Conclusion" check in `extraRequiredChecks` so branch
110
+ * protection works for repos that add the audit workflow explicitly. The
111
+ * tasks are intentionally left repo-specific — add the ones you want as flat ids:
112
+ * tasks: [...preset.tasks, { name: "measure:bundle", required: true }, "lint:unused", ...]
113
+ *
114
+ * For docs-only sites without TypeScript source, use docsSitePreset() instead.
115
+ *
116
+ * @example
117
+ * const preset = docsPreset();
118
+ * export default defineConfig({
119
+ * ...preset,
120
+ * description: "...",
121
+ * homepage: "https://docs.theholocron.dev/my-lib/",
122
+ * repo: { ...preset.repo, name: "theholocron/my-lib", topics: ["typescript"] },
123
+ * tasks: [...preset.tasks, { name: "measure:bundle", required: true }, { name: "release", with: { "run-build": true } }, "sync-repo"],
124
+ * providers: { ...preset.providers, secrets: "github" },
125
+ * });
126
+ */
127
+ export declare function docsPreset(): DocsPreset;
128
+ /**
129
+ * Preset for theholocron repos that are documentation-only sites with no
130
+ * TypeScript source to check (e.g. skills, themes). No typecheck, no audit.
131
+ *
132
+ * @example
133
+ * const preset = docsSitePreset();
134
+ * export default defineConfig({
135
+ * ...preset,
136
+ * description: "...",
137
+ * repo: { ...preset.repo, name: "theholocron/my-site" },
138
+ * tasks: [...preset.tasks, { name: "release", with: { "run-build": false } }, "sync-repo"],
139
+ * providers: { ...preset.providers, secrets: "github" },
140
+ * });
141
+ */
142
+ export declare function docsSitePreset(): DocsSitePreset;
143
+ /**
144
+ * Wraps any composed preset with monorepo-specific overrides
145
+ * (sets uses_external_packages: true).
146
+ *
147
+ * For new configs, prefer: compose(node(), typecheck(), ..., monorepo())
148
+ *
149
+ * @example
150
+ * const preset = monorepo(nextjs());
151
+ */
152
+ export declare function monorepoPreset(base: ComposedPreset): ComposedPreset;
153
+ /**
154
+ * Preset for single-package Next.js application repos. Includes Vercel
155
+ * deployment, Lighthouse audit, Storybook + interaction + user-flow tests,
156
+ * and the derived Conclusion checks.
157
+ *
158
+ * @example
159
+ * const preset = nextjs({ test: { "wait-on-url": "http://localhost:3000", "run-chromatic": true } });
160
+ * export default defineConfig({
161
+ * ...preset,
162
+ * repo: { ...preset.repo, name: "theholocron/my-app", topics: ["nextjs"] },
163
+ * tasks: [
164
+ * ...preset.tasks,
165
+ * "sync-repo",
166
+ * { name: "deploy-docs", with: { storybook: [{ name: "" }] } },
167
+ * ],
168
+ * });
169
+ */
170
+ export declare function nextjsPreset(options?: NextjsOptions): ComposedPreset;
171
+ /**
172
+ * Base preset for theholocron Node.js repositories.
173
+ * Spread the returned fragments into `defineConfig()`.
174
+ *
175
+ * @example
176
+ * const preset = node();
177
+ * export default defineConfig({
178
+ * ...preset,
179
+ * repo: { ...preset.repo, name: "theholocron/my-lib" },
180
+ * tasks: [...preset.tasks, { name: "release", with: { "run-build": true } }],
181
+ * });
182
+ */
183
+ export declare function nodePreset(): ComposedPreset;
184
+ /**
185
+ * Preset for single-package React/Vite application repos. Includes Storybook,
186
+ * interaction tests, Knip + Lighthouse audit, and the UI extraRequiredChecks.
187
+ *
188
+ * Pass `test` overrides to merge repo-specific options (e.g. run-chromatic)
189
+ * into the single `test:unit` entry so the sync tool sees one complete entry:
190
+ *
191
+ * @example
192
+ * const preset = react({
193
+ * test: { "run-chromatic": { projects: [{ tokenName: "default", workingDir: "." }] } },
194
+ * });
195
+ * export default defineConfig({
196
+ * ...preset,
197
+ * repo: { ...preset.repo, name: "theholocron/my-app" },
198
+ * tasks: [...preset.tasks, "sync-repo", { name: "deploy-docs", with: { storybook: [{ name: "" }] } }],
199
+ * });
200
+ */
201
+ export declare function reactPreset(options?: ReactOptions): ComposedPreset;
202
+ /** The capability factories, for composing your own preset with compose(). */
203
+ export declare const withCapabilities: {
204
+ /** Bundle size auditing, with Knip and Lighthouse when asked. */
205
+ withAudit: typeof audit;
206
+ /** A documentation site deployed to Cloudflare Pages with pull request previews. */
207
+ withDocs: typeof docs;
208
+ /** Settings for a monorepo's workspaces. */
209
+ withMonorepo: typeof monorepo;
210
+ /** A Next.js application: Vercel deployment and Cypress tests on top of React. */
211
+ withNextjs: typeof nextjs;
212
+ /** The base library tasks for a Node project, without type-checking. */
213
+ withNode: typeof node;
214
+ /** Adds React and Storybook UI testing. */
215
+ withReact: typeof react;
216
+ /** Adds TypeScript type-checking. */
217
+ withTypecheck: typeof typecheck;
218
+ /** Publishes the engineering wiki. */
219
+ withWiki: typeof wiki;
220
+ };
221
+ export { type AuditOptions, type Capability, type ComposedPreset, type DocsPreset, type DocsSitePreset, type NextjsOptions, type ReactOptions, compose };