@theholocron/cli 5.0.0-alpha.359 → 5.0.0-alpha.360

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 CHANGED
@@ -628,6 +628,7 @@ commands and the config are provider-neutral; Discord is the first provider.
628
628
  | `holocron doctor notifications [--built-only] [--deliver] [--post]` | Step by step: does the server match the layout, do the secrets exist, and does a person (not the bot) own it. A full run also leaves one `🧪 test:` post in the layout's `testChannel`; `--built-only` posts nothing; `--deliver` posts to every channel and removes each post; `--post [channel]` posts the result as the bot (the failures, or only the summary when none failed). It also reads the Checkly feed (webhook, alert channel, subscriptions), the Comlink relay (Worker, route, bindings, the tracker's integration and rule) and the Notifications workflow (the file, and the secrets it reads), posting nothing, so `--built-only` keeps those steps. The `bot-permissions` row compares what the bot's roles hold server-wide with the permissions it needs (`ServerInspection` `botPermissions`; the owner and Administrator hold all, channel overwrites are left to the forum row) and, when some are missing, fails naming them in plain words with the invite link that asks for them again (not a credential); it is skipped, with the reason, when the roles could not be read |
629
629
  | `holocron doctor variables` | Do the Actions variables `repo.variables` declares exist, with those values (and, for the organization's, that visibility)? One row for the repository and one for the organization, each only when declared. Read-only. A `repo.variables.sync` entry adds one row that checks its names exist (no value is read or shown). An undeclared variable counts only with `prune`; a scope that cannot be read (no provider, no org token) is a skip, not a failure |
630
630
  | `holocron doctor ci` | Has the repo moved to the flat task vocabulary? One row each for the `tasks:` entries (a deprecated alias, with the id that replaces it), the generated callers (file, workflow and job name equal the task id), the `ci` aggregate's `expected` list (no id missing or stale) and where the callers point (`theholocron/.github` or holocron `ci-v1`). Read-only, no provider needed; exits 1 on a failure. The ruleset's checks are `doctor repo`'s |
631
+ | `holocron doctor github-app` | Does each GitHub App instance in `githubApps` (`{ name, manifest, environment }`) have what its manifest file (`default_permissions`, `default_events`) declares? Reads the App's id and key from the vault `environment` in memory (never printed), calls `GET /app` and `GET /app/installations` with the App's JWT. Rows per instance: `reachable`, `events` (all subscribed), `permissions` (each granted at least at the manifest's level, `read < write < admin`), `installations` (none lags the App, a pending update fails). Extras on the App are `info` in a row's detail, never a failure. A gap ends with the App's settings page (user- or organization-owned) and, for an installation, its own page. Credentials that cannot be read are a skip; an unreadable manifest or a rejected JWT fails. Read-only |
631
632
  | `holocron doctor environments` | Do the deployment environments exist? The ones `repo setup` creates (`staging`, `production`, when an `environments` provider is configured) plus every environment `repo.secrets.environments` names. One row. A missing one fails; an extra one is never a problem; no provider with some named is a skip |
632
633
  | `holocron doctor project [--post [channel]]` | Does each board `providers.projects.boards` declares exist and match its template? One row per board, status list, field, view and automation rule; the board's extras and the items `project reconcile` would fix (no status, closed but not done, open blocker but not blocked, blocked without a blocker) are `info` rows, never a failure. A template file that does not read fails, naming the file. Read-only; `--post` shares the failing rows through the `notifications` bot. |
633
634
  | `holocron doctor credentials` | Does the credentials environment exist, and does it hold every variable the configured plugins take? One row per variable and provider (`ok`, `fail` when missing, `skip` for an optional one not set), listing names only: it never reads a value, and says which spelling of the environment's name matched. |
package/dist/cli.mjs CHANGED
@@ -32,13 +32,13 @@ import { findRootSync, isWorkspaceRoot, walkFilesSync } from "@theholocron/fs-ut
32
32
  import { appManifestPage, buildAppManifest, convertAppManifest, serveAppManifest, serveHandler, superviseProcesses } from "@theholocron/dagobah";
33
33
  import { access, copyFile, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
34
34
  import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto";
35
+ import { createGitHubClient, getApp, listAppInstallations } from "@theholocron/github-client";
35
36
  import { createServer } from "node:http";
36
37
  import { runCheckAgainstUrl } from "@theholocron/kyber/checks";
37
38
  import { moveMajorTag } from "@theholocron/kyber/git";
38
39
  import { ADR_DIR, ADR_STATUSES, CLOSED_STATUSES, SPEC_DIRS, SPEC_STATUSES, WITHDRAWN_STATE, assignSpecIds, checkSpecs, classifySpecPath, discussionBody, discussionIdLine, discussionPrLine, discussionTitle, evaluateDocsPresence, isAddedDocComment, isFeat, packageOf, parseFrontmatter, parseSkipDocs, reconcileSpecStatus, specSummary, specTitle, updateFrontmatter } from "@theholocron/astromech/repo-validation";
39
40
  import { fetchLatestFromNpm, runUpgradeNode } from "@theholocron/astromech/upgrade";
40
41
  import { lintCommitMsgFile } from "@theholocron/astromech/lint";
41
- import { createGitHubClient } from "@theholocron/github-client";
42
42
  // src/plugin/capabilities/capabilities.ts
43
43
  /** How many providers each capability resolves to: one (`"single"`) or several active at once (`"many"`). */
44
44
  const CARDINALITY = {
@@ -206,6 +206,20 @@ function resolveEntry(key, raw) {
206
206
  }
207
207
  /** A DNS hostname of at least two labels: no scheme, port, path or space. */
208
208
  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])?)+$/;
209
+ /** Throws a {@link ConfigError} naming the first thing wrong with the `githubApps` list. */
210
+ function validateGitHubApps(apps) {
211
+ if (!Array.isArray(apps)) throw new ConfigError$1("`githubApps` must be a list of { name, manifest, environment }");
212
+ apps.forEach((app, idx) => {
213
+ for (const key of [
214
+ "name",
215
+ "manifest",
216
+ "environment"
217
+ ]) {
218
+ const value = app?.[key];
219
+ if (typeof value !== "string" || value.trim() === "") throw new ConfigError$1(`\`githubApps[${idx}].${key}\` must be a non-empty string`);
220
+ }
221
+ });
222
+ }
209
223
  /** Throws a {@link ConfigError} naming the first thing wrong with the `dev` block. */
210
224
  function validateDev(dev) {
211
225
  const nonEmpty = (value) => typeof value === "string" && value.trim() !== "";
@@ -261,6 +275,7 @@ function resolveConfig(raw) {
261
275
  if (typeof environment !== "string" || environment.trim() === "") throw new ConfigError$1("`credentials.environment` must be the name of an environment, got an empty value");
262
276
  }
263
277
  if (raw.dev !== void 0) validateDev(raw.dev);
278
+ if (raw.githubApps !== void 0) validateGitHubApps(raw.githubApps);
264
279
  validateVariablesSync(raw.repo?.variables);
265
280
  const credentialsEntry = providers.credentials;
266
281
  if (credentialsEntry?.cardinality === "many") for (const tuple of credentialsEntry.tuples) {
@@ -291,6 +306,7 @@ function resolveConfig(raw) {
291
306
  env: raw.env,
292
307
  credentials: raw.credentials,
293
308
  dev: raw.dev,
309
+ githubApps: raw.githubApps,
294
310
  log: raw.log,
295
311
  telemetry: raw.telemetry,
296
312
  eslint: raw.eslint
@@ -716,6 +732,7 @@ const COMMAND_CONTEXTS = {
716
732
  "doctor environments": "workspace",
717
733
  "doctor credentials": "workspace",
718
734
  "doctor project": "workspace",
735
+ "doctor github-app": "workspace",
719
736
  "project move": "workspace",
720
737
  "doctor dns": "workspace",
721
738
  "doctor repo": "workspace",
@@ -1449,12 +1466,12 @@ async function runDoctorTokens(input) {
1449
1466
  try {
1450
1467
  module = await importer(pkg);
1451
1468
  } catch (err) {
1452
- rows.push(row$6(pkg, "skip", `cannot load the plugin: ${errorMessage(err)}`));
1469
+ rows.push(row$8(pkg, "skip", `cannot load the plugin: ${errorMessage(err)}`));
1453
1470
  continue;
1454
1471
  }
1455
1472
  for (const token of module.tokens ?? []) rows.push(await checkToken(token, module, env, readToken, now()));
1456
1473
  }
1457
- if (rows.length === 0) rows.push(row$6("tokens", "skip", "no configured plugin lists the tokens it takes"));
1474
+ if (rows.length === 0) rows.push(row$8("tokens", "skip", "no configured plugin lists the tokens it takes"));
1458
1475
  printCheckRows(rows, print);
1459
1476
  const summary = summariseChecks(rows);
1460
1477
  printCheckSummary(summary, print);
@@ -1475,7 +1492,7 @@ function configuredPackages(input) {
1475
1492
  const packages = Object.values(input.loaded.resolved.providers).flatMap((entry) => entry.cardinality === "single" ? [entry.tuple.packageName] : entry.tuples.map((t) => t.packageName));
1476
1493
  return [...new Set(packages)];
1477
1494
  }
1478
- function row$6(id, status, detail) {
1495
+ function row$8(id, status, detail) {
1479
1496
  return {
1480
1497
  id,
1481
1498
  title: id,
@@ -1488,20 +1505,20 @@ async function checkToken(token, module, env, readToken, now) {
1488
1505
  const { keyringKey, envName, vendorEnvName } = token;
1489
1506
  const fromEnv = env.get(envName) ? envName : vendorEnvName && env.get(vendorEnvName) ? vendorEnvName : void 0;
1490
1507
  const value = fromEnv ? env.get(fromEnv) : readToken(keyringKey);
1491
- if (!value) return row$6(keyringKey, "skip", `not set (${vendorEnvName ? `${envName} / ${vendorEnvName}` : envName}, or \`holocron auth set ${keyringKey}\`)`);
1492
- if (!module.verifyToken || token.verifiable === false) return row$6(keyringKey, "skip", "set, but its plugin cannot verify it");
1508
+ if (!value) return row$8(keyringKey, "skip", `not set (${vendorEnvName ? `${envName} / ${vendorEnvName}` : envName}, or \`holocron auth set ${keyringKey}\`)`);
1509
+ if (!module.verifyToken || token.verifiable === false) return row$8(keyringKey, "skip", "set, but its plugin cannot verify it");
1493
1510
  const from = fromEnv ?? "keyring";
1494
1511
  try {
1495
1512
  const verified = await module.verifyToken(value);
1496
- if (!verified.ok) return row$6(keyringKey, "fail", `rejected (${from}): ${verified.message}`);
1513
+ if (!verified.ok) return row$8(keyringKey, "fail", `rejected (${from}): ${verified.message}`);
1497
1514
  const expiry = verified.expiresAt ? describeExpiry(verified.expiresAt, now) : void 0;
1498
- if (!expiry) return row$6(keyringKey, "ok", `${verified.subject} (${from})`);
1515
+ if (!expiry) return row$8(keyringKey, "ok", `${verified.subject} (${from})`);
1499
1516
  return expiry.soon ? {
1500
- ...row$6(keyringKey, "fail", `${verified.subject} (${from}), ${expiry.text}`),
1517
+ ...row$8(keyringKey, "fail", `${verified.subject} (${from}), ${expiry.text}`),
1501
1518
  problems: [`${expiry.text}: renew it`]
1502
- } : row$6(keyringKey, "ok", `${verified.subject} (${from}), ${expiry.text}`);
1519
+ } : row$8(keyringKey, "ok", `${verified.subject} (${from}), ${expiry.text}`);
1503
1520
  } catch (err) {
1504
- return row$6(keyringKey, "fail", `could not be verified (${from}): ${errorMessage(err)}`);
1521
+ return row$8(keyringKey, "fail", `could not be verified (${from}): ${errorMessage(err)}`);
1505
1522
  }
1506
1523
  }
1507
1524
  // src/commands/doctor-tokens/doctor-tokens.command.ts
@@ -1964,6 +1981,13 @@ const doctorEnvironmentsEntry = {
1964
1981
  positionals: [],
1965
1982
  supportsDryRun: false
1966
1983
  };
1984
+ // src/commands/doctor-github-app/doctor-github-app.entry.ts
1985
+ const doctorGitHubAppEntry = {
1986
+ name: "doctor github-app",
1987
+ description: "Compare each registered GitHub App's events, permissions and installations with its manifest (read-only)",
1988
+ positionals: [],
1989
+ supportsDryRun: false
1990
+ };
1967
1991
  // src/commands/doctor-monitoring/doctor-monitoring.entry.ts
1968
1992
  const doctorMonitoringEntry = {
1969
1993
  name: "doctor monitoring",
@@ -2357,6 +2381,7 @@ const registry = createCommandRegistry([
2357
2381
  doctorEnvironmentsEntry,
2358
2382
  doctorCredentialsEntry,
2359
2383
  doctorProjectEntry,
2384
+ doctorGitHubAppEntry,
2360
2385
  projectMoveEntry,
2361
2386
  doctorDnsEntry,
2362
2387
  doctorRepoEntry,
@@ -4580,7 +4605,7 @@ async function runDoctorCredentials(input) {
4580
4605
  };
4581
4606
  }
4582
4607
  /** A row for the provider as a whole, or for one of its variables when `name` is given. */
4583
- function row$5(provider, status, detail, name) {
4608
+ function row$7(provider, status, detail, name) {
4584
4609
  return name === void 0 ? {
4585
4610
  id: provider,
4586
4611
  title: provider,
@@ -4597,32 +4622,32 @@ function row$5(provider, status, detail, name) {
4597
4622
  }
4598
4623
  async function checkCredentials(input, loader) {
4599
4624
  const { resolved } = input.loaded;
4600
- if (!resolved.providers.credentials) return [row$5("credentials", "skip", "no `credentials` provider is configured")];
4601
- const rows = loader.loadFailures().filter((f) => f.key === "credentials").map((f) => row$5(f.provider, "fail", `failed to load: ${errorMessage(f.error)}`));
4625
+ if (!resolved.providers.credentials) return [row$7("credentials", "skip", "no `credentials` provider is configured")];
4626
+ const rows = loader.loadFailures().filter((f) => f.key === "credentials").map((f) => row$7(f.provider, "fail", `failed to load: ${errorMessage(f.error)}`));
4602
4627
  if (!loader.has("credentials")) return rows;
4603
4628
  const expected = await expectedTokens(input);
4604
4629
  const { tuples } = resolved.providers.credentials;
4605
4630
  for (const impl of loader.get("credentials")) {
4606
4631
  const tuple = tuples.find((t) => t.provider === impl.providerName);
4607
4632
  const environment = tuple && credentialsEnvironment(tuple, resolved);
4608
- rows.push(...environment ? await checkProvider(impl, environment, expected) : [row$5(impl.providerName, "skip", "no `environment` option and `credentials.environment` is not set")]);
4633
+ rows.push(...environment ? await checkProvider(impl, environment, expected) : [row$7(impl.providerName, "skip", "no `environment` option and `credentials.environment` is not set")]);
4609
4634
  }
4610
4635
  return rows;
4611
4636
  }
4612
4637
  async function checkProvider(impl, environment, expected) {
4613
4638
  const provider = impl.providerName;
4614
- if (!impl.inspect) return [row$5(provider, "skip", "cannot list the variables without reading their values")];
4615
- if (expected.length === 0) return [row$5(provider, "skip", "no configured plugin lists the tokens it takes")];
4639
+ if (!impl.inspect) return [row$7(provider, "skip", "cannot list the variables without reading their values")];
4640
+ if (expected.length === 0) return [row$7(provider, "skip", "no configured plugin lists the tokens it takes")];
4616
4641
  try {
4617
4642
  const found = await impl.inspect(environment);
4618
4643
  const held = new Set(found.names);
4619
4644
  const where = found.environment === environment ? `"${found.environment}"` : `"${found.environment}" (the config writes "${environment}")`;
4620
4645
  return expected.map(({ name, optional }) => {
4621
- if (held.has(name)) return row$5(provider, "ok", `present in ${where}`, name);
4622
- return optional ? row$5(provider, "skip", `optional, not set in ${where}`, name) : row$5(provider, "fail", `missing from ${where}`, name);
4646
+ if (held.has(name)) return row$7(provider, "ok", `present in ${where}`, name);
4647
+ return optional ? row$7(provider, "skip", `optional, not set in ${where}`, name) : row$7(provider, "fail", `missing from ${where}`, name);
4623
4648
  });
4624
4649
  } catch (err) {
4625
- return [row$5(provider, "fail", errorMessage(err))];
4650
+ return [row$7(provider, "fail", errorMessage(err))];
4626
4651
  }
4627
4652
  }
4628
4653
  /**
@@ -5453,7 +5478,7 @@ async function runDoctorDns(input) {
5453
5478
  });
5454
5479
  else if (!loader.has("dns")) {
5455
5480
  const why = whyMissing(loader, "dns", "no `dns` provider to check them with");
5456
- for (const zone of zones) rows.push(row$4(zone, "skip", why));
5481
+ for (const zone of zones) rows.push(row$6(zone, "skip", why));
5457
5482
  for (const { hostname } of domains) rows.push(domainRow(hostname, "skip", why));
5458
5483
  } else {
5459
5484
  const dns = loader.get("dns");
@@ -5475,7 +5500,7 @@ async function runDoctorDns(input) {
5475
5500
  ...status === "skip" ? { reason: [...new Set(rows.map((r) => r.detail))].join("; ") } : {}
5476
5501
  };
5477
5502
  }
5478
- function row$4(zone, status, detail, problems = []) {
5503
+ function row$6(zone, status, detail, problems = []) {
5479
5504
  return {
5480
5505
  id: `dns-${zone}`,
5481
5506
  title: `${zone} records exist`,
@@ -5504,7 +5529,7 @@ async function checkDomain(dns, deploy, project, hostname) {
5504
5529
  return noToken !== void 0 ? domainRow(hostname, "skip", noToken) : domainRow(hostname, "fail", errorMessage(err));
5505
5530
  }
5506
5531
  }
5507
- async function checkZone(dns, zone, wanted, rowOf = (...args) => row$4(zone, ...args)) {
5532
+ async function checkZone(dns, zone, wanted, rowOf = (...args) => row$6(zone, ...args)) {
5508
5533
  try {
5509
5534
  const have = await dns.listRecords(zone);
5510
5535
  const problems = declaredVsActual(new Map(wanted.map((w) => [keyOf(w), w])), new Map(have.map((h) => [keyOf(h), h])), {
@@ -5614,6 +5639,201 @@ const doctorEnvironmentsCommand = {
5614
5639
  })).status === "fail") process.exitCode = 1;
5615
5640
  }
5616
5641
  };
5642
+ // src/commands/doctor-github-app/permission-gaps.ts
5643
+ const LEVELS$1 = [
5644
+ "read",
5645
+ "write",
5646
+ "admin"
5647
+ ];
5648
+ /** The permissions in `want` that `have` lacks or holds at a lower level (`read < write < admin`), one line each. */
5649
+ function permissionGaps(want, have) {
5650
+ return Object.entries(want).flatMap(([name, level]) => {
5651
+ const held = have[name];
5652
+ if (held === void 0) return [`missing permission ${name} (${level})`];
5653
+ return LEVELS$1.indexOf(held) < LEVELS$1.indexOf(level) ? [`permission ${name} is ${held}, wants ${level}`] : [];
5654
+ });
5655
+ }
5656
+ // src/commands/doctor-github-app/settings-urls.ts
5657
+ /** The App's permissions page (its events are on the same page, under "Subscribe to events"), by who owns it. */
5658
+ function appSettingsUrl(app) {
5659
+ return app.owner?.type === "Organization" ? `https://github.com/organizations/${app.owner.login}/settings/apps/${app.slug}/permissions` : `https://github.com/settings/apps/${app.slug}/permissions`;
5660
+ }
5661
+ /** The page where an account accepts an App's new permissions: its installation. */
5662
+ function installationSettingsUrl(account, id) {
5663
+ if (account?.type === "Organization") return `https://github.com/organizations/${account.login}/settings/installations/${id}`;
5664
+ return `https://github.com/settings/installations/${id}`;
5665
+ }
5666
+ // src/commands/doctor-github-app/app-rows.ts
5667
+ const row$5 = (name, what, problems, ok) => ({
5668
+ id: `${name}:${what}`,
5669
+ title: `${name}: ${what}`,
5670
+ status: problems.length > 0 ? "fail" : "ok",
5671
+ detail: problems.length > 0 ? `${problems.length} problem(s)` : ok,
5672
+ problems
5673
+ });
5674
+ /** Extras are information only: they never fail a row, they are named in its detail. */
5675
+ const extrasNote = (noun, extras) => extras.length > 0 ? `; info: ${extras.length} ${noun} not in the manifest (${extras.join(", ")})` : "";
5676
+ /**
5677
+ * The events, permissions and installations rows of one App instance: the manifest against the live App, and the live
5678
+ * App against what each installation has accepted. A row that fails ends with the page that fixes it.
5679
+ */
5680
+ function appRows(name, manifest, app, installations) {
5681
+ const fix = `fix: ${appSettingsUrl(app)} (events are on the same page, under "Subscribe to events")`;
5682
+ const eventProblems = manifest.events.filter((e) => !app.events.includes(e)).map((e) => `missing event ${e}`);
5683
+ const extraEvents = app.events.filter((e) => !manifest.events.includes(e));
5684
+ const permissionProblems = permissionGaps(manifest.permissions, app.permissions);
5685
+ const extraPermissions = Object.keys(app.permissions).filter((p) => !(p in manifest.permissions));
5686
+ const installationProblems = installations.flatMap((installation) => {
5687
+ const gaps = [...permissionGaps(app.permissions, installation.permissions), ...app.events.filter((e) => !installation.events.includes(e)).map((e) => `missing event ${e}`)];
5688
+ if (gaps.length === 0) return [];
5689
+ const who = installation.account?.login ?? `installation ${installation.id}`;
5690
+ const url = installationSettingsUrl(installation.account, installation.id);
5691
+ return [`${who} has not accepted the current App: ${gaps.join("; ")}`, `fix: ${who} accepts the update at ${url}`];
5692
+ });
5693
+ return [
5694
+ row$5(name, "events", eventProblems.length > 0 ? [...eventProblems, fix] : [], `all ${manifest.events.length} subscribed${extrasNote("extra event(s)", extraEvents)}`),
5695
+ row$5(name, "permissions", permissionProblems.length > 0 ? [...permissionProblems, fix] : [], `all ${Object.keys(manifest.permissions).length} granted${extrasNote("extra permission(s)", extraPermissions)}`),
5696
+ row$5(name, "installations", installationProblems, `${installations.length} installation(s) up to date`)
5697
+ ];
5698
+ }
5699
+ // src/commands/doctor-github-app/parse-manifest.ts
5700
+ const LEVELS = [
5701
+ "read",
5702
+ "write",
5703
+ "admin"
5704
+ ];
5705
+ /** Reads the permissions and events out of an App manifest's text; throws an `Error` saying what is wrong with it. */
5706
+ function parseManifest(text) {
5707
+ const raw = JSON.parse(text);
5708
+ const permissions = raw.default_permissions;
5709
+ if (typeof permissions !== "object" || permissions === null || Array.isArray(permissions)) throw new Error("`default_permissions` must be an object of permission name to read, write or admin");
5710
+ for (const [name, level] of Object.entries(permissions)) if (typeof level !== "string" || !LEVELS.includes(level)) throw new Error(`\`default_permissions.${name}\` must be read, write or admin, got ${JSON.stringify(level)}`);
5711
+ const events = raw.default_events ?? [];
5712
+ if (!Array.isArray(events) || !events.every((e) => typeof e === "string")) throw new Error("`default_events` must be a list of event names");
5713
+ return {
5714
+ permissions,
5715
+ events
5716
+ };
5717
+ }
5718
+ // src/commands/doctor-github-app/doctor-github-app.ts
5719
+ /**
5720
+ * `holocron doctor github-app` — does each registered GitHub App instance have what its manifest declares?
5721
+ *
5722
+ * GitHub has no API that changes an existing App's permissions or event subscriptions, so each instance is changed by
5723
+ * hand in its settings page and a missed one fails quietly. Read-only: for every entry of `githubApps` it reads the
5724
+ * manifest file, reads the instance's `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` from its vault environment in
5725
+ * memory (never printed, never written), signs the App's own JWT and calls `GET /app` and `GET /app/installations`.
5726
+ * Rows per instance: reachable; events (every manifest event is subscribed); permissions (each manifest permission is
5727
+ * granted at least at its level, `read < write < admin`); installations (none lags the App, which is a pending
5728
+ * update an owner has not accepted). Extras on the App are named in a row's detail as `info`, never a failure. A row
5729
+ * that fails ends with the settings page that fixes it. An instance whose credentials cannot be read is a skip with
5730
+ * the reason; an unreadable manifest, a rejected JWT or a gap is a failure.
5731
+ */
5732
+ const APP_ID = "GITHUB_APP_ID";
5733
+ const PRIVATE_KEY = "GITHUB_APP_PRIVATE_KEY";
5734
+ const defaultApi = {
5735
+ getApp,
5736
+ listAppInstallations
5737
+ };
5738
+ async function runDoctorGitHubApp(input) {
5739
+ const print = input.print ?? ((line) => console.log(line));
5740
+ const logger = input.logger ?? getLogger();
5741
+ const instances = input.loaded.resolved.githubApps ?? [];
5742
+ const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
5743
+ if (instances.length > 0) {
5744
+ await loader.load();
5745
+ assertPluginsResolvable$1(loader, "doctor github-app");
5746
+ }
5747
+ const rows = [];
5748
+ if (instances.length === 0) rows.push(row$4("github-app", "reachable", "skip", "no `githubApps` are declared in holocron.config.ts"));
5749
+ for (const instance of instances) rows.push(...await checkInstance(instance, loader, input));
5750
+ printCheckRows(rows, print);
5751
+ const summary = summariseChecks(rows);
5752
+ printCheckSummary(summary, print);
5753
+ const status = summary.fail > 0 ? "fail" : summary.ok === 0 ? "skip" : "ok";
5754
+ logger.info({
5755
+ ...summary,
5756
+ status
5757
+ }, "doctor github-app");
5758
+ return {
5759
+ status,
5760
+ rows,
5761
+ summary,
5762
+ ...status === "skip" ? { reason: [...new Set(rows.map((r) => r.detail))].join("; ") } : {}
5763
+ };
5764
+ }
5765
+ function row$4(name, what, status, detail) {
5766
+ return {
5767
+ id: `${name}:${what}`,
5768
+ title: `${name}: ${what}`,
5769
+ status,
5770
+ detail,
5771
+ problems: []
5772
+ };
5773
+ }
5774
+ /** An error's message with the secrets it was handed taken out, so nothing read from the vault is ever printed. */
5775
+ function scrubbed(err, secrets) {
5776
+ return secrets.filter(Boolean).reduce((text, secret) => text.split(secret).join("[redacted]"), errorMessage(err));
5777
+ }
5778
+ /** The App's id and key from its vault environment, or the reason they cannot be had. */
5779
+ async function readCredentials(instance, loader) {
5780
+ const vault = loader.has("vault") ? loader.get("vault") : void 0;
5781
+ if (!vault?.readEnvironment) return { reason: vault ? `${vault.providerName} cannot read an environment's variables` : "needs a `vault` provider in holocron.config.ts (1password)" };
5782
+ let values;
5783
+ try {
5784
+ values = await vault.readEnvironment(instance.environment);
5785
+ } catch (err) {
5786
+ return { reason: `cannot read the "${instance.environment}" environment: ${errorMessage(err)}` };
5787
+ }
5788
+ const missing = [APP_ID, PRIVATE_KEY].filter((key) => !values[key]?.trim());
5789
+ if (missing.length > 0) return { reason: `"${instance.environment}" does not hold ${missing.join(" or ")}` };
5790
+ const privateKey = values[PRIVATE_KEY].includes("\n") ? values[PRIVATE_KEY] : values[PRIVATE_KEY].replace(/\\n/g, "\n");
5791
+ return { creds: {
5792
+ appId: values[APP_ID].trim(),
5793
+ privateKey
5794
+ } };
5795
+ }
5796
+ async function checkInstance(instance, loader, input) {
5797
+ const { name } = instance;
5798
+ const readManifest = input.readManifest ?? ((path) => readFileSync(join(input.context.repoRoot, path), "utf8"));
5799
+ let manifest;
5800
+ try {
5801
+ manifest = parseManifest(readManifest(instance.manifest));
5802
+ } catch (err) {
5803
+ return [row$4(name, "manifest", "fail", `cannot read ${instance.manifest}: ${errorMessage(err)}`)];
5804
+ }
5805
+ const read = await readCredentials(instance, loader);
5806
+ if ("reason" in read) return [row$4(name, "reachable", "skip", read.reason)];
5807
+ const api = input.api ?? defaultApi;
5808
+ const secrets = [read.creds.privateKey];
5809
+ try {
5810
+ const app = await api.getApp(read.creds);
5811
+ const installations = await api.listAppInstallations(read.creds);
5812
+ const owner = app.owner ? `, owned by ${app.owner.login}` : "";
5813
+ return [row$4(name, "reachable", "ok", `${app.slug}${owner}, settings: ${appSettingsUrl(app)}`), ...appRows(name, manifest, app, installations)];
5814
+ } catch (err) {
5815
+ return [row$4(name, "reachable", "fail", `cannot call GitHub as the App: ${scrubbed(err, secrets)}`)];
5816
+ }
5817
+ }
5818
+ // src/commands/doctor-github-app/doctor-github-app.command.ts
5819
+ const doctorGitHubAppCommand = {
5820
+ command: "github-app",
5821
+ describe: "Compare each registered GitHub App's events, permissions and installations with its manifest (read-only)",
5822
+ handler: async (argv) => {
5823
+ const tokens = tokenContext$1(argv.token);
5824
+ if (!tokens) return;
5825
+ const loaded = await loadConfig(argv.cwd);
5826
+ applyResolvedConfig(argv, loaded.resolved);
5827
+ if ((await runDoctorGitHubApp({
5828
+ loaded,
5829
+ context: {
5830
+ repoRoot: argv.cwd,
5831
+ ...tokens,
5832
+ org: resolveOrg(argv, loaded.resolved)
5833
+ }
5834
+ })).status === "fail") process.exitCode = 1;
5835
+ }
5836
+ };
5617
5837
  // src/commands/doctor-monitoring/doctor-monitoring.ts
5618
5838
  /**
5619
5839
  * `holocron doctor monitoring` — do the checks the `monitoring` provider declares exist in its account, as declared?
@@ -10113,6 +10333,19 @@ const DEEP_CHECKS = [
10113
10333
  };
10114
10334
  }
10115
10335
  },
10336
+ {
10337
+ name: "github-app",
10338
+ capability: "vault",
10339
+ command: doctorGitHubAppCommand,
10340
+ async run(input) {
10341
+ const report = await runDoctorGitHubApp(input);
10342
+ return {
10343
+ status: report.status,
10344
+ summary: report.summary,
10345
+ ...report.reason ? { reason: report.reason } : {}
10346
+ };
10347
+ }
10348
+ },
10116
10349
  {
10117
10350
  name: "project",
10118
10351
  capability: "projects",