@theholocron/cli 5.0.0-alpha.34 → 5.0.0-alpha.340

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.
@@ -0,0 +1,302 @@
1
+ import { CARDINALITY, REQUIRED_CAPABILITIES } from "./plugin/capabilities.mjs";
2
+ import { resolveTaskName } from "@theholocron/astromech";
3
+ // src/config/config/config.ts
4
+ /** Thrown when a `holocron.config` is invalid. */
5
+ var ConfigError = class extends Error {
6
+ /** The error's name, `"ConfigError"`. */
7
+ name = "ConfigError";
8
+ };
9
+ const PLUGIN_PREFIX = "@theholocron/holocron-plugin-";
10
+ const COMMUNITY_PREFIX = "holocron-plugin-";
11
+ /**
12
+ * Resolve `"github"` → `"@theholocron/holocron-plugin-github"`.
13
+ * Fully-qualified names (scoped or not) are honored verbatim, which
14
+ * is how third-party plugins published outside the org work.
15
+ */
16
+ function resolvePluginPackage(provider) {
17
+ if (!provider) throw new ConfigError("provider name is empty");
18
+ if (provider.startsWith("@")) return provider;
19
+ if (provider.startsWith(COMMUNITY_PREFIX)) return provider;
20
+ if (provider.includes("/")) return provider;
21
+ return PLUGIN_PREFIX + provider;
22
+ }
23
+ /** A bare `[provider, options]` tuple, with both elements present? */
24
+ function isOptionsTuple(value) {
25
+ if (!Array.isArray(value)) return false;
26
+ if (value.length !== 2) return false;
27
+ if (typeof value[0] !== "string") return false;
28
+ const opt = value[1];
29
+ return typeof opt === "object" && opt !== null && !Array.isArray(opt);
30
+ }
31
+ function normalizeEntry(entry) {
32
+ if (typeof entry === "string") return {
33
+ provider: entry,
34
+ packageName: resolvePluginPackage(entry),
35
+ options: {}
36
+ };
37
+ const [provider, options] = entry;
38
+ return {
39
+ provider,
40
+ packageName: resolvePluginPackage(provider),
41
+ options
42
+ };
43
+ }
44
+ /** Resolves one capability's raw provider entry into single or multiple resolved tuples, checking it against the capability's cardinality. */
45
+ function resolveEntry(key, raw) {
46
+ const cardinality = CARDINALITY[key];
47
+ if (typeof raw === "string") {
48
+ if (cardinality === "many") throw new ConfigError(`\`${key}\` accepts multiple providers; wrap a single one in an array: ["${raw}"]`);
49
+ return {
50
+ cardinality: "single",
51
+ tuple: normalizeEntry(raw)
52
+ };
53
+ }
54
+ if (!Array.isArray(raw)) throw new ConfigError(`\`${key}\` entry must be a string or array, got ${typeof raw}`);
55
+ if (isOptionsTuple(raw)) {
56
+ if (cardinality === "many") return {
57
+ cardinality: "many",
58
+ tuples: [normalizeEntry(raw)]
59
+ };
60
+ return {
61
+ cardinality: "single",
62
+ tuple: normalizeEntry(raw)
63
+ };
64
+ }
65
+ if (cardinality === "single") throw new ConfigError(`\`${key}\` accepts exactly one provider; got a multi-provider list with ${raw.length} entries`);
66
+ return {
67
+ cardinality: "many",
68
+ tuples: raw.map((entry, idx) => {
69
+ if (typeof entry === "string") return normalizeEntry(entry);
70
+ if (isOptionsTuple(entry)) return normalizeEntry(entry);
71
+ throw new ConfigError(`\`${key}[${idx}]\` must be a provider string or [provider, options] tuple`);
72
+ })
73
+ };
74
+ }
75
+ /** A DNS hostname of at least two labels: no scheme, port, path or space. */
76
+ const HOSTNAME = /^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)+$/;
77
+ /** Throws a {@link ConfigError} naming the first thing wrong with the `dev` block. */
78
+ function validateDev(dev) {
79
+ const nonEmpty = (value) => typeof value === "string" && value.trim() !== "";
80
+ if (dev.environment !== void 0 && !nonEmpty(dev.environment)) throw new ConfigError("`dev.environment` must be the name of a vault environment, got an empty value");
81
+ if (dev.tunnel !== void 0) {
82
+ if (!nonEmpty(dev.tunnel.name)) throw new ConfigError("`dev.tunnel.name` must be a name, got an empty value");
83
+ if (typeof dev.tunnel.hostname !== "string" || !HOSTNAME.test(dev.tunnel.hostname)) throw new ConfigError(`\`dev.tunnel.hostname\` must be a hostname such as sentinel-dev.example.dev (no scheme or path), got ${JSON.stringify(dev.tunnel.hostname)}`);
84
+ }
85
+ if (dev.port !== void 0 && !(Number.isInteger(dev.port) && dev.port >= 1 && dev.port <= 65535)) throw new ConfigError(`\`dev.port\` must be a port from 1 to 65535, got ${JSON.stringify(dev.port)}`);
86
+ if (dev.command !== void 0 && !(Array.isArray(dev.command) && dev.command.length > 0 && dev.command.every(nonEmpty))) throw new ConfigError("`dev.command` must be the program and its arguments, e.g. [\"pnpm\", \"run\", \"serve\"]");
87
+ if (dev.serve !== void 0) {
88
+ const { serve } = dev;
89
+ if (!nonEmpty(serve.handler)) throw new ConfigError("`dev.serve.handler` must be the path of the module that exports the handler");
90
+ if (serve.export !== void 0 && !nonEmpty(serve.export)) throw new ConfigError("`dev.serve.export` must be the name of the handler's export, got an empty value");
91
+ if (serve.required !== void 0 && !(Array.isArray(serve.required) && serve.required.every(nonEmpty))) throw new ConfigError("`dev.serve.required` must be a list of variable names");
92
+ if (serve.logging !== void 0 && !(nonEmpty(serve.logging.tokenVar) && nonEmpty(serve.logging.datasetVar))) throw new ConfigError("`dev.serve.logging` needs a `tokenVar` and a `datasetVar`, both variable names");
93
+ }
94
+ }
95
+ /** The values `repoValidation.docsCoverage` accepts. */
96
+ const DOCS_COVERAGE_MODES = [
97
+ "off",
98
+ "warn",
99
+ "required"
100
+ ];
101
+ /**
102
+ * The environment a `credentials` provider reads: its own `environment` option when it has one, else the shared
103
+ * `credentials.environment`, else `undefined`. The option lets each of several providers name its own (a 1Password
104
+ * Environment and an AWS secret are not called the same thing) without the plugin storing the name.
105
+ */
106
+ function credentialsEnvironment(tuple, config) {
107
+ const own = tuple.options.environment;
108
+ return typeof own === "string" && own.trim() !== "" ? own : config.credentials?.environment;
109
+ }
110
+ /** Validates a raw `holocron.config` and resolves its provider entries; throws `ConfigError` when `name` or `providers` is missing or an entry is malformed. */
111
+ function resolveConfig(raw) {
112
+ if (!raw.name) throw new ConfigError("`name` is required");
113
+ if (!raw.providers || typeof raw.providers !== "object") throw new ConfigError("`providers` block is required");
114
+ const providers = {};
115
+ for (const [key, entry] of Object.entries(raw.providers)) {
116
+ if (entry === void 0) continue;
117
+ providers[key] = resolveEntry(key, entry);
118
+ }
119
+ for (const required of REQUIRED_CAPABILITIES) if (!providers[required]) throw new ConfigError(`required capability \`${required}\` is missing from providers`);
120
+ let docs;
121
+ if (raw.docs !== void 0) {
122
+ if (!raw.docs.build) throw new ConfigError("`docs.build` is required when `docs` is set");
123
+ docs = raw.docs;
124
+ }
125
+ const docsCoverage = raw.repoValidation?.docsCoverage;
126
+ if (docsCoverage !== void 0 && !DOCS_COVERAGE_MODES.includes(docsCoverage)) throw new ConfigError(`\`repoValidation.docsCoverage\` must be one of ${DOCS_COVERAGE_MODES.map((m) => `"${m}"`).join(", ")}, got ${JSON.stringify(docsCoverage)}`);
127
+ if (raw.credentials !== void 0) {
128
+ const environment = raw.credentials.environment;
129
+ if (typeof environment !== "string" || environment.trim() === "") throw new ConfigError("`credentials.environment` must be the name of an environment, got an empty value");
130
+ }
131
+ if (raw.dev !== void 0) validateDev(raw.dev);
132
+ const credentialsEntry = providers.credentials;
133
+ if (credentialsEntry?.cardinality === "many") for (const tuple of credentialsEntry.tuples) {
134
+ const own = tuple.options.environment;
135
+ if (own !== void 0 && (typeof own !== "string" || own.trim() === "")) throw new ConfigError(`the \`environment\` option of the \`${tuple.provider}\` credentials provider must be the name of an environment, got an empty value`);
136
+ if (credentialsEnvironment(tuple, raw) === void 0) throw new ConfigError(`the \`${tuple.provider}\` credentials provider has no environment to read: give it an \`environment\` option or set \`credentials.environment\``);
137
+ }
138
+ const homepage = raw.homepage ?? (docs?.domain ? `https://${docs.domain}/` : void 0);
139
+ return {
140
+ name: raw.name,
141
+ description: raw.description,
142
+ homepage,
143
+ org: raw.org,
144
+ domain: raw.domain,
145
+ repo: raw.repo,
146
+ repoValidation: raw.repoValidation,
147
+ tasks: raw.tasks,
148
+ syncScripts: raw.syncScripts,
149
+ holocronScript: raw.holocronScript,
150
+ extraRequiredChecks: raw.extraRequiredChecks,
151
+ hooks: raw.hooks,
152
+ providers,
153
+ apps: raw.apps ?? [],
154
+ doctor: raw.doctor ?? {},
155
+ agent: raw.agent,
156
+ skills: raw.skills,
157
+ docs,
158
+ env: raw.env,
159
+ credentials: raw.credentials,
160
+ dev: raw.dev,
161
+ log: raw.log,
162
+ telemetry: raw.telemetry,
163
+ eslint: raw.eslint
164
+ };
165
+ }
166
+ // src/config/compose/compose.ts
167
+ /**
168
+ * The key a task entry merges under. A name that stands for exactly one flat id (the id itself, or an old dotted
169
+ * alias such as `verification.unitTests`) keys by that id, so the alias overrides the preset's entry instead of
170
+ * sitting next to it; a name that stands for several ids or none (a suite, an unknown name) keys by itself.
171
+ */
172
+ function taskName(e) {
173
+ const name = typeof e === "string" ? e : e.name;
174
+ const resolved = resolveTaskName(name);
175
+ return resolved.length === 1 ? resolved[0].id : name;
176
+ }
177
+ /**
178
+ * Merge two lists of `repo.secrets.sync` entries. An entry is the same sync when its environment and scope match;
179
+ * the keys then add up, and an entry that names no keys (every key the vault holds) stays that way.
180
+ */
181
+ function mergeSync(a, b) {
182
+ const merged = /* @__PURE__ */ new Map();
183
+ for (const entry of [...a ?? [], ...b ?? []]) {
184
+ const id = `${entry.environment}\0${entry.scope ?? "repo"}`;
185
+ const have = merged.get(id);
186
+ merged.set(id, have ? {
187
+ ...have,
188
+ ...have.keys && entry.keys ? { keys: [.../* @__PURE__ */ new Set([...have.keys, ...entry.keys])] } : { keys: void 0 }
189
+ } : { ...entry });
190
+ }
191
+ return [...merged.values()].map(({ keys, ...rest }) => keys ? {
192
+ ...rest,
193
+ keys
194
+ } : rest);
195
+ }
196
+ /**
197
+ * Merge any number of capability fragments into a single preset object that
198
+ * spreads directly into `defineConfig()`.
199
+ *
200
+ * - Accepts individual capabilities or nested arrays (for bundle presets).
201
+ * - Deduplicates by `id` — when the same ID appears more than once, the last
202
+ * occurrence wins. This lets callers override bundle defaults by listing an
203
+ * explicit capability after the bundle.
204
+ * - Validates all `requires` at call time and throws `ConfigError` if any are
205
+ * unmet, listing every missing dependency in a single message.
206
+ *
207
+ * @example
208
+ * // docs-only site — no typecheck
209
+ * const preset = compose(node(), docs());
210
+ *
211
+ * // library with docs
212
+ * const preset = compose(node(), typecheck(), docs());
213
+ *
214
+ * // nextjs() is a bundle that returns Capability[]
215
+ * const preset = compose(node(), nextjs());
216
+ */
217
+ function compose(...args) {
218
+ const flat = args.flat();
219
+ const byId = /* @__PURE__ */ new Map();
220
+ for (const cap of flat) byId.set(cap.id, cap);
221
+ const caps = [...byId.values()];
222
+ const available = new Set(caps.map((c) => c.id));
223
+ const errors = [];
224
+ for (const cap of caps) for (const req of cap.requires ?? []) if (!available.has(req)) errors.push(`"${cap.id}" requires "${req}"`);
225
+ if (errors.length > 0) throw new ConfigError(`compose(): unmet dependencies — ${errors.join(", ")}`);
226
+ const taskMap = /* @__PURE__ */ new Map();
227
+ for (const cap of caps) for (const entry of cap.tasks ?? []) taskMap.set(taskName(entry), entry);
228
+ let providers = {};
229
+ for (const cap of caps) if (cap.providers) providers = {
230
+ ...providers,
231
+ ...cap.providers
232
+ };
233
+ const checksSeen = /* @__PURE__ */ new Set();
234
+ const extraRequiredChecks = [];
235
+ for (const cap of caps) for (const check of cap.extraRequiredChecks ?? []) if (!checksSeen.has(check)) {
236
+ checksSeen.add(check);
237
+ extraRequiredChecks.push(check);
238
+ }
239
+ let repo = {};
240
+ for (const cap of caps) {
241
+ if (!cap.repo) continue;
242
+ const { properties, topics, teams, variables, secrets, ...scalars } = cap.repo;
243
+ repo = {
244
+ ...repo,
245
+ ...scalars
246
+ };
247
+ if (properties) repo.properties = {
248
+ ...repo.properties,
249
+ ...properties
250
+ };
251
+ if (variables) repo.variables = {
252
+ ...repo.variables,
253
+ ...variables,
254
+ ...repo.variables?.repo || variables.repo ? { repo: {
255
+ ...repo.variables?.repo,
256
+ ...variables.repo
257
+ } } : {},
258
+ ...repo.variables?.org || variables.org ? { org: {
259
+ ...repo.variables?.org,
260
+ ...variables.org
261
+ } } : {}
262
+ };
263
+ if (secrets) {
264
+ const union = (a, b) => [.../* @__PURE__ */ new Set([...a ?? [], ...b ?? []])];
265
+ const environments = { ...repo.secrets?.environments };
266
+ for (const [env, names] of Object.entries(secrets.environments ?? {})) environments[env] = union(environments[env], names);
267
+ repo.secrets = {
268
+ ...repo.secrets?.repo || secrets.repo ? { repo: union(repo.secrets?.repo, secrets.repo) } : {},
269
+ ...repo.secrets?.org || secrets.org ? { org: union(repo.secrets?.org, secrets.org) } : {},
270
+ ...Object.keys(environments).length > 0 ? { environments } : {},
271
+ ...repo.secrets?.sync || secrets.sync ? { sync: mergeSync(repo.secrets?.sync, secrets.sync) } : {}
272
+ };
273
+ }
274
+ if (topics) {
275
+ const merged = /* @__PURE__ */ new Set([...repo.topics ?? [], ...topics]);
276
+ repo.topics = [...merged];
277
+ }
278
+ if (teams) {
279
+ const teamMap = new Map((repo.teams ?? []).map((t) => [typeof t === "string" ? t : t.slug, t]));
280
+ for (const t of teams) teamMap.set(typeof t === "string" ? t : t.slug, t);
281
+ repo.teams = [...teamMap.values()];
282
+ }
283
+ }
284
+ let org;
285
+ let domain;
286
+ let docs;
287
+ for (const cap of caps) {
288
+ if (cap.org !== void 0) org = cap.org;
289
+ if (cap.domain !== void 0) domain = cap.domain;
290
+ if (cap.docs !== void 0) docs = cap.docs;
291
+ }
292
+ return {
293
+ tasks: [...taskMap.values()],
294
+ providers,
295
+ repo,
296
+ extraRequiredChecks,
297
+ ...org !== void 0 ? { org } : {},
298
+ ...domain !== void 0 ? { domain } : {},
299
+ ...docs !== void 0 ? { docs } : {}
300
+ };
301
+ }
302
+ export { resolveEntry as a, resolveConfig as i, ConfigError as n, resolvePluginPackage as o, credentialsEnvironment as r, compose as t };