@theholocron/cli 5.0.0-alpha.420 → 5.0.0-alpha.421

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
@@ -258,14 +258,14 @@ and nothing else carries a copy. `.holocron/org.md` (the agent contract the CLI
258
258
 
259
259
  Additional `repo` fields recognised by `holocron repo setup`:
260
260
 
261
- | Field | Type | Description |
262
- | ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
263
- | `repo.teams` | `Array<string \| { slug, permission }>` | GitHub teams granted repo access. String shorthand defaults to `push` (Write). `holocron repo setup` also writes `.github/CODEOWNERS` for teams with `push`/`maintain`/`admin`. |
264
- | `repo.topics` | `string[]` | GitHub topics set on the repository. |
265
- | `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. |
266
- | `repo.properties` | `RepoProperties` | Org-level custom property values synced to the GitHub dashboard. |
267
- | `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. |
268
- | `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?, repos? }]` 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>`). An `org=` scope requires `repos`, the repositories that can read the secrets (visibility `selected`, never `all`); without it the config does not load. `doctor secrets` flags a secret readable by more repositories than its entry lists, and a name held at both repository and organization level. |
261
+ | Field | Type | Description |
262
+ | ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
263
+ | `repo.teams` | `Array<string \| { slug, permission }>` | GitHub teams granted repo access. String shorthand defaults to `push` (Write). `holocron repo setup` also writes `.github/CODEOWNERS` for teams with `push`/`maintain`/`admin`. |
264
+ | `repo.topics` | `string[]` | GitHub topics set on the repository. |
265
+ | `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. |
266
+ | `repo.properties` | `RepoProperties` | Org-level custom property values synced to the GitHub dashboard. |
267
+ | `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. |
268
+ | `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?, repos? }]` declares the vault environments `secrets sync` fills from (it follows these entries, one step per scope, unless `--github-secret` is given; the `local` and `dev` layers are never synced (a `ConfigError`, and an entry naming them does not load); an environment with no entry and no `--github-secret` is a `ConfigError` before the vault is read, #2104; 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>`). An `org=` scope requires `repos`, the repositories that can read the secrets (visibility `selected`, never `all`); without it the config does not load. `doctor secrets` flags a secret readable by more repositories than its entry lists, and a name held at both repository and organization level. |
269
269
 
270
270
  ### Custom properties synced to GitHub
271
271
 
package/dist/cli.mjs CHANGED
@@ -12,9 +12,9 @@ import yargs from "yargs";
12
12
  import { hideBin } from "yargs/helpers";
13
13
  import { ConfigError, ConfigError as ConfigError$1, createConfigSystem, lastWins, mergeByKey, shallowMerge, union } from "@theholocron/kyber/config";
14
14
  import { LoaderError, assertPluginsResolvable, createPluginSystem, isModuleNotFound, resolvePluginPackage } from "@theholocron/kyber/plugins";
15
+ import { readGitRemote, updateGitignore, upsertManagedBlock } from "@theholocron/git-utils";
15
16
  import { DEFAULT_ORG, DOT_GITHUB_REPO, HOLOCRON_REPO, KNOWN_TASKS, KNOWN_WORKFLOWS, LEGACY_NAMES, PNPM_BUILTIN_COMMANDS, PRERELEASE_CHANNEL, RELEASE_BRANCHES, RESERVED_SCRIPT_NAMES, SUITES, TASKS, aggregateChecks, checkPackageScripts, createAlexignore, createAlexrc, createAstromech, createCommitMsg, createDco, createDependabot, createDevmoji, createEditorconfig, createEditorconfigChecker, createHeader, createLabeler, createPreCommit, createPrePush, createPrepareCommitMsg, createYamlignore, createYamllint, defaultListDirs, defaultPaths, defaultReadJson, deployOnRelease, describeTasks, extractPreviewConfig, frozenReusablePaths, generateThinCallerContent, hostedReusableWorkflows, isDeprecated, isTask, legacyCaller, legacyCallerFile, legacyGate, legacyWorkflowKey, localize, mergeScripts, readWorkspacePackages, resolveTaskName, reusableTemplates, scriptName, stampDeprecated, workflowFile, workflowKey, workflowKeys, workspacePackages } from "@theholocron/astromech";
