@theholocron/cli 5.0.0-alpha.227 → 5.0.0-alpha.229

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
@@ -547,6 +547,7 @@ commands and the config are provider-neutral; Discord is the first provider.
547
547
  | `holocron notifications link` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept) |
548
548
  | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
549
549
  | `holocron doctor notifications [--built-only] [--deliver]` | 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 |
550
+ | `holocron probe [<provider> [<probe>]] [--dry-run] [--yes]` | Poke a live provider on purpose: list the probes, inspect something, or run a proof that cleans up after itself. Plugins offer the probes; nothing secret is printed; one that changes things asks first |
550
551
 
551
552
  Channels fed by another service are declared with `feeds` on the channel: `{ name: "uptime", webhook: true, feeds: { monitoring: true } }` (the object form `{ name?, webhook?, avatar? }` overrides the alert channel's name, default `Message to #<channel>`, the dedicated webhook's name, default the provider's, and gives that webhook a picture, a file path or `https://` URL, or `{ url, image }` (the URL is tried first, the file in the repo is the fallback), else the provider's own icon (`Monitoring.icon`, a URL and an embedded `data:` image; Checkly provides one), else the layout's `webhookAvatar`, else the layout's `webhookAvatar`). `setup` gives the channel a dedicated webhook and hands its URL straight to the `monitoring` provider through `Monitoring.ensureAlertChannel({ name, format: "discord", url? })`, which finds an alert channel of that name or creates one and subscribes every check; the URL is never stored as a secret. It needs a `monitoring` provider that implements `ensureAlertChannel` (Checkly does). Two feeds may not share an alert channel name, and a feed's webhook may not share the channel's own webhook name (compared without regard to case).
552
553
 
