@theholocron/cli 5.0.0-alpha.27 → 5.0.0-alpha.270

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/dist/index.mjs CHANGED
@@ -1,14 +1,18 @@
1
- import { CARDINALITY, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, isMulti } from "./plugin/capabilities.mjs";
1
+ import { CARDINALITY, ElevationRequiredError, MissingTokenError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, isMulti } from "./plugin/capabilities.mjs";
2
+ import { a as resolvePluginPackage, i as resolveEntry, n as ConfigError, r as resolveConfig, t as compose } from "./compose-CDyegVKe.mjs";
2
3
  import { AuthError, createResolveToken as createResolveToken$1, createRestClient } from "@theholocron/http-client";
3
- import { createEnvLookup } from "@theholocron/env-utils";
4
+ import { createEnvLookup, withEnvPrefix } from "@theholocron/env-utils";
4
5
  import { Entry, findCredentials } from "@napi-rs/keyring";
5
- import { readFile } from "node:fs/promises";
6
6
  import { basename, dirname, join } from "node:path";
7
- import { execFile } from "node:child_process";
8
- import { promisify } from "node:util";
7
+ import { readPackageJson } from "@theholocron/pkg-utils";
9
8
  import { loadTasksConfig } from "@theholocron/astromech/config";
10
9
  import { ConfigFileError, ConfigFileError as ConfigFileError$1, loadConfigFile } from "@theholocron/datapad";
11
- createEnvLookup();
10
+ import { readGitRemote } from "@theholocron/git-utils";
11
+ import { lookup } from "node:dns/promises";
12
+ // src/env/env.ts
13
+ /** Singleton env for simple global lookups throughout the CLI. */
14
+ const env = createEnvLookup();
15
+ withEnvPrefix(env, "HOLOCRON");
12
16
  /**
13
17
  * Create an injectable env for commands that accept a fake env in tests.
14
18
  * Pass `input.env` when available, falls back to `process.env`.
@@ -16,8 +20,7 @@ createEnvLookup();
16
20
  function makeEnv(source) {
17
21
  return createEnvLookup(source);
18
22
  }
19
- //#endregion
20
- //#region src/auth/keyring.ts
23
+ // src/auth/keyring/keyring.ts
21
24
  /**
22
25
  * Keyring-backed bootstrap credential store.
23
26
  *
@@ -86,8 +89,7 @@ function listStoredProviders() {
86
89
  return [];
87
90
  }
88
91
  }
89
- //#endregion
90
- //#region src/auth/auth-resolver.ts
92
+ // src/auth/auth-resolver/auth-resolver.ts
91
93
  /** Wraps `createResolveToken` from `@theholocron/http` and injects the
92
94
  * system keyring so plugins stay at a one-liner call site. */