16
17
  import { loadTasksConfig } from "@theholocron/astromech/config";
17
- import { readGitRemote, updateGitignore, upsertManagedBlock } from "@theholocron/git-utils";
18
18
  import { bumpCatalogPins, discoverWorkspacePackages, parseCatalogs, readPackageJson, readPackageJsonSync, resolveWorkspaceGlobs } from "@theholocron/pkg-utils";
19
19
  import { createCliLogger, createCliTelemetry } from "@theholocron/kyber/observability";
20
20
  import { resolveAxiomFromEnv } from "@theholocron/observability/logger";
@@ -166,6 +166,50 @@ function validateEnvironmentChoice(entry, what, required = true) {
166
166
  }
167
167
  if (required) throw new ConfigError(`${what} needs the name of a vault environment (\`environment\`) or a \`layer\``);
168
168
  }
169
+ // src/credentials-environments/repo-slug/repo-slug.ts
170
+ /**
171
+ * The `<org>/<repo>` of the repository at `cwd`, from its `origin` remote. A remote that is missing or cannot be
172
+ * parsed is a `ConfigError` that names the `environment` option as the fix.
173
+ */
174
+ async function repoSlug(cwd, exec) {
175
+ const remote = await readGitRemote(cwd, exec ? { exec } : {});
176
+ if (!remote) throw new ConfigError(`cannot derive the 1Password Environment name: the \`origin\` remote of ${cwd} is missing or not an owner/repo URL. Give the \`credentials\` provider an \`environment\` option to name it.`);
177
+ return remote.slug;
178
+ }
179
+ // src/credentials-environments/unsynced-layer/unsynced-layer.ts
180
+ /** The layers this machine reads for itself. They are never synced to GitHub, a deployment or a Worker (#2104). */
181
+ const UNSYNCED_LAYERS = ["local", "dev"];
182
+ /** Whether `layer` is one of {@link UNSYNCED_LAYERS}. */
183
+ function isUnsyncedLayer(layer) {
184
+ return isEnvironmentLayer(layer) && UNSYNCED_LAYERS.includes(layer);
185
+ }
186
+ /**
187
+ * The text of the error for an Environment of an unsynced layer, shared by the command and the config checks.
188
+ *
189
+ * @param what - What names the layer, e.g. "`secrets sync dev`" or "a `repo.secrets.sync` entry".
190
+ * @param layer - The unsynced layer.
191
+ */
192
+ function unsyncedLayerMessage(what, layer) {
193
+ return `${what} names the \`${layer}\` layer: \`local\` and \`dev\` are read by this machine and are never synced. Only ${ENVIRONMENT_LAYERS.filter((l) => !isUnsyncedLayer(l)).map((l) => `\`${l}\``).join(" and ")} can be synced`;
194
+ }
195
+ /**
196
+ * Refuse a sync of an unsynced layer, before anything is read. The argument is a layer word, or the literal name of a
197
+ * layer's Environment (`<org/repo> - dev`, built by `layerEnvironment()` from the `origin` remote). A remote that
198
+ * cannot be read means no literal name can be matched, so only a layer word is checked then.
199
+ *
200
+ * @param id - The environment as given on the command line.
201
+ * @param input - Where the repository is, and optionally how to read its remote.
202
+ * @throws {ConfigError} For an unsynced layer, whatever other flags are given.
203
+ */
204
+ async function assertSyncableLayer(id, input) {
205
+ if (isEnvironmentLayer(id)) {
206
+ if (isUnsyncedLayer(id)) throw new ConfigError(unsyncedLayerMessage(`\`secrets sync ${id}\``, id));
207
+ return;
208
+ }
209
+ const slug = await repoSlug(input.repoRoot, input.gitExec).catch(() => void 0);
210
+ if (slug === void 0) return;
211
+ for (const layer of UNSYNCED_LAYERS) if (id === layerEnvironment(slug, layer)) throw new ConfigError(unsyncedLayerMessage(`\`secrets sync\` for ${JSON.stringify(id)}`, layer));
212
+ }
169
213
  // src/config/validate-secrets-deploy/validate-secrets-deploy.ts
170
214
  /**
171
215
  * Check `repo.secrets.deploy`: each entry names a vault environment (or a `layer`) and at least one of a non-empty `keys` list and a
@@ -179,6 +223,7 @@ function validateSecretsDeploy(secrets) {
179
223
  for (const entry of secrets?.deploy ?? []) {
180
224
  const named = validateEnvironmentChoice(entry, "a `repo.secrets.deploy` entry");
181
225
  const label = `\`repo.secrets.deploy\` entry for ${JSON.stringify(named)}`;
226
+ if (isUnsyncedLayer(entry.layer)) throw new ConfigError(unsyncedLayerMessage(label, entry.layer));
182
227
  const { keys, prefix } = entry;
183
228
  if (keys !== void 0 && (!Array.isArray(keys) || keys.some((k) => typeof k !== "string" || k === ""))) throw new ConfigError(`${label} has \`keys\` that is not a list of key names`);
184
229
  if (prefix !== void 0 && (typeof prefix !== "string" || prefix === "")) throw new ConfigError(`${label} has an empty \`prefix\``);
@@ -203,6 +248,7 @@ function validateSecretsSync(secrets) {
203
248
  for (const entry of secrets?.sync ?? []) {
204
249
  const named = validateEnvironmentChoice(entry, "a `repo.secrets.sync` entry");
205
250
  const label = `\`repo.secrets.sync\` entry for ${JSON.stringify(named)}`;
251
+ if (isUnsyncedLayer(entry.layer)) throw new ConfigError(unsyncedLayerMessage(label, entry.layer));
206
252
  const scope = entry.scope ?? "repo";
207
253
  if (!scope.startsWith("org=")) {
208
254
  if (entry.visibility !== void 0 || entry.repos !== void 0) throw new ConfigError(`${label} sets \`visibility\` or \`repos\` on scope ${JSON.stringify(scope)}: only an organization scope ("org=<name>") has readers to name`);
@@ -782,16 +828,6 @@ function environmentLayers(slug, layer) {
782
828
  });
783
829
  return layer === "local" ? [candidate(SUFFIX.local, true), candidate(SUFFIX.development, false)] : [candidate(SUFFIX[layer], false)];
784
830
  }
785
- // src/credentials-environments/repo-slug/repo-slug.ts
786
- /**
787
- * The `<org>/<repo>` of the repository at `cwd`, from its `origin` remote. A remote that is missing or cannot be
788
- * parsed is a `ConfigError` that names the `environment` option as the fix.
789
- */
790
- async function repoSlug(cwd, exec) {
791
- const remote = await readGitRemote(cwd, exec ? { exec } : {});
792
- if (!remote) throw new ConfigError(`cannot derive the 1Password Environment name: the \`origin\` remote of ${cwd} is missing or not an owner/repo URL. Give the \`credentials\` provider an \`environment\` option to name it.`);
793
- return remote.slug;
794
- }
795
831
  // src/credentials-environments/resolve-environments/resolve-environments.ts
796
832
  /**
797
833
  * The Environments one `credentials` entry reads. An explicit name (the entry's `environment` option, else the shared
@@ -25095,7 +25131,10 @@ function restorePem(value) {
25095
25131
  * closed (#2061): they receive only the keys `repo.secrets.deploy` names for this environment (an exact `keys`
25096
25132
  * list and/or a `prefix`), passed in as `deployFilter`. With none, the run throws a `ConfigError` before it reads
25097
25133
  * the vault. A name outside the filter is reported by name only and never reaches the provider.
25098
- * - `secrets` (GH Actions) defaults to every key, repo-scoped — but a
25134
+ * - `secrets` (GH Actions) fails closed too (#2104): with no `repo.secrets.sync` entry for the environment, no
25135
+ * `--github-secret` (`--github-secret-scope` alone names no keys and is refused) and no deployment or Worker destination, the run throws a
25136
+ * `ConfigError` before the vault is read, `--dry-run` included. A deployment or Worker sync alone writes nothing
25137
+ * to `secrets`. Where a destination is named, `secrets` defaults to every key, repo-scoped — and a
25099
25138
  * caller can pass `githubSecretKeys` (an allowlist, from repeatable
25100
25139
  * `--github-secret KEY` CLI values) to restrict `secrets` to only
25101
25140
  * those keys, and `githubSecretScope` (same `{ kind }` shape `secret
@@ -25120,6 +25159,15 @@ function restorePem(value) {
25120
25159
  * If it doesn't, the command errors with a hint to populate the keys
25121
25160
  * individually via `holocron secrets set` (also planned for v5.1).
25122
25161
  */
25162
+ /**
25163
+ * The `ConfigError` text for a sync that names no destination for `secrets`: the environment, and the environments
25164
+ * `repo.secrets.sync` does have an entry for.
25165
+ */
25166
+ function noSecretsEntryMessage(environmentId, entries) {
25167
+ const known = [...new Set(entries.map((entry) => resolvedEnvironment(entry)))];
25168
+ const list = known.length > 0 ? known.map((name) => JSON.stringify(name)).join(", ") : "none";
25169
+ return `no \`repo.secrets.sync\` entry for environment ${JSON.stringify(environmentId)}: a sync with no entry would write every key to the repository's secrets. Environments with an entry: ${list}. Add { environment: ${JSON.stringify(environmentId)}, keys: [...], scope: "repo" } (or layer: "<layer>") to repo.secrets.sync, or name the destination with --github-secret <KEY> (with --github-secret-scope for another scope)`;
25170
+ }
25123
25171
  /** Why there is no `workers` provider: the plugin's own load error when it failed to load (e.g. a missing account id). */
25124
25172
  function workersMissing(loader) {
25125
25173
  const base = "--worker needs a `workers` provider in holocron.config.ts";
@@ -25127,6 +25175,10 @@ function workersMissing(loader) {
25127
25175
  return failure ? `${base} (\`${failure.provider}\` failed to load: ${describeError(failure.error)})` : base;
25128
25176
  }
25129
25177
  async function runSecretsSync(input) {
25178
+ await assertSyncableLayer(input.environmentId, {
25179
+ repoRoot: input.context.repoRoot,
25180
+ ...input.gitExec ? { gitExec: input.gitExec } : {}
25181
+ });
25130
25182
  const print = input.print ?? ((line) => console.log(line));
25131
25183
  const logger = input.logger ?? getLogger();
25132
25184
  const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
@@ -25139,6 +25191,9 @@ async function runSecretsSync(input) {
25139
25191
  const dryRun = input.context.dryRun ?? false;
25140
25192
  const variablesOnly = (input.variableRoutes?.length ?? 0) > 0 && input.secretRoutes?.length === 0 && !input.projectId;
25141
25193
  if ((loader.has("deployment") && !variablesOnly && Boolean(input.projectId) || input.workerScript) && !input.deployFilter) throw new ConfigError(`no \`repo.secrets.deploy\` entry for environment ${JSON.stringify(input.environmentId)}: a deployment or a Worker receives only the keys named by \`keys\` or \`prefix\`, never every key. Add { environment: ${JSON.stringify(input.environmentId)}, prefix: "<PREFIX>_" } (or keys: [...]) to repo.secrets.deploy`);
25194
+ const namesSecretsDestination = input.secretRoutes !== void 0 || Boolean(input.githubSecretKeys?.length);
25195
+ if (!namesSecretsDestination && input.githubSecretScope !== void 0) throw new ConfigError(`--github-secret-scope names a scope but no keys: pass the keys to write with --github-secret <KEY>, or declare environment ${JSON.stringify(input.environmentId)} in \`repo.secrets.sync\``);
25196
+ if (!namesSecretsDestination && !input.projectId && !input.workerScript) throw new ConfigError(noSecretsEntryMessage(input.environmentId, input.loaded.resolved.repo?.secrets?.sync ?? []));
25142
25197
  for (const route of input.secretRoutes ?? [{ scope: input.githubSecretScope ?? { kind: "repo" } }]) if (route.scope.kind === "organization" && !route.scope.repos?.length) throw new ConfigError(`organization secrets (org=${route.scope.name}) need an explicit reader list: declare them in \`repo.secrets.sync\` with \`repos: [...]\` (visibility "selected"), never "all"`);
25143
25198
  const targets = input.targets ?? ["production", "preview"];
25144
25199
  print(style.header(`Holocron secrets sync — environment ${input.environmentId}${dryRun ? " (dry-run)" : ""}`));
@@ -25171,10 +25226,10 @@ async function runSecretsSync(input) {
25171
25226
  const rows = [];
25172
25227
  if (loader.has("secrets")) {
25173
25228
  const secrets = loader.get("secrets");
25174
- const routes = input.secretRoutes ?? [{
25229
+ const routes = input.secretRoutes ?? (input.githubSecretKeys?.length ? [{
25175
25230
  scope: input.githubSecretScope ?? { kind: "repo" },
25176
- ...input.githubSecretKeys ? { keys: input.githubSecretKeys } : {}
25177
- }];
25231
+ keys: input.githubSecretKeys
25232
+ }] : []);
25178
25233
  for (const route of routes) {
25179
25234
  print(style.step(routes.length > 1 ? `secrets (${scopeLabel(route.scope)})` : "secrets"));
25180
25235
  const access = await readAccess(secrets, route.scope, print);
@@ -25456,11 +25511,10 @@ const secretsSyncArgs = (y) => y.positional("environmentId", {
25456
25511
  describe: "A deployed Worker (script name) to set every vault key on as a secret, e.g. comlink."
25457
25512
  }).option("github-secret", {
25458
25513
  type: "array",
25459
- describe: "Vault key(s) to push to GH Actions secrets (repeatable). Omit to push every key."
25514
+ describe: "Vault key(s) to push to GH Actions secrets (repeatable). Names the destination when `repo.secrets.sync` has no entry."
25460
25515
  }).option("github-secret-scope", {
25461
25516
  type: "string",
25462
- default: "repo",
25463
- describe: "Scope applied to every --github-secret key: \"repo\" (default), \"env=<name>\", or \"org=<name>\"."
25517
+ describe: "Scope applied to every --github-secret key: \"repo\", \"env=<name>\", or \"org=<name>\". Naming it counts as naming the destination."
25464
25518
  });
25465
25519
  // src/commands/secrets-sync/secrets-sync.command.ts
25466
25520
  const secretsSyncCommand = {
@@ -25470,8 +25524,9 @@ const secretsSyncCommand = {
25470
25524
  handler: async (argv) => {
25471
25525
  const tokens = tokenContext$1(argv.token);
25472
25526
  if (!tokens) return;
25473
- const githubSecretScope = parseScope(argv.githubSecretScope);
25527
+ const githubSecretScope = argv.githubSecretScope ? parseScope(argv.githubSecretScope) : void 0;
25474
25528
  const [environmentId] = await promptForPositionals(getEntry("secrets sync"), argv);
25529
+ await assertSyncableLayer(environmentId, { repoRoot: argv.cwd });
25475
25530
  const loaded = await loadConfig(argv.cwd);
25476
25531
  const environment = await resolveEnvironmentId(environmentId, { repoRoot: argv.cwd });
25477
25532
  applyResolvedConfig(argv, loaded.resolved);
@@ -25492,7 +25547,7 @@ const secretsSyncCommand = {
25492
25547
  ...argv.worker ? { workerScript: argv.worker } : {},
25493
25548
  ...deploy ? { deployFilter: deploy } : {},
25494
25549
  ...argv.githubSecret?.length ? { githubSecretKeys: argv.githubSecret } : {},
25495
- githubSecretScope,
25550
+ ...githubSecretScope ? { githubSecretScope } : {},
25496
25551
  ...routes.length ? { secretRoutes: routes } : variablesOnly ? { secretRoutes: [] } : {},
25497
25552
  ...variables.length ? { variableRoutes: variables } : {},
25498
25553
  targets: argv.target