package/dist/cli.mjs CHANGED
@@ -426,6 +426,7 @@ const COMMAND_CONTEXTS = {
426
426
  "notifications create-server": "workspace",
427
427
  "notifications sync-roles": "workspace",
428
428
  "doctor notifications": "workspace",
429
+ probe: "workspace",
429
430
  deploy: "workspace",
430
431
  "deploy cleanup-preview": "workspace",
431
432
  "monitoring check": "workspace",
@@ -1217,6 +1218,8 @@ var PluginLoader = class {
1217
1218
  importer;
1218
1219
  registry = /* @__PURE__ */ new Map();
1219
1220
  failures = [];
1221
+ /** The probes of each provider that was imported, by provider name (`sentry`). */
1222
+ probeSets = /* @__PURE__ */ new Map();
1220
1223
  constructor(config, context, importer = defaultImporter$1) {
1221
1224
  this.config = config;
1222
1225
  this.context = context;
@@ -1284,6 +1287,10 @@ var PluginLoader = class {
1284
1287
  return this.registry.has(key);
1285
1288
  }
1286
1289
  /** All capability keys currently loaded. Useful for the doctor command. */
1290
+ /** The probes each loaded provider offers, by provider name. Empty for a provider that offers none. */
1291
+ probes() {
1292
+ return this.probeSets;
1293
+ }
1287
1294
  loadedKeys() {
1288
1295
  return Array.from(this.registry.keys());
1289
1296
  }
@@ -1294,13 +1301,15 @@ var PluginLoader = class {
1294
1301
  });
1295
1302
  if (isPluginModule(mod)) {
1296
1303
  const effectiveToken = this.context.cliTokens?.[tuple.provider] ?? this.context.cliToken;
1297
- const factory = mod.createPlugin({
1304
+ const plugin = mod.createPlugin({
1298
1305
  ...this.projectDefaults(),
1299
1306
  ...this.context,
1300
1307
  ...effectiveToken !== void 0 ? { cliToken: effectiveToken } : {},
1301
1308
  cliTokens: void 0,
1302
1309
  ...tuple.options
1303
- }).capabilities[key];
1310
+ });
1311
+ if (plugin.probes && Object.keys(plugin.probes).length > 0) this.probeSets.set(tuple.provider, plugin.probes);
1312
+ const factory = plugin.capabilities[key];
1304
1313
  if (typeof factory !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not implement the \`${key}\` capability`);
1305
1314
  return factory();
1306
1315
  }
@@ -6904,6 +6913,252 @@ function printNextSteps$1(print, inputs) {
6904
6913
  print(" 7. Commit + push when capability is functionally complete.");
6905
6914
  }
6906
6915
  //#endregion
6916
+ //#region src/commands/probe/core-probes.ts
6917
+ /** The group of probes that belong to the CLI itself, not to a provider. */
6918
+ const CORE_PROVIDER = "core";
6919
+ /**
6920
+ * `core providers`: which providers the config names loaded and which did not, and why. A provider that fails to load
6921
+ * (a missing token, a missing option such as an account id) is skipped quietly by every other command.
6922
+ */
6923
+ function coreProbes(loader) {
6924
+ return { providers: {
6925
+ summary: "Show which configured providers loaded, and why any did not.",
6926
+ writes: false,
6927
+ async run(ctx) {
6928
+ const failed = loader.loadFailures();
6929
+ for (const key of loader.loadedKeys()) ctx.say({
6930
+ status: "ok",
6931
+ label: key
6932
+ });
6933
+ for (const f of failed) ctx.say({
6934
+ status: "fail",
6935
+ label: `${f.key} (${f.provider})`,
6936
+ detail: describeProviderError(f.error)
6937
+ });
6938
+ const withProbes = [...loader.probes().keys()];
6939
+ ctx.say({
6940
+ status: "info",
6941
+ label: "probes offered by",
6942
+ detail: withProbes.length > 0 ? withProbes.join(", ") : "no configured provider"
6943
+ });
6944
+ }
6945
+ } };
6946
+ }
6947
+ //#endregion
6948
+ //#region src/commands/probe/list-probes.ts
6949
+ /** The listing `holocron probe` prints: each provider, and under it each probe with its summary; writers are marked. */
6950
+ function listProbes(groups) {
6951
+ const lines = [];
6952
+ const width = Math.max(0, ...[...groups.values()].flatMap((g) => Object.keys(g).map((n) => n.length)));
6953
+ for (const [provider, probes] of [...groups].sort(([a], [b]) => a.localeCompare(b))) {
6954
+ lines.push(style.header(provider));
6955
+ for (const [name, probe] of Object.entries(probes).sort(([a], [b]) => a.localeCompare(b))) {
6956
+ const mark = probe.writes ? " (changes things)" : "";
6957
+ lines.push(` ${name.padEnd(width)} ${probe.summary}${mark}`);
6958
+ }
6959
+ lines.push("");
6960
+ }
6961
+ return lines;
6962
+ }
6963
+ //#endregion
6964
+ //#region src/ui/command-failure/command-failure.ts
6965
+ /**
6966
+ * Error class names whose `.message` is a complete, actionable sentence. Any other error is printed too, so a command
6967
+ * that throws a plain `Error` is never silent; this set only marks the ones written to be read as they are.
6968
+ */
6969
+ const USER_FACING_ERRORS = /* @__PURE__ */ new Set([
6970
+ "WorkspaceContextError",
6971
+ "ConfigFileError",
6972
+ "NonInteractiveError"
6973
+ ]);
6974
+ /**
6975
+ * The line to print for an error that reached the top level: its message with control characters stripped (a provider's
6976
+ * text can carry them), plus a provider's response detail when it has one. Never empty, so a failure always says
6977
+ * something.
6978
+ */
6979
+ function commandFailureMessage(err) {
6980
+ return describeProviderError(err) || (err instanceof Error ? err.name : "the command failed");
6981
+ }
6982
+ //#endregion
6983
+ //#region src/commands/probe/scrub.ts
6984
+ const HIDDEN = "«hidden»";
6985
+ /** Shapes that are credentials wherever they appear: a Discord webhook URL, a bearer header, a Sentry token. */
6986
+ const SHAPES = [
6987
+ /https:\/\/(?:[\w-]+\.)?discord(?:app)?\.com\/api\/webhooks\/\d+\/[\w-]+/g,
6988
+ /\bBearer\s+[\w.~+/=-]+/gi,
6989
+ /\bsntry[a-z]_[\w+/=-]+/g
6990
+ ];
6991
+ const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
6992
+ /**
6993
+ * Returns a function that replaces secrets in a line of output: every value the caller gave (a token, a signing secret)
6994
+ * and every string shaped like a credential. Values shorter than 6 characters are left, since replacing `ab` would
6995
+ * mangle ordinary words. `secrets` may grow after this is called; it is read on each use.
6996
+ */
6997
+ function createScrubber(secrets) {
6998
+ return (text) => {
6999
+ let out = text;
7000
+ const known = [...secrets].filter((s) => s.length >= 6).sort((a, b) => b.length - a.length);
7001
+ for (const secret of known) out = out.replace(new RegExp(escape(secret), "g"), HIDDEN);
7002
+ for (const shape of SHAPES) out = out.replace(shape, HIDDEN);
7003
+ return out;
7004
+ };
7005
+ }
7006
+ //#endregion
7007
+ //#region src/commands/probe/run-probe.ts
7008
+ const defaultInterrupt = (handler) => {
7009
+ const listener = () => void handler().finally(() => process.exit(130));
7010
+ process.once("SIGINT", listener);
7011
+ return () => void process.off("SIGINT", listener);
7012
+ };
7013
+ /**
7014
+ * Runs one probe under the rules every probe shares: what it prints is scrubbed, a change goes through `write` (skipped
7015
+ * on `--dry-run`), a probe that writes is asked about first, and what it registered to undo runs whether it succeeded,
7016
+ * failed or was interrupted.
7017
+ */
7018
+ async function runProbe(input) {
7019
+ const print = input.print ?? ((line) => console.log(line));
7020
+ const secrets = new Set(input.secrets ?? []);
7021
+ const scrub = createScrubber(secrets);
7022
+ const rows = [];
7023
+ const emit = (row) => {
7024
+ const clean = {
7025
+ status: row.status,
7026
+ label: scrub(stripControl(row.label)),
7027
+ ...row.detail ? { detail: scrub(sanitizeDetail(row.detail)) } : {}
7028
+ };
7029
+ rows.push(clean);
7030
+ print(statusRow(clean.status === "info" ? "skip" : clean.status, [clean.label, clean.detail ?? ""]));
7031
+ };
7032
+ if (input.probe.writes && !input.dryRun && !input.yes) {
7033
+ if (!(input.interactive ?? Boolean(process.stdin.isTTY))) throw new NonInteractiveError(`\`${input.name}\` changes things on ${input.provider} (${input.probe.summary}); pass --yes to run it without asking`);
7034
+ if (!await (input.confirm ?? ((message) => confirm({
7035
+ message,
7036
+ default: false
7037
+ })))(`${input.name} changes things on ${input.provider}: ${input.probe.summary}. Continue?`)) {
7038
+ emit({
7039
+ status: "info",
7040
+ label: input.name,
7041
+ detail: "cancelled; nothing was changed"
7042
+ });
7043
+ return {
7044
+ status: "cancelled",
7045
+ rows
7046
+ };
7047
+ }
7048
+ }
7049
+ const undo = [];
7050
+ const runCleanups = async () => {
7051
+ while (undo.length > 0) {
7052
+ const { label, fn } = undo.pop();
7053
+ try {
7054
+ await fn();
7055
+ emit({
7056
+ status: "info",
7057
+ label: `cleaned up ${label}`
7058
+ });
7059
+ } catch (err) {
7060
+ emit({
7061
+ status: "fail",
7062
+ label: `could not clean up ${label}`,
7063
+ detail: commandFailureMessage(err)
7064
+ });
7065
+ }
7066
+ }
7067
+ };
7068
+ const ctx = {
7069
+ dryRun: input.dryRun,
7070
+ say: emit,
7071
+ secret: (value) => {
7072
+ if (value) secrets.add(value);
7073
+ },
7074
+ async write(label, fn) {
7075
+ if (!input.probe.writes) throw new Error(`${input.name} is read-only and cannot ${label}`);
7076
+ if (input.dryRun) {
7077
+ emit({
7078
+ status: "info",
7079
+ label: `would ${label}`
7080
+ });
7081
+ return;
7082
+ }
7083
+ return fn();
7084
+ },
7085
+ cleanup(label, fn) {
7086
+ if (!input.dryRun) undo.push({
7087
+ label,
7088
+ fn
7089
+ });
7090
+ }
7091
+ };
7092
+ const stopListening = (input.onInterrupt ?? defaultInterrupt)(runCleanups);
7093
+ try {
7094
+ await input.probe.run(ctx);
7095
+ } catch (err) {
7096
+ emit({
7097
+ status: "fail",
7098
+ label: input.name,
7099
+ detail: commandFailureMessage(err)
7100
+ });
7101
+ } finally {
7102
+ stopListening();
7103
+ await runCleanups();
7104
+ }
7105
+ const counts = {
7106
+ ok: rows.filter((r) => r.status === "ok").length,
7107
+ fail: rows.filter((r) => r.status === "fail").length
7108
+ };
7109
+ if (counts.ok + counts.fail > 0) print(`\n${counts.ok} ok, ${counts.fail} fail`);
7110
+ return {
7111
+ status: counts.fail > 0 ? "fail" : "ok",
7112
+ rows
7113
+ };
7114
+ }
7115
+ //#endregion
7116
+ //#region src/commands/probe/probe.ts
7117
+ /**
7118
+ * `holocron probe [<provider> [<probe>]]`. With nothing, lists what can be probed; with a provider, lists its probes;
7119
+ * with both, runs one. Probes come from the configured plugins, plus the CLI's own `core` group.
7120
+ */
7121
+ async function runProbeCommand(input) {
7122
+ const print = input.print ?? ((line) => console.log(line));
7123
+ /* v8 ignore next -- the real loader is only built outside tests, which always inject one */
7124
+ const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
7125
+ await loader.load();
7126
+ const groups = new Map(loader.probes());
7127
+ groups.set(CORE_PROVIDER, coreProbes(loader));
7128
+ if (!input.provider) {
7129
+ for (const line of listProbes(groups)) print(line);
7130
+ return { status: "listed" };
7131
+ }
7132
+ const probes = groups.get(input.provider);
7133
+ if (!probes) {
7134
+ print(statusRow("fail", [`no probes for \`${input.provider}\``, `try: ${[...groups.keys()].sort().join(", ")}`]));
7135
+ return { status: "fail" };
7136
+ }
7137
+ if (!input.probe) {
7138
+ for (const line of listProbes(/* @__PURE__ */ new Map([[input.provider, probes]]))) print(line);
7139
+ return { status: "listed" };
7140
+ }
7141
+ const probe = probes[input.probe];
7142
+ if (!probe) {
7143
+ print(statusRow("fail", [`\`${input.provider}\` has no probe \`${input.probe}\``, `try: ${Object.keys(probes).sort().join(", ")}`]));
7144
+ return { status: "fail" };
7145
+ }
7146
+ const tokens = [input.context.cliToken, ...Object.values(input.context.cliTokens ?? {})].filter((t) => typeof t === "string");
7147
+ return { status: (await runProbe({
7148
+ name: `${input.provider} ${input.probe}`,
7149
+ provider: input.provider,
7150
+ probeName: input.probe,
7151
+ probe,
7152
+ dryRun: input.dryRun ?? false,
7153
+ yes: input.yes ?? false,
7154
+ secrets: tokens,
7155
+ print,
7156
+ ...input.interactive !== void 0 ? { interactive: input.interactive } : {},
7157
+ ...input.confirm ? { confirm: input.confirm } : {},
7158
+ ...input.onInterrupt ? { onInterrupt: input.onInterrupt } : {}
7159
+ })).status };
7160
+ }
7161
+ //#endregion
6907
7162
  //#region src/commands/publish/resolve-otp.ts
6908
7163
  /**
6909
7164
  * `argvOtp` if given, else the `HOLOCRON_OTP` env var — the secret-delivery
@@ -11943,6 +12198,12 @@ const COMMAND_REGISTRY = [
11943
12198
  positionals: [],
11944
12199
  supportsDryRun: true
11945
12200
  },
12201
+ {
12202
+ name: "probe",
12203
+ description: "Poke a live provider on purpose: inspect it, or run a proof that cleans up after itself",
12204
+ positionals: [],
12205
+ supportsDryRun: true
12206
+ },
11946
12207
  {
11947
12208
  name: "repo setup",
11948
12209
  description: "Apply infra setup actions across every configured capability",
@@ -12590,25 +12851,6 @@ function buildRunMenuEntries(taskNames) {
12590
12851
  return entries;
12591
12852
  }
12592
12853
  //#endregion
12593
- //#region src/ui/command-failure/command-failure.ts
12594
- /**
12595
- * Error class names whose `.message` is a complete, actionable sentence. Any other error is printed too, so a command
12596
- * that throws a plain `Error` is never silent; this set only marks the ones written to be read as they are.
12597
- */
12598
- const USER_FACING_ERRORS = /* @__PURE__ */ new Set([
12599
- "WorkspaceContextError",
12600
- "ConfigFileError",
12601
- "NonInteractiveError"
12602
- ]);
12603
- /**
12604
- * The line to print for an error that reached the top level: its message with control characters stripped (a provider's
12605
- * text can carry them), plus a provider's response detail when it has one. Never empty, so a failure always says
12606
- * something.
12607
- */
12608
- function commandFailureMessage(err) {
12609
- return describeProviderError(err) || (err instanceof Error ? err.name : "the command failed");
12610
- }
12611
- //#endregion
12612
12854
  //#region src/update-notifier/update-notifier.ts
12613
12855
  const PACKAGE_NAME = "@theholocron/cli";
12614
12856
  const CACHE_TTL_MS = 864e5;
@@ -13505,7 +13747,35 @@ try {
13505
13747
  }
13506
13748
  }).command("$0", false, () => {}, async (argv) => {
13507
13749
  await launchGroupMenu("new", argv);
13508
- }), () => {}).command("secrets", "Set secrets and sync vault environments", (g) => g.command("set [name] [value]", "Set a single secret via the configured `secrets` capability", (y) => y.positional("name", {
13750
+ }), () => {}).command("probe [provider] [probe]", "Poke a live provider on purpose: inspect it, or run a proof that cleans up after itself", (y) => y.positional("provider", {
13751
+ type: "string",
13752
+ describe: "Which provider's probes (omit to list them all)"
13753
+ }).positional("probe", {
13754
+ type: "string",
13755
+ describe: "Which probe to run (omit to list the provider's)"
13756
+ }).option("yes", {
13757
+ type: "boolean",
13758
+ default: false,
13759
+ describe: "Run a probe that changes things without asking first (required without a terminal)"
13760
+ }), async (argv) => {
13761
+ const tokens = tokenContext(argv.token);
13762
+ if (!tokens) return;
13763
+ const loaded = await loadConfig(argv.cwd);
13764
+ applyResolvedConfig(argv, loaded.resolved);
13765
+ if ((await runProbeCommand({
13766
+ loaded,
13767
+ context: {
13768
+ repoRoot: argv.cwd,
13769
+ dryRun: argv.dryRun,
13770
+ ...tokens,
13771
+ org: resolveOrg(argv, loaded.resolved)
13772
+ },
13773
+ ...argv.provider ? { provider: argv.provider } : {},
13774
+ ...argv.probe ? { probe: argv.probe } : {},
13775
+ dryRun: argv.dryRun,
13776
+ yes: argv.yes
13777
+ })).status === "fail") process.exitCode = 1;
13778
+ }).command("secrets", "Set secrets and sync vault environments", (g) => g.command("set [name] [value]", "Set a single secret via the configured `secrets` capability", (y) => y.positional("name", {
13509
13779
  type: "string",
13510
13780
  describe: "Secret name (e.g., NPM_TOKEN)"
13511
13781
  }).positional("value", {