@theholocron/cli 5.0.0-alpha.351 → 5.0.0-alpha.352

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
@@ -247,7 +247,7 @@ Additional `repo` fields recognised by `holocron repo setup`:
247
247
  | `repo.topics` | `string[]` | GitHub topics set on the repository. |
248
248
  | `repo.protection` | `"balanced" \| "strict" \| "none"` | Branch-protection preset applied by `holocron repo setup`. For `"strict"`, the required status checks are derived from the task manifest — see below. |
249
249
  | `repo.properties` | `RepoProperties` | Org-level custom property values synced to the GitHub dashboard. |
250
- | `repo.variables` | `{ repo?, org?, prune? }` | GitHub Actions variables created and updated by `holocron repo setup`. Undeclared ones are left alone unless `prune` is on. |
250
+ | `repo.variables` | `{ repo?, org?, sync?, prune? }` | GitHub Actions variables created and updated by `holocron repo setup`. Undeclared ones are left alone unless `prune` is on. `sync: [{ environment, keys, scope?, visibility? }]` names the vault environment `holocron secrets sync` fills Actions variables from (a separate environment from the secrets one; names only, a blank value is skipped, `doctor variables` expects the names). A name given as a literal and in `sync`, or `prune` with `sync`, is a config error. |
251
251
  | `repo.secrets` | `{ repo?, org?, environments?, sync? }` | Names of the secrets that must exist, checked (never written) by `holocron doctor secrets`. Names only. The notification layout's secrets and a Chromatic project token are expected without being listed. `sync: [{ environment, keys?, scope? }]` declares the vault environments `secrets sync` fills from (it follows these entries, one step per scope, unless `--github-secret` is given; a blank value is skipped); the doctor expects their keys (every key the `vault` provider lists when `keys` is omitted, names only) at the `scope` (`repo`, `env=<name>`, `org=<name>`). |
252
252
 
253
253
  ### Custom properties synced to GitHub
@@ -610,7 +610,7 @@ commands and the config are provider-neutral; Discord is the first provider.
610
610
  | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
611
611
  | `holocron project reconcile [board]` | Sets item statuses where a rule says so: an open blocker means `blocked`, no blocker left means `planned`, closed means `done` (status only; `--dry-run` previews; an open item with no status is reported). Runs hourly from `platform.projectReconcile.yml`, which `repo setup` writes when `providers.projects` declares boards |
612
612
  | `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 |
613
- | `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. An undeclared variable counts only with `prune`; a scope that cannot be read (no provider, no org token) is a skip, not a failure |
613
+ | `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 |
614
614
  | `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 |
615
615
  | `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 |
616
616
  | `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. |