93
95
  function createResolveToken(config) {
@@ -104,16 +106,19 @@ function createResolveToken(config) {
104
106
  * operation fails with a message naming the exact env var to set.
105
107
  */
106
108
  function createFeatureResolver(config) {
107
- return function resolveFeatureToken(input = {}) {
109
+ const resolveFeatureToken = (input = {}) => {
108
110
  const env = makeEnv(input.env);
109
111
  const keyring = input.keyring ?? getToken;
110
112
  const token = input.cliToken || env.get(config.envName) || keyring(config.keyringKey);
111
- if (!token) throw new AuthError(`no GitHub token found for this operation. Pass --token <PAT>, set ${config.envName}, or run: holocron auth set ${config.keyringKey} <PAT>`);
113
+ if (!token) throw new AuthError(`no ${config.vendor ?? "GitHub"} token found for this operation. Pass --token <token>, set ${config.envName}, or run: holocron auth set ${config.keyringKey} <token>`);
112
114
  return token;
113
115
  };
116
+ return Object.assign(resolveFeatureToken, { token: {
117
+ envName: config.envName,
118
+ keyringKey: config.keyringKey
119
+ } });
114
120
  }
115
- //#endregion
116
- //#region src/commands/setup/derived-properties.ts
121
+ // src/commands/setup/derived-properties/derived-properties.ts
117
122
  /**
118
123
  * Repo archetype, in priority order:
119
124
  * 1. `*-template` repo name → `template` (independent of package shape).
@@ -184,7 +189,7 @@ function deriveCapabilities(providers) {
184
189
  return Object.keys(providers ?? {}).sort();
185
190
  }
186
191
  /**
187
- * `source` + `ci` are the minimal baseline every repo `holocron setup`
192
+ * `source` + `ci` are the minimal baseline every repo `holocron repo setup`
188
193
  * touches wires — every `holocron.config.ts` in this org already satisfies
189
194
  * this, so `non-compliant` here means drift (a provider manually removed
190
195
  * after setup), not an unmet aspirational policy. Deliberately not a richer
@@ -213,215 +218,17 @@ function missingCapabilities(capabilities) {
213
218
  */
214
219
  async function readWorkspacePackageJsons(repoRoot, workspacePackages) {
215
220
  const results = [];
216
- for (const { slug, dir = "packages" } of workspacePackages) try {
217
- const raw = await readFile(join(repoRoot, dir, slug, "package.json"), "utf8");
218
- results.push(JSON.parse(raw));
219
- } catch {}
220
- return results;
221
- }
222
- //#endregion
223
- //#region src/config/config.ts
224
- var ConfigError = class extends Error {
225
- name = "ConfigError";
226
- };
227
- const PLUGIN_PREFIX = "@theholocron/holocron-plugin-";
228
- const COMMUNITY_PREFIX = "holocron-plugin-";
229
- /**
230
- * Resolve `"github"` → `"@theholocron/holocron-plugin-github"`.
231
- * Fully-qualified names (scoped or not) are honored verbatim, which
232
- * is how third-party plugins published outside the org work.
233
- */
234
- function resolvePluginPackage(provider) {
235
- if (!provider) throw new ConfigError("provider name is empty");
236
- if (provider.startsWith("@")) return provider;
237
- if (provider.startsWith(COMMUNITY_PREFIX)) return provider;
238
- if (provider.includes("/")) return provider;
239
- return PLUGIN_PREFIX + provider;
240
- }
241
- /** A bare `[provider, options]` tuple, with both elements present? */
242
- function isOptionsTuple(value) {
243
- if (!Array.isArray(value)) return false;
244
- if (value.length !== 2) return false;
245
- if (typeof value[0] !== "string") return false;
246
- const opt = value[1];
247
- return typeof opt === "object" && opt !== null && !Array.isArray(opt);
248
- }
249
- function normalizeEntry(entry) {
250
- if (typeof entry === "string") return {
251
- provider: entry,
252
- packageName: resolvePluginPackage(entry),
253
- options: {}
254
- };
255
- const [provider, options] = entry;
256
- return {
257
- provider,
258
- packageName: resolvePluginPackage(provider),
259
- options
260
- };
261
- }
262
- function resolveEntry(key, raw) {
263
- const cardinality = CARDINALITY[key];
264
- if (typeof raw === "string") {
265
- if (cardinality === "many") throw new ConfigError(`\`${key}\` accepts multiple providers; wrap a single one in an array: ["${raw}"]`);
266
- return {
267
- cardinality: "single",
268
- tuple: normalizeEntry(raw)
269
- };
270
- }
271
- if (!Array.isArray(raw)) throw new ConfigError(`\`${key}\` entry must be a string or array, got ${typeof raw}`);
272
- if (isOptionsTuple(raw)) {
273
- if (cardinality === "many") return {
274
- cardinality: "many",
275
- tuples: [normalizeEntry(raw)]
276
- };
277
- return {
278
- cardinality: "single",
279
- tuple: normalizeEntry(raw)
280
- };
221
+ for (const { slug, dir = "packages", path } of workspacePackages) {
222
+ const pkg = await readPackageJson(join(repoRoot, path ?? join(dir, slug)));
223
+ if (pkg) results.push(pkg);
281
224
  }
282
- if (cardinality === "single") throw new ConfigError(`\`${key}\` accepts exactly one provider; got a multi-provider list with ${raw.length} entries`);
283
- return {
284
- cardinality: "many",
285
- tuples: raw.map((entry, idx) => {
286
- if (typeof entry === "string") return normalizeEntry(entry);
287
- if (isOptionsTuple(entry)) return normalizeEntry(entry);
288
- throw new ConfigError(`\`${key}[${idx}]\` must be a provider string or [provider, options] tuple`);
289
- })
290
- };
291
- }
292
- function resolveConfig(raw) {
293
- if (!raw.name) throw new ConfigError("`name` is required");
294
- if (!raw.providers || typeof raw.providers !== "object") throw new ConfigError("`providers` block is required");
295
- const providers = {};
296
- for (const [key, entry] of Object.entries(raw.providers)) {
297
- if (entry === void 0) continue;
298
- providers[key] = resolveEntry(key, entry);
299
- }
300
- for (const required of REQUIRED_CAPABILITIES) if (!providers[required]) throw new ConfigError(`required capability \`${required}\` is missing from providers`);
301
- let docs;
302
- if (raw.docs !== void 0) {
303
- if (!raw.docs.build) throw new ConfigError("`docs.build` is required when `docs` is set");
304
- docs = raw.docs;
305
- }
306
- const homepage = raw.homepage ?? (docs?.domain ? `https://${docs.domain}/` : void 0);
307
- return {
308
- name: raw.name,
309
- description: raw.description,
310
- homepage,
311
- org: raw.org,
312
- domain: raw.domain,
313
- repo: raw.repo,
314
- tasks: raw.tasks,
315
- syncScripts: raw.syncScripts,
316
- holocronScript: raw.holocronScript,
317
- extraRequiredChecks: raw.extraRequiredChecks,
318
- hooks: raw.hooks,
319
- providers,
320
- apps: raw.apps ?? [],
321
- doctor: raw.doctor ?? {},
322
- agent: raw.agent,
323
- skills: raw.skills,
324
- docs,
325
- env: raw.env,
326
- log: raw.log,
327
- telemetry: raw.telemetry
328
- };
329
- }
330
- //#endregion
331
- //#region src/config/compose.ts
332
- function taskName(e) {
333
- return typeof e === "string" ? e : e.name;
334
- }
335
- /**
336
- * Merge any number of capability fragments into a single preset object that
337
- * spreads directly into `defineConfig()`.
338
- *
339
- * - Accepts individual capabilities or nested arrays (for bundle presets).
340
- * - Deduplicates by `id` — when the same ID appears more than once, the last
341
- * occurrence wins. This lets callers override bundle defaults by listing an
342
- * explicit capability after the bundle.
343
- * - Validates all `requires` at call time and throws `ConfigError` if any are
344
- * unmet, listing every missing dependency in a single message.
345
- *
346
- * @example
347
- * // docs-only site — no typecheck
348
- * const preset = compose(node(), docs());
349
- *
350
- * // library with docs
351
- * const preset = compose(node(), typecheck(), docs());
352
- *
353
- * // nextjs() is a bundle that returns Capability[]
354
- * const preset = compose(node(), nextjs());
355
- */
356
- function compose(...args) {
357
- const flat = args.flat();
358
- const byId = /* @__PURE__ */ new Map();
359
- for (const cap of flat) byId.set(cap.id, cap);
360
- const caps = [...byId.values()];
361
- const available = new Set(caps.map((c) => c.id));
362
- const errors = [];
363
- for (const cap of caps) for (const req of cap.requires ?? []) if (!available.has(req)) errors.push(`"${cap.id}" requires "${req}"`);
364
- if (errors.length > 0) throw new ConfigError(`compose(): unmet dependencies — ${errors.join(", ")}`);
365
- const taskMap = /* @__PURE__ */ new Map();
366
- for (const cap of caps) for (const entry of cap.tasks ?? []) taskMap.set(taskName(entry), entry);
367
- let providers = {};
368
- for (const cap of caps) if (cap.providers) providers = {
369
- ...providers,
370
- ...cap.providers
371
- };
372
- const checksSeen = /* @__PURE__ */ new Set();
373
- const extraRequiredChecks = [];
374
- for (const cap of caps) for (const check of cap.extraRequiredChecks ?? []) if (!checksSeen.has(check)) {
375
- checksSeen.add(check);
376
- extraRequiredChecks.push(check);
377
- }
378
- let repo = {};
379
- for (const cap of caps) {
380
- if (!cap.repo) continue;
381
- const { properties, topics, teams, ...scalars } = cap.repo;
382
- repo = {
383
- ...repo,
384
- ...scalars
385
- };
386
- if (properties) repo.properties = {
387
- ...repo.properties,
388
- ...properties
389
- };
390
- if (topics) {
391
- const merged = /* @__PURE__ */ new Set([...repo.topics ?? [], ...topics]);
392
- repo.topics = [...merged];
393
- }
394
- if (teams) {
395
- const teamMap = new Map((repo.teams ?? []).map((t) => [typeof t === "string" ? t : t.slug, t]));
396
- for (const t of teams) teamMap.set(typeof t === "string" ? t : t.slug, t);
397
- repo.teams = [...teamMap.values()];
398
- }
399
- }
400
- let org;
401
- let domain;
402
- let docs;
403
- for (const cap of caps) {
404
- if (cap.org !== void 0) org = cap.org;
405
- if (cap.domain !== void 0) domain = cap.domain;
406
- if (cap.docs !== void 0) docs = cap.docs;
407
- }
408
- return {
409
- tasks: [...taskMap.values()],
410
- providers,
411
- repo,
412
- extraRequiredChecks,
413
- ...org !== void 0 ? { org } : {},
414
- ...domain !== void 0 ? { domain } : {},
415
- ...docs !== void 0 ? { docs } : {}
416
- };
225
+ return results;
417
226
  }
418
- //#endregion
419
- //#region src/config/define-config.ts
227
+ // src/config/define-config/define-config.ts
420
228
  function defineConfig(config) {
421
229
  return config;
422
230
  }
423
- //#endregion
424
- //#region src/config/load-config.ts
231
+ // src/config/load-config/load-config.ts
425
232
  /**
426
233
  * `holocron.config.{ts,js,mjs,cjs,json}` loader.
427
234
  *
@@ -433,34 +240,40 @@ function defineConfig(config) {
433
240
  * Probe order is TS-first (`.ts` → `.js` → `.mjs` → `.cjs` → `.json`) —
434
241
  * see ADR-0010 / issue #75 / #81.
435
242
  */
436
- const execFileAsync = promisify(execFile);
437
243
  /**
438
- * Read + parse + resolve `holocron.config.*` from the given directory.
244
+ * Read + parse + resolve `holocron.config.*` starting from the given
245
+ * directory, walking up through ancestors to the nearest `.git` boundary
246
+ * when `cwd` itself has no match — every command is usable from any
247
+ * subdirectory of a repo, not only its exact root (see
248
+ * `@theholocron/datapad`'s own doc comment for the stop conditions).
439
249
  * Throws {@link ConfigFileError} when nothing is found or a file cannot
440
- * be loaded, or `ConfigError` when the config is invalid.
250
+ * be loaded, or `ConfigError` when the config fails schema checks.
441
251
  */
442
252
  async function loadConfig(cwd) {
443
253
  const found = await loadConfigFile({
444
254
  cwd,
445
- name: "holocron"
255
+ name: "holocron",
256
+ walkUp: true
446
257
  });
447
258
  if (!found) throw new ConfigFileError$1(`no holocron.config.{ts,js,mjs,cjs,json} found in ${cwd}. Create one — see the README for the schema.`);
259
+ const withDefaults = await deriveDefaults(found);
448
260
  return {
449
- resolved: resolveConfig(await deriveDefaults(dirname(found.filepath), found.config)),
261
+ resolved: resolveConfig(withDefaults),
450
262
  filepath: found.filepath
451
263
  };
452
264
  }
453
- async function deriveDefaults(configDir, raw) {
454
- const result = { ...raw };
265
+ async function deriveDefaults(found) {
266
+ const configDir = dirname(found.filepath);
267
+ const result = { ...found.config };
455
268
  if (!result.name) result.name = await readPackageJsonName(configDir) ?? basename(configDir);
456
269
  if (result.repo && !result.repo.name) {
457
- const repoName = await readGitRemote(configDir);
458
- if (repoName) result.repo = {
270
+ const remote = await readGitRemote(configDir);
271
+ if (remote?.host === "github.com") result.repo = {
459
272
  ...result.repo,
460
- name: repoName
273
+ name: remote.slug
461
274
  };
462
275
  }
463
- const manifest = await loadTasksConfig(configDir);
276
+ const manifest = await loadTasksConfig(configDir, { holocron: found });
464
277
  if (manifest.tasks) result.tasks = manifest.tasks;
465
278
  if (manifest.syncScripts !== void 0) result.syncScripts = manifest.syncScripts;
466
279
  if (manifest.holocronScript !== void 0) result.holocronScript = manifest.holocronScript;
@@ -469,31 +282,144 @@ async function deriveDefaults(configDir, raw) {
469
282
  return result;
470
283
  }
471
284
  async function readPackageJsonName(dir) {
472
- try {
473
- const content = await readFile(join(dir, "package.json"), "utf8");
474
- const pkg = JSON.parse(content);
475
- return typeof pkg.name === "string" ? pkg.name.replace(/^@[^/]+\//, "") : void 0;
476
- } catch {
477
- return;
285
+ const name = (await readPackageJson(dir))?.name;
286
+ return name === void 0 ? void 0 : name.replace(/^@[^/]+\//, "");
287
+ }
288
+ // src/plugin/connection-probe/connection-probe.ts
289
+ const TLS_CODES = /* @__PURE__ */ new Set([
290
+ "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
291
+ "SELF_SIGNED_CERT_IN_CHAIN",
292
+ "DEPTH_ZERO_SELF_SIGNED_CERT",
293
+ "CERT_HAS_EXPIRED",
294
+ "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
295
+ "ERR_TLS_CERT_ALTNAME_INVALID"
296
+ ]);
297
+ /** The code Node attaches to a network failure, with that error's message: on the error itself, or on its `cause` (where `fetch` puts it). */
298
+ function codeOf(err) {
299
+ for (let e = err, depth = 0; e && depth < 4; depth++) {
300
+ if (typeof e.code === "string") return {
301
+ code: e.code,
302
+ message: String(e.message ?? "")
303
+ };
304
+ e = e.cause;
478
305
  }
479
306
  }
480
- async function readGitRemote(dir) {
481
- try {
482
- const { stdout } = await execFileAsync("git", [
483
- "remote",
484
- "get-url",
485
- "origin"
486
- ], { cwd: dir });
487
- return parseGitRemoteUrl(stdout.trim());
488
- } catch {
489
- return;
307
+ /** A network failure in plain words, with what usually causes it. Never includes anything from a request. */
308
+ function describeNetworkError(err, timeoutMs) {
309
+ const found = codeOf(err);
310
+ const code = found?.code;
311
+ const name = err?.name;
312
+ if (name === "TimeoutError" || name === "AbortError" || code === "UND_ERR_CONNECT_TIMEOUT" || code === "ETIMEDOUT") return `no answer within ${timeoutMs / 1e3}s (${code ?? name}): a firewall, VPN or proxy may be dropping it`;
313
+ switch (code) {
314
+ case "ENOTFOUND":
315
+ case "EAI_AGAIN": return `${code}: the name did not resolve; check your network and DNS`;
316
+ case "ECONNREFUSED": return "ECONNREFUSED: the host refused the connection";
317
+ case "ECONNRESET":
318
+ case "UND_ERR_SOCKET": return `${code}: the connection was cut off; a proxy or firewall may be interfering`;
319
+ case "ENETUNREACH":
320
+ case "EHOSTUNREACH": return `${code}: no route to the host; check that you are online`;
321
+ default:
322
+ if (code && TLS_CODES.has(code)) return `${code}: the TLS certificate was not trusted; a corporate proxy that re-signs traffic needs NODE_EXTRA_CA_CERTS`;
323
+ return found ? `${found.code}: ${found.message}` : String(err?.message ?? err);
490
324
  }
491
325
  }
492
- function parseGitRemoteUrl(url) {
493
- const httpsMatch = url.match(/github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/);
494
- if (httpsMatch) return httpsMatch[1];
495
- const sshMatch = url.match(/github\.com:([^/]+\/[^/]+?)(?:\.git)?$/);
496
- if (sshMatch) return sshMatch[1];
326
+ /**
327
+ * The `connection` probe every provider offers, for telling a network problem from a credential problem: does the name
328
+ * resolve, does the host answer, is there a token, and does the provider accept it. A step that cannot work because an
329
+ * earlier one failed is reported as not tried rather than failing a second time for the same reason.
330
+ */
331
+ function connectionProbe(input) {
332
+ const timeoutMs = input.timeoutMs ?? 1e4;
333
+ return {
334
+ summary: `Check the network path to ${input.provider} and that it accepts your token.`,
335
+ writes: false,
336
+ async run(probe) {
337
+ let reachable = true;
338
+ if (input.url) {
339
+ const host = new URL(input.url).hostname;
340
+ const lookup$1 = input.lookup ?? (input.fetch ? void 0 : (h) => lookup(h));
341
+ if (lookup$1) try {
342
+ const { address } = await lookup$1(host);
343
+ probe.say({
344
+ status: "ok",
345
+ label: `DNS ${host}`,
346
+ detail: address
347
+ });
348
+ } catch (err) {
349
+ reachable = false;
350
+ probe.say({
351
+ status: "fail",
352
+ label: `DNS ${host}`,
353
+ detail: describeNetworkError(err, timeoutMs)
354
+ });
355
+ }
356
+ if (reachable) {
357
+ const started = Date.now();
358
+ try {
359
+ const res = await (input.fetch ?? fetch)(input.url, {
360
+ method: "GET",
361
+ signal: AbortSignal.timeout(timeoutMs)
362
+ });
363
+ probe.say({
364
+ status: "ok",
365
+ label: `reach ${host}`,
366
+ detail: `HTTP ${res.status} in ${Date.now() - started} ms`
367
+ });
368
+ } catch (err) {
369
+ reachable = false;
370
+ probe.say({
371
+ status: "fail",
372
+ label: `reach ${host}`,
373
+ detail: describeNetworkError(err, timeoutMs)
374
+ });
375
+ }
376
+ } else probe.say({
377
+ status: "info",
378
+ label: `reach ${host}`,
379
+ detail: "not tried: the name did not resolve"
380
+ });
381
+ }
382
+ let token;
383
+ try {
384
+ token = await input.token();
385
+ } catch (err) {
386
+ probe.say({
387
+ status: "fail",
388
+ label: "token",
389
+ detail: err.message
390
+ });
391
+ probe.say({
392
+ status: "info",
393
+ label: "accepted",
394
+ detail: "not tried: there is no token"
395
+ });
396
+ return;
397
+ }
398
+ probe.secret(token);
399
+ probe.say({
400
+ status: "ok",
401
+ label: "token",
402
+ detail: "found"
403
+ });
404
+ if (!reachable) {
405
+ probe.say({
406
+ status: "info",
407
+ label: "accepted",
408
+ detail: "not tried: the host could not be reached"
409
+ });
410
+ return;
411
+ }
412
+ const result = await input.verify(token);
413
+ probe.say(result.ok ? {
414
+ status: "ok",
415
+ label: "accepted",
416
+ detail: result.subject
417
+ } : {
418
+ status: "fail",
419
+ label: "accepted",
420
+ detail: result.message
421
+ });
422
+ }
423
+ };
497
424
  }
498
- //#endregion
499
- export { AuthError, CARDINALITY, ConfigError, ConfigFileError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
425
+ export { AuthError, CARDINALITY, ConfigError, ConfigFileError, ElevationRequiredError, MissingTokenError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, compose, connectionProbe, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, describeNetworkError, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };