@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 +1 -0
- package/dist/cli.mjs +256 -23
- package/dist/cli.mjs.map +1 -1
- package/dist/{config-system-DPQQeBH_.d.mts → config-system-BkIbjZQi.d.mts} +26 -1
- package/dist/{config-system-CkpFGTap.mjs → config-system-xLN8TV6N.mjs} +16 -0
- package/dist/index.d.mts +2 -2
- package/dist/index.mjs +1 -1
- package/dist/presets.d.mts +1 -1
- package/dist/presets.mjs +1 -1
- package/package.json +11 -11
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$
|
|
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$
|
|
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$
|
|
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$
|
|
1492
|
-
if (!module.verifyToken || token.verifiable === false) return row$
|
|
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$
|
|
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$
|
|
1515
|
+
if (!expiry) return row$8(keyringKey, "ok", `${verified.subject} (${from})`);
|
|
1499
1516
|
return expiry.soon ? {
|
|
1500
|
-
...row$
|
|
1517
|
+
...row$8(keyringKey, "fail", `${verified.subject} (${from}), ${expiry.text}`),
|
|
1501
1518
|
problems: [`${expiry.text}: renew it`]
|
|
1502
|
-
} : row$
|
|
1519
|
+
} : row$8(keyringKey, "ok", `${verified.subject} (${from}), ${expiry.text}`);
|
|
1503
1520
|
} catch (err) {
|
|
1504
|
-
return row$
|
|
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$
|
|
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$
|
|
4601
|
-
const rows = loader.loadFailures().filter((f) => f.key === "credentials").map((f) => row$
|
|
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$
|
|
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$
|
|
4615
|
-
if (expected.length === 0) return [row$
|
|
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$
|
|
4622
|
-
return optional ? row$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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",
|