@@ -629,6 +629,8 @@ Channels fed by the error tracker add `feeds: { errors: true }` and a layout `re
629
629
 
630
630
  `holocron secrets sync <env> --worker <script>` also sets every key of the vault environment on a deployed Worker as a secret, through the optional `Workers.setSecret(script, name, value)` (write-only; the Cloudflare plugin implements it). The Worker must already exist. Sync only adds and updates: it never removes a binding, because a Worker also holds secrets that are not in the vault (for Comlink, the `COMLINK_<SOURCE>_WEBHOOK` that `notifications setup` sets), so a key deleted from the vault must be deleted from the Worker separately. Keys are written one at a time and each is reported; if one fails, the exit code is 1 and re-running finishes the rest, since every write is idempotent.
631
631
 
632
+ `holocron secrets sync <env>` also writes GitHub Actions **variables** when `repo.variables.sync` has an entry for that environment: each key goes through the `source` provider's `syncVariables` (repo scope) or `syncOrgVariables` (`org=<name>`), one call per key and never pruning, so a name the vault lacks or holds blank is skipped and GitHub keeps its value. Keep these in a vault environment of their own (a vault does not tell a visible value from a secret one, and a variable is readable afterwards). An environment declared only by variable entries pushes nothing to `secrets` or `deployment`. Values are never printed. `doctor variables` checks that the names exist at their scope.
633
+
632
634
  `holocron secrets list [--scope repo|environment|organization] [--env <name>] [--json]` prints the names (never the values; GitHub does not return them) of the secrets at each scope, sorted, under a heading per scope. With no `--scope` it lists the repository, plus the organization (`--org`, `HOLOCRON_ORG` or the config's `org`) and the `--env` environment when they are known; `--scope` lists one. A scope that cannot be listed is reported under its heading and the rest are still listed; the exit code is 1 if any failed. `--json` prints `[{ scope, names, error? }]`. It is read-only, so `--dry-run` does not apply. Comparing the names with what the config expects is `doctor secrets`, which also covers the keys of the vault environments declared in `repo.secrets.sync`.
633
635
 
634
636
  A channel with `kind: "forum"` is a forum, with `tags` (each a `name`, an `emoji` and whether it is `moderated`); `setup` adds and corrects the tags but never removes one, and a text channel of the same name must be deleted first, since neither kind can become the other. A forum takes no `webhook` or `feeds`.
package/dist/cli.mjs CHANGED
@@ -112,6 +112,34 @@ var MissingTokenError = class extends Error {
112
112
  /** Lets a caller tell this error from any other by name, across package copies. */
113
113
  name = "MissingTokenError";
114
114
  };
115
+ // src/config/validate-variables-sync/validate-variables-sync.ts
116
+ /** GitHub treats variable names as case-insensitive, so every comparison goes through this. */
117
+ const key = (name) => name.toUpperCase();
118
+ /**
119
+ * Check `repo.variables.sync`: each entry names a vault environment, one or more keys and a scope that is `repo` or
120
+ * `org=<name>`; a name may not also be a literal value of the same scope (one source per name); and `prune` cannot
121
+ * be combined with `sync`, because `repo setup` would delete the variables the sync wrote.
122
+ *
123
+ * @param variables - `repo.variables`, if the config has it.
124
+ * @throws {ConfigError} Naming the first problem found.
125
+ */
126
+ function validateVariablesSync(variables) {
127
+ const entries = variables?.sync;
128
+ if (!entries || entries.length === 0) return;
129
+ if (variables?.prune === true) throw new ConfigError("`repo.variables.prune` cannot be combined with `repo.variables.sync`: pruning would delete the variables the sync writes");
130
+ for (const entry of entries) {
131
+ if (typeof entry.environment !== "string" || entry.environment.trim() === "") throw new ConfigError("a `repo.variables.sync` entry needs the name of a vault environment");
132
+ const label = `\`repo.variables.sync\` entry for ${JSON.stringify(entry.environment)}`;
133
+ if (!Array.isArray(entry.keys) || entry.keys.length === 0 || entry.keys.some((k) => typeof k !== "string" || k === "")) throw new ConfigError(`${label} needs \`keys\`, a list of variable names`);
134
+ const scope = entry.scope ?? "repo";
135
+ const org = scope.startsWith("org=") ? scope.slice(4) : void 0;
136
+ if (scope !== "repo" && (org === void 0 || org === "")) throw new ConfigError(`${label} has scope ${JSON.stringify(scope)}: use "repo" or "org=<name>"`);
137
+ if (entry.visibility !== void 0 && entry.visibility !== "all" && entry.visibility !== "private") throw new ConfigError(`${label} has visibility ${JSON.stringify(entry.visibility)}: use "all" or "private"`);
138
+ const literal = new Set(Object.keys((org === void 0 ? variables?.repo : variables?.org) ?? {}).map(key));
139
+ const both = entry.keys.filter((k) => literal.has(key(k)));
140
+ if (both.length > 0) throw new ConfigError(`${label} lists ${both.join(", ")}, which \`repo.variables.${org === void 0 ? "repo" : "org"}\` also gives a value: keep one source per name`);
141
+ }
142
+ }
115
143
  // src/config/config/config.ts
116
144
  const PLUGIN_PREFIX = "@theholocron/holocron-plugin-";
117
145
  const COMMUNITY_PREFIX = "holocron-plugin-";
@@ -233,6 +261,7 @@ function resolveConfig(raw) {
233
261
  if (typeof environment !== "string" || environment.trim() === "") throw new ConfigError$1("`credentials.environment` must be the name of an environment, got an empty value");
234
262
  }
235
263
  if (raw.dev !== void 0) validateDev(raw.dev);
264
+ validateVariablesSync(raw.repo?.variables);
236
265
  const credentialsEntry = providers.credentials;
237
266
  if (credentialsEntry?.cardinality === "many") for (const tuple of credentialsEntry.tuples) {
238
267
  const own = tuple.options.environment;
@@ -269,8 +298,9 @@ function resolveConfig(raw) {
269
298
  }
270
299
  // src/config/compose/merge-sync/merge-sync.ts
271
300
  /**
272
- * Merge two lists of `repo.secrets.sync` entries. An entry is the same sync when its environment and scope match;
273
- * the keys then add up, and an entry that names no keys (every key the vault holds) stays that way.
301
+ * Merge two lists of `repo.secrets.sync` (or `repo.variables.sync`) entries. An entry is the same sync when its
302
+ * environment and scope match; the keys then add up, and an entry that names no keys (every key the vault holds) stays
303
+ * that way.
274
304
  */
275
305
  function mergeSync(a, b) {
276
306
  const merged = /* @__PURE__ */ new Map();
@@ -293,7 +323,7 @@ const properties = shallowMerge();
293
323
  const teamsByKey = mergeByKey((t) => typeof t === "string" ? t : t.slug);
294
324
  /**
295
325
  * Merge one capability's `repo` fragment onto what earlier ones gave. Scalars: last writer wins. `properties`: shallow
296
- * merge. `variables`: merged per scope (`repo`, `org`). `secrets`: each name list is a union, and `sync` entries merge by
326
+ * merge. `variables`: merged per scope (`repo`, `org`), and `sync` entries by environment and scope. `secrets`: each name list is a union, and `sync` entries merge by
297
327
  * environment and scope. `topics`: union. `teams`: merged by slug.
298
328
  */
299
329
  function mergeRepo(prev, next) {
@@ -313,7 +343,8 @@ function mergeRepo(prev, next) {
313
343
  ...repo.variables?.org || variables.org ? { org: {
314
344
  ...repo.variables?.org,
315
345
  ...variables.org
316
- } } : {}
346
+ } } : {},
347
+ ...repo.variables?.sync || variables.sync ? { sync: mergeSync(repo.variables?.sync, variables.sync) } : {}
317
348
  };
318
349
  if (secrets) {
319
350
  const environments = { ...repo.secrets?.environments };
@@ -9517,12 +9548,61 @@ const doctorSecretsCommand = {
9517
9548
  })).status === "fail") process.exitCode = 1;
9518
9549
  }
9519
9550
  };
9551
+ // src/commands/doctor-variables/sync-checks.ts
9552
+ /** Re-keys what GitHub holds by the spelling the config declares, since GitHub treats names as case-insensitive. */
9553
+ function bySpelling$1(declared, have) {
9554
+ const spelled = new Map(declared.map((name) => [name.toUpperCase(), name]));
9555
+ return new Map(Object.entries(have).map(([name, value]) => [spelled.get(name.toUpperCase()) ?? name, value]));
9556
+ }
9557
+ /**
9558
+ * The checks `repo.variables.sync` adds to `holocron doctor variables`: one per entry, that every key it lists exists
9559
+ * at its scope. The values live in the vault, which the doctor does not read, so only names (and, for an organization
9560
+ * entry, the visibility it writes) are compared and a value is never shown. A scope that is not `repo` or `org=<name>`
9561
+ * is rejected when the config loads, so it is not handled here.
9562
+ *
9563
+ * @param entries - `repo.variables.sync`, if the config has it.
9564
+ */
9565
+ function syncVariableChecks(entries) {
9566
+ return (entries ?? []).map((entry) => {
9567
+ const scope = entry.scope ?? "repo";
9568
+ const org = scope.startsWith("org=") ? scope.slice(4) : void 0;
9569
+ return {
9570
+ id: `sync-${entry.environment}-${scope}`,
9571
+ title: `${org === void 0 ? "repository" : `${org} organization`} variables from ${entry.environment} exist`,
9572
+ async run(source) {
9573
+ const checked = entry.keys.length;
9574
+ if (org === void 0) {
9575
+ if (!source.listVariables) return { skip: "provider does not implement listVariables" };
9576
+ const have = bySpelling$1(entry.keys, await source.listVariables());
9577
+ return {
9578
+ problems: declaredVsActual(new Map(entry.keys.map((name) => [name, true])), new Map([...have.keys()].map((name) => [name, true])), {
9579
+ noun: "variable",
9580
+ flagExtra: false
9581
+ }),
9582
+ checked
9583
+ };
9584
+ }
9585
+ if (!source.listOrgVariables) return { skip: "provider does not implement listOrgVariables" };
9586
+ const have = bySpelling$1(entry.keys, await source.listOrgVariables(org));
9587
+ return {
9588
+ problems: declaredVsActual(new Map(entry.keys.map((name) => [name, entry.visibility ?? "all"])), new Map([...have].map(([name, v]) => [name, v.visibility])), {
9589
+ noun: "organization variable",
9590
+ flagExtra: false,
9591
+ show: (visibility) => `visibility ${visibility}`
9592
+ }),
9593
+ checked
9594
+ };
9595
+ }
9596
+ };
9597
+ });
9598
+ }
9520
9599
  // src/commands/doctor-variables/doctor-variables.ts
9521
9600
  /**
9522
9601
  * `holocron doctor variables` — do the Actions variables `repo.variables` declares exist, with those values?
9523
9602
  *
9524
9603
  * Read-only. One row for the repository's variables and one for the organization's, each only when the config
9525
- * declares that scope. A variable that exists but is not declared is a problem only with `repo.variables.prune`,
9604
+ * declares that scope, and one per `repo.variables.sync` entry that checks its names exist (the values are in the
9605
+ * vault, so none is compared or shown). A variable that exists but is not declared is a problem only with `repo.variables.prune`,
9526
9606
  * since without it `repo setup` leaves it alone. A scope that cannot be read because there is no provider, the
9527
9607
  * provider cannot list variables, or the token is missing is a skip with the reason, not a failure.
9528
9608
  */
@@ -9568,6 +9648,7 @@ async function runDoctorVariables(input) {
9568
9648
  };
9569
9649
  }
9570
9650
  });
9651
+ checks.push(...syncVariableChecks(variables?.sync));
9571
9652
  const rows = [];
9572
9653
  if (checks.length === 0) rows.push({
9573
9654
  id: "variables",
@@ -20822,6 +20903,9 @@ function restorePem(value) {
20822
20903
  * entry for this environment gives `secrets` its own keys and scope, one
20823
20904
  * step per scope, so one environment can fill organization and repository
20824
20905
  * secrets in one run.
20906
+ * - `repo.variables.sync` entries for this environment give Actions variables: each key goes through the `source`
20907
+ * provider's `syncVariables` (repo scope) or `syncOrgVariables`, one call per key, without pruning. An
20908
+ * environment with only variable entries pushes nothing to `secrets` or `deployment`.
20825
20909
  * - A key that is blank in the vault is skipped in every destination, and a
20826
20910
  * listed key the vault does not hold is a skipped row.
20827
20911
  *
@@ -20890,7 +20974,41 @@ async function runSecretsSync(input) {
20890
20974
  }
20891
20975
  }
20892
20976
  }
20893
- if (loader.has("deployment")) {
20977
+ const variableRoutes = input.variableRoutes ?? [];
20978
+ if (variableRoutes.length > 0) {
20979
+ const source = loader.has("source") ? loader.get("source") : void 0;
20980
+ for (const route of variableRoutes) {
20981
+ const scope = scopeLabel(route.scope);
20982
+ print(style.step(`variables (${scope})`));
20983
+ const destination = `variables:${source?.providerName ?? "source"}`;
20984
+ const org = route.scope.kind === "organization" ? route.scope.name : void 0;
20985
+ const unsupported = !source ? "needs a `source` provider in holocron.config.ts" : org === void 0 && !source.syncVariables ? `source provider (${source.providerName}) does not implement syncVariables` : org !== void 0 && !source.syncOrgVariables ? `source provider (${source.providerName}) does not implement syncOrgVariables` : void 0;
20986
+ if (unsupported) {
20987
+ const row = {
20988
+ destination,
20989
+ scope,
20990
+ key: "(all)",
20991
+ status: "fail",
20992
+ message: unsupported
20993
+ };
20994
+ rows.push(row);
20995
+ print(formatRow(row));
20996
+ continue;
20997
+ }
20998
+ for (const key of route.keys) {
20999
+ rows.push(await pushRow(destination, scope, key, envVars, dryRun, async (value) => {
21000
+ if (org === void 0) await source.syncVariables({ [key]: value }, { prune: false });
21001
+ else await source.syncOrgVariables(org, { [key]: {
21002
+ value,
21003
+ visibility: route.visibility ?? "all"
21004
+ } }, { prune: false });
21005
+ }));
21006
+ print(formatRow(rows[rows.length - 1]));
21007
+ }
21008
+ }
21009
+ }
21010
+ const variablesOnly = variableRoutes.length > 0 && input.secretRoutes?.length === 0 && !input.projectId;
21011
+ if (loader.has("deployment") && !variablesOnly) {
20894
21012
  const deploy = loader.get("deployment");
20895
21013
  if (!input.projectId) {
20896
21014
  print(style.step("deployment"));
@@ -21034,6 +21152,26 @@ function vaultProviderName(loader) {
21034
21152
  if (!loader.has("vault")) return "<missing>";
21035
21153
  return loader.get("vault").providerName;
21036
21154
  }
21155
+ // src/commands/secrets-sync/variable-routes.ts
21156
+ /**
21157
+ * The routes into Actions variables that `repo.variables.sync` declares for one vault environment: every entry naming
21158
+ * it gives its keys and the scope they land at (`repo` when omitted). An environment no entry names has none.
21159
+ *
21160
+ * @param entries - `repo.variables.sync`, if the config has it.
21161
+ * @param environmentId - The vault environment being synced.
21162
+ * @throws When an entry's `scope` is not `repo` or `org=<name>`.
21163
+ */
21164
+ function variableRoutes(entries, environmentId) {
21165
+ return (entries ?? []).filter((entry) => entry.environment === environmentId).map((entry) => {
21166
+ const scope = parseScope(entry.scope ?? "repo");
21167
+ if (scope.kind === "environment") throw new Error(`invalid variable scope "${entry.scope}" — expected "repo" or "org=<name>"`);
21168
+ return {
21169
+ scope,
21170
+ keys: entry.keys,
21171
+ ...entry.visibility ? { visibility: entry.visibility } : {}
21172
+ };
21173
+ });
21174
+ }
21037
21175
  // src/commands/secrets-sync/secrets-sync.args.ts
21038
21176
  const secretsSyncArgs = (y) => y.positional("environmentId", {
21039
21177
  type: "string",
@@ -21069,6 +21207,8 @@ const secretsSyncCommand = {
21069
21207
  const loaded = await loadConfig(argv.cwd);
21070
21208
  applyResolvedConfig(argv, loaded.resolved);
21071
21209
  const routes = argv.githubSecret?.length ? [] : secretRoutes(loaded.resolved.repo?.secrets?.sync, environmentId);
21210
+ const variables = variableRoutes(loaded.resolved.repo?.variables?.sync, environmentId);
21211
+ const variablesOnly = variables.length > 0 && routes.length === 0 && !argv.githubSecret?.length;
21072
21212
  if ((await runSecretsSync({
21073
21213
  loaded,
21074
21214
  context: {
@@ -21082,7 +21222,8 @@ const secretsSyncCommand = {
21082
21222
  ...argv.worker ? { workerScript: argv.worker } : {},
21083
21223
  ...argv.githubSecret?.length ? { githubSecretKeys: argv.githubSecret } : {},
21084
21224
  githubSecretScope,
21085
- ...routes.length ? { secretRoutes: routes } : {},
21225
+ ...routes.length ? { secretRoutes: routes } : variablesOnly ? { secretRoutes: [] } : {},
21226
+ ...variables.length ? { variableRoutes: variables } : {},
21086
21227
  targets: argv.target
21087
21228
  })).summary.fail > 0) process.exitCode = 1;
21088
21229
  }