@theholocron/cli 5.0.0-alpha.354 → 5.0.0-alpha.356

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
@@ -244,8 +244,11 @@ repo's `.holocron/repo.ts` holds `teams`, `topics`, `variables` and `secrets`, n
244
244
  out, so the config can say `deployment: ["vercel", { domain }]` and `monitoring: "checkly"`. The same option set inline
245
245
  and in the file is an error that names both (`vercel.teamId is set in providers.deployment and in
246
246
  .holocron/org.ts`), with no merge and no precedence. A provider key or an option the area does not know is an error; a
247
- provider the config does not use is ignored. A config reads only the `.holocron/` beside it, so an app with its own
248
- `holocron.config.ts` (`apps/sentinel`) has its own `.holocron/org.ts`. Anything CI needs (`CLOUDFLARE_ACCOUNT_ID`,
247
+ provider the config does not use is ignored. The org area is shared: a config in a subdirectory (`apps/sentinel`)
248
+ also reads the repository root's `.holocron/org.ts` (the nearest ancestor with a `.git`), and its own
249
+ `.holocron/org.ts` wins for a key set in both, option by option; that is not an error, so an identifier written in the
250
+ root file needs no copy in the app. The other areas (`repo`, `notifications`) describe the repository and are not
251
+ shared. Anything CI needs (`CLOUDFLARE_ACCOUNT_ID`,
249
252
  `TURBO_TEAM`, `AXIOM_DATASET`) stays out: it lives in 1Password and syncs to a GitHub variable (`repo.variables.sync`),
250
253
  and nothing else carries a copy. `.holocron/org.md` (the agent contract the CLI embeds) is not an area: only
251
254
  `.ts`, `.js`, `.mjs`, `.cjs` and `.json` are read.
@@ -785,7 +788,8 @@ export default defineConfig({
785
788
  Axiom shipping activates when a token (`HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN`
786
789
  → OS keyring `axiom.<org>` → `axiom`) **and** a dataset
787
790
  (`HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET` → `log.axiom.dataset` in
788
- `holocron.config`) both resolve; env vars win. The token is never read from a
791
+ `holocron.config` → the credential chain, where the 1Password-synced
792
+ `AXIOM_DATASET` lives) both resolve; env vars win. The token is never read from a
789
793
  config file.
790
794
 
791
795
  The dataset side of that resolution is **execution-context-aware** (ADR-0012):
package/dist/cli.mjs CHANGED
@@ -20,7 +20,7 @@ import { bumpCatalogPins, discoverWorkspacePackages, parseCatalogs, readPackageJ
20
20
  import { createCliLogger, createCliTelemetry } from "@theholocron/kyber/observability";
21
21
  import { resolveAxiomFromEnv } from "@theholocron/observability/logger";
22
22
  import { Entry, findCredentials } from "@napi-rs/keyring";
23
- import { AuthError, DOTENV_FILE, copyToClipboard, createFeatureResolver, createKeyring, dotenvLine, finishCredentialsFile, hasCredentials, isGitIgnored, readDotenvFile, setCredentials, writeCredentialsFile } from "@theholocron/kyber/secrets";
23
+ import { AuthError, DOTENV_FILE, copyToClipboard, createFeatureResolver, createKeyring, dotenvLine, finishCredentialsFile, hasCredentials, isGitIgnored, readDotenvFile, resolveValue, resolveValue as resolveValue$2, setCredentials, writeCredentialsFile } from "@theholocron/kyber/secrets";
24
24
  import { errorMessage } from "@theholocron/misc-utils";
25
25
  import { pathToFileURL } from "node:url";
26
26
  import { DRY_RUN_NOOP_EXIT_CODE, createCommandRegistry, createMenu, numeric } from "@theholocron/kyber/menu";
@@ -429,6 +429,12 @@ const HOLOCRON_AREAS = [
429
429
  "repo",
430
430
  "org"
431
431
  ];
432
+ /**
433
+ * The areas a config in a subdirectory also reads from the repository root's `.holocron/` (SPEC-0069): only `org`,
434
+ * because its values are the organization's and every config needs them. `repo` and `notifications` describe the
435
+ * repository itself, so an app's config does not take them from the root.
436
+ */
437
+ const SHARED_AREAS = ["org"];
432
438
  // src/config/load-config/place-notifications/place-notifications.ts
433
439
  const isTuple$1 = (entry) => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && typeof entry[1] === "object" && entry[1] !== null && !Array.isArray(entry[1]);
434
440
  const providerName = (entry) => isTuple$1(entry) ? entry[0] : entry;
@@ -494,15 +500,34 @@ function validate(area) {
494
500
  }
495
501
  return area.value;
496
502
  }
503
+ /**
504
+ * The org options of an area and, when the repository root has the same area, the root's under them: an option set in
505
+ * both takes the config's own value, option by option (the root's other options stay). Each file is checked on its own.
506
+ */
507
+ function merge(area) {
508
+ const merged = {};
509
+ for (const layer of area.root ? [area.root, area] : [area]) for (const [provider, options] of Object.entries(validate(layer))) {
510
+ const sourced = merged[provider] ??= {};
511
+ for (const [option, value] of Object.entries(options)) sourced[option] = {
512
+ value,
513
+ path: layer.path
514
+ };
515
+ }
516
+ return merged;
517
+ }
497
518
  /** Fill one entry when it names a provider the area holds; throws when the config already sets one of its options. */
498
- function fill(entry, org, capability, path) {
519
+ function fill(entry, org, capability) {
499
520
  const [provider, options] = isTuple(entry) ? entry : [entry, {}];
500
521
  const values = org[provider];
501
522
  if (values === void 0 || Object.keys(values).length === 0) return entry;
502
- for (const option of Object.keys(values)) if (options[option] !== void 0) throw new ConfigError(`${provider}.${option} is set in providers.${capability} and in ${path}. Set it in one place: remove the inline option or the key from ${path}`);
523
+ const filled = {};
524
+ for (const [option, { value, path }] of Object.entries(values)) {
525
+ if (options[option] !== void 0) throw new ConfigError(`${provider}.${option} is set in providers.${capability} and in ${path}. Set it in one place: remove the inline option or the key from ${path}`);
526
+ filled[option] = value;
527
+ }
503
528
  return [provider, {
504
529
  ...options,
505
- ...values
530
+ ...filled
506
531
  }];
507
532
  }
508
533
  /**
@@ -510,12 +535,14 @@ function fill(entry, org, capability, path) {
510
535
  * `[name, options]` tuple, or either inside a list) that names a provider the file holds gets each option it leaves
511
536
  * out. An option set inline and in the file is a `ConfigError` naming both (no merge, no precedence); a provider the
512
537
  * config does not use is ignored; a provider or option the file lists but `OrgConfig` does not know is an error.
538
+ * When the area also came from the repository root (`area.root`, a config in a subdirectory), the two files combine
539
+ * option by option and the config's own file wins; that is not an error.
513
540
  */
514
541
  function placeOrg(raw, area) {
515
- const org = validate(area);
542
+ const org = merge(area);
516
543
  if (raw.providers === void 0) return raw;
517
544
  const providers = { ...raw.providers };
518
- for (const [capability, entry] of Object.entries(raw.providers)) providers[capability] = Array.isArray(entry) && !isTuple(entry) ? entry.map((item) => fill(item, org, capability, area.path)) : fill(entry, org, capability, area.path);
545
+ for (const [capability, entry] of Object.entries(raw.providers)) providers[capability] = Array.isArray(entry) && !isTuple(entry) ? entry.map((item) => fill(item, org, capability)) : fill(entry, org, capability);
519
546
  return {
520
547
  ...raw,
521
548
  providers
@@ -571,6 +598,7 @@ function placeAreas(areas, raw) {
571
598
  const system$1 = createConfigSystem({
572
599
  name: "holocron",
573
600
  areas: HOLOCRON_AREAS,
601
+ shared: SHARED_AREAS,
574
602
  place: placeAreas,
575
603
  derive: deriveDefaults$1,
576
604
  resolve: resolveConfig,
@@ -730,8 +758,10 @@ function commandsInContext(context) {
730
758
  * traces, errors, structured context that routes to Axiom. It runs in
731
759
  * parallel to `print` (user-facing UX output) and does not replace it.
732
760
  */
733
- const env$8 = createEnvLookup();
734
- const holocronEnv$1 = withEnvPrefix(env$8, "HOLOCRON");
761
+ const env$9 = createEnvLookup();
762
+ /** The one definition of the CLI's variable prefix: `HOLOCRON_<NAME>` is tried before the bare `<NAME>`. */
763
+ const PREFIX$1 = "HOLOCRON";
764
+ const holocronEnv$1 = withEnvPrefix(env$9, PREFIX$1);
735
765
  /**
736
766
  * Dataset for `global`-context commands (`clone`, `auth set`, `upgrade
737
767
  * node`, …) — ADR-0012. These commands aren't "about" any repo, so their
@@ -743,6 +773,15 @@ const holocronEnv$1 = withEnvPrefix(env$8, "HOLOCRON");
743
773
  */
744
774
  const GLOBAL_AXIOM_DATASET = "holocron-global";
745
775
  /**
776
+ * The dataset of a non-global command: the process environment (`HOLOCRON_AXIOM_DATASET`, then the unprefixed
777
+ * `AXIOM_DATASET`, through the prefix lookup), then `log.axiom.dataset`, then the credential chain, which is asked for
778
+ * the same pair of names. `resolveValue` takes a plain list of names, so the pair is built from {@link PREFIX} instead of
779
+ * adding a prefix option to kyber for one caller.
780
+ */
781
+ function resolveCliDataset(opts) {
782
+ return holocronEnv$1.get("AXIOM_DATASET") ?? opts.configAxiomDataset ?? resolveValue$2([`${PREFIX$1}_AXIOM_DATASET`, "AXIOM_DATASET"]);
783
+ }
784
+ /**
746
785
  * Resolve Axiom credentials for the CLI.
747
786
  *
748
787
  * A `global`-context command (ADR-0012) always resolves to
@@ -752,8 +791,11 @@ const GLOBAL_AXIOM_DATASET = "holocron-global";
752
791
  * right answer. Everything else keeps the existing chain: env vars win
753
792
  * (same contract as `@theholocron/observability`'s `resolveAxiomFromEnv`),
754
793
  * falling back to the CLI-only bridge that pairs the OS-keyring token
755
- * (`axiom.<org>` then bare `axiom`) with a dataset from
756
- * `HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET` or `log.axiom.dataset`.
794
+ * (`axiom.<org>` then bare `axiom`) with a dataset from the process
795
+ * environment (`HOLOCRON_AXIOM_DATASET`, then `AXIOM_DATASET`), then
796
+ * `log.axiom.dataset`, then the credential chain (`resolveValue`, which finds the
797
+ * 1Password-synced `AXIOM_DATASET`). The config sits before the chain so a local
798
+ * run with no `.envrc` still ships to `holocron-local`, not to the CI dataset.
757
799
  * Returns `undefined` unless both a token and a dataset are found.
758
800
  */
759
801
  function resolveCliAxiom(opts, ctx) {
@@ -762,9 +804,9 @@ function resolveCliAxiom(opts, ctx) {
762
804
  const fromEnv = resolveAxiomFromEnv();
763
805
  if (fromEnv) return fromEnv;
764
806
  }
765
- const dataset = isGlobal ? GLOBAL_AXIOM_DATASET : holocronEnv$1.get("AXIOM_DATASET") ?? opts.configAxiomDataset;
807
+ const dataset = isGlobal ? GLOBAL_AXIOM_DATASET : resolveCliDataset(opts);
766
808
  if (!dataset) return void 0;
767
- const org = opts.org ?? env$8.get("HOLOCRON_ORG");
809
+ const org = opts.org ?? env$9.get(`${PREFIX$1}_ORG`);
768
810
  const token = holocronEnv$1.get("AXIOM_TOKEN") || (org ? keyring.get(`axiom.${org}`) : null) || keyring.get("axiom");
769
811
  return token ? {
770
812
  dataset,
@@ -772,7 +814,7 @@ function resolveCliAxiom(opts, ctx) {
772
814
  } : void 0;
773
815
  }
774
816
  const logger = createCliLogger({
775
- envPrefix: "HOLOCRON",
817
+ envPrefix: PREFIX$1,
776
818
  resolveAxiom: resolveCliAxiom
777
819
  });
778
820
  /**
@@ -858,7 +900,7 @@ const endSession = telemetry.endSession;
858
900
  const flush = telemetry.flush;
859
901
  telemetry.resetTelemetry;
860
902
  // src/commands/resolve-org/resolve-org.ts
861
- const env$7 = createEnvLookup();
903
+ const env$8 = createEnvLookup();
862
904
  /**
863
905
  * Resolves the active org in priority order:
864
906
  * 1. `--org` CLI flag
@@ -866,7 +908,7 @@ const env$7 = createEnvLookup();
866
908
  * 3. `org` from `holocron.config.ts`
867
909
  */
868
910
  function resolveOrg(argv, config) {
869
- return argv.org ?? env$7.get("HOLOCRON_ORG") ?? config.org;
911
+ return argv.org ?? env$8.get("HOLOCRON_ORG") ?? config.org;
870
912
  }
871
913
  // src/commands/apply-resolved-config/apply-resolved-config.ts
872
914
  /**
@@ -2244,7 +2286,7 @@ const projectReconcileEntry = {
2244
2286
  supportsDryRun: true
2245
2287
  };
2246
2288
  // src/commands/publish/publish.entry.ts
2247
- const env$6 = createEnvLookup();
2289
+ const env$7 = createEnvLookup();
2248
2290
  const PUBLISH_TAG_OPTION = {
2249
2291
  key: "tag",
2250
2292
  flag: "--tag",
@@ -2257,7 +2299,7 @@ const PUBLISH_OTP_OPTION = {
2257
2299
  type: "password",
2258
2300
  secret: true,
2259
2301
  askLast: true,
2260
- required: Boolean(env$6.get("HOLOCRON_NPM_ENFORCE_2FA")),
2302
+ required: Boolean(env$7.get("HOLOCRON_NPM_ENFORCE_2FA")),
2261
2303
  message: "One-time password (2FA), if npm requires it for this publish:"
2262
2304
  };
2263
2305
  // src/interactive-menu/command-catalog/command-catalog.ts
@@ -3019,7 +3061,7 @@ async function runClone(input) {
3019
3061
  };
3020
3062
  }
3021
3063
  // src/commands/clone/clone.command.ts
3022
- const env$5 = createEnvLookup();
3064
+ const env$6 = createEnvLookup();
3023
3065
  const resolveCloneToken = createFeatureResolver$1({
3024
3066
  envName: "HOLOCRON_READ_TOKEN",
3025
3067
  keyringKey: "github.read"
@@ -3057,7 +3099,7 @@ const cloneCommand = {
3057
3099
  } } : {},
3058
3100
  confirmOpen: async (openTarget, moreToCome) => {
3059
3101
  if (!process.stdin.isTTY) return;
3060
- if (moreToCome && env$5.get(DRY_RUN_PREVIEW_ENV_VAR) === "1") return;
3102
+ if (moreToCome && env$6.get(DRY_RUN_PREVIEW_ENV_VAR) === "1") return;
3061
3103
  if (await confirm({
3062
3104
  message: `Open ${openTarget}?`,
3063
3105
  default: false
@@ -3067,7 +3109,7 @@ const cloneCommand = {
3067
3109
  if (report.status === "fail") {
3068
3110
  if (report.message) reportError(`clone: ${report.message}`);
3069
3111
  process.exitCode = 1;
3070
- } else if (report.status === "dry-run" && report.cloned === 0 && env$5.get(DRY_RUN_PREVIEW_ENV_VAR) === "1") process.exitCode = DRY_RUN_NOOP_EXIT_CODE;
3112
+ } else if (report.status === "dry-run" && report.cloned === 0 && env$6.get(DRY_RUN_PREVIEW_ENV_VAR) === "1") process.exitCode = DRY_RUN_NOOP_EXIT_CODE;
3071
3113
  }
3072
3114
  };
3073
3115
  // src/commands/config-show/config-show.args.ts
@@ -3798,6 +3840,7 @@ async function runDevServe(input) {
3798
3840
  });
3799
3841
  }
3800
3842
  // src/commands/dev-serve/dev-serve.command.ts
3843
+ const env$5 = createEnvLookup();
3801
3844
  const devServeCommand = {
3802
3845
  command: "serve",
3803
3846
  describe: "Serve the handler `dev.serve` names on PORT: the application `holocron dev` runs when it is configured, not usually run by hand",
@@ -3813,7 +3856,7 @@ const devServeCommand = {
3813
3856
  cwd: argv.cwd,
3814
3857
  environment: dev.environment ?? "",
3815
3858
  serve: dev.serve,
3816
- port: Number(process.env["PORT"] ?? dev.port ?? 3e3)
3859
+ port: Number(env$5.get("PORT") ?? dev.port ?? 3e3)
3817
3860
  });
3818
3861
  } catch (err) {
3819
3862
  reportError(`dev serve: ${errorMessage(err)}`);
@@ -10699,6 +10742,36 @@ async function runMonitoringRunResolved(input) {
10699
10742
  ...input.runCheck ? { runCheck: input.runCheck } : {}
10700
10743
  });
10701
10744
  }
10745
+ // src/commands/resolve-vercel-credentials/resolve-vercel-credentials.ts
10746
+ /** The `teamId` of the first configured `vercel` provider (the loader fills it from `.holocron/org.ts`), if any. */
10747
+ function configuredTeamId(resolved) {
10748
+ for (const entry of Object.values(resolved?.providers ?? {})) {
10749
+ const tuples = entry.cardinality === "single" ? [entry.tuple] : entry.tuples;
10750
+ for (const tuple of tuples) {
10751
+ const teamId = tuple.provider === "vercel" ? tuple.options["teamId"] : void 0;
10752
+ if (typeof teamId === "string" && teamId !== "") return teamId;
10753
+ }
10754
+ }
10755
+ }
10756
+ /**
10757
+ * Reads the Vercel token, team id and Deployment Protection bypass secret through the credential chain
10758
+ * (`resolveValue`: the environment, then the `credentials` providers) instead of `process.env`. The environment's
10759
+ * `VERCEL_TEAM_ID` wins over the configured provider's `teamId`, so the override CI passes keeps working. A value that
10760
+ * is not set is left out, so the result spreads straight into the input of `resolveVercelBypassHeaders`.
10761
+ *
10762
+ * @param resolved - The loaded config, when the command has one. `monitoring run-resolved` loads none.
10763
+ * @param env - The environment to read. Default `process.env`; a test passes its own.
10764
+ */
10765
+ function resolveVercelCredentials(resolved, env) {
10766
+ const vercelToken = resolveValue(["VERCEL_TOKEN"], env);
10767
+ const vercelTeamId = resolveValue(["VERCEL_TEAM_ID"], env) ?? configuredTeamId(resolved);
10768
+ const bypassSecret = resolveValue(["VERCEL_PROTECTION_BYPASS_SECRET"], env);
10769
+ return {
10770
+ ...vercelToken ? { vercelToken } : {},
10771
+ ...vercelTeamId ? { vercelTeamId } : {},
10772
+ ...bypassSecret ? { bypassSecret } : {}
10773
+ };
10774
+ }
10702
10775
  // src/commands/monitoring-check/monitoring-check.args.ts
10703
10776
  const monitoringCheckArgs = (y) => y.positional("url", {
10704
10777
  type: "string",
@@ -10721,9 +10794,7 @@ const monitoringCheckCommand = {
10721
10794
  const { headers } = await resolveVercelBypassHeaders({
10722
10795
  url,
10723
10796
  ...argv.vercelProject ? { vercelProject: argv.vercelProject } : {},
10724
- ...process.env["VERCEL_TOKEN"] ? { vercelToken: process.env["VERCEL_TOKEN"] } : {},
10725
- ...process.env["VERCEL_TEAM_ID"] ? { vercelTeamId: process.env["VERCEL_TEAM_ID"] } : {},
10726
- ...process.env["VERCEL_PROTECTION_BYPASS_SECRET"] ? { bypassSecret: process.env["VERCEL_PROTECTION_BYPASS_SECRET"] } : {}
10797
+ ...resolveVercelCredentials(loaded.resolved)
10727
10798
  });
10728
10799
  if ((await runMonitoringCheck({
10729
10800
  loaded,
@@ -10811,9 +10882,7 @@ const monitoringRunResolvedCommand = {
10811
10882
  checks: JSON.parse(readFileSync(argv.checksFile, "utf8")),
10812
10883
  url: argv.url,
10813
10884
  ...argv.vercelProject ? { vercelProject: argv.vercelProject } : {},
10814
- ...process.env["VERCEL_TOKEN"] ? { vercelToken: process.env["VERCEL_TOKEN"] } : {},
10815
- ...process.env["VERCEL_TEAM_ID"] ? { vercelTeamId: process.env["VERCEL_TEAM_ID"] } : {},
10816
- ...process.env["VERCEL_PROTECTION_BYPASS_SECRET"] ? { bypassSecret: process.env["VERCEL_PROTECTION_BYPASS_SECRET"] } : {}
10885
+ ...resolveVercelCredentials()
10817
10886
  })).status === "fail") process.exitCode = 1;
10818
10887
  }
10819
10888
  };
@@ -15246,7 +15315,7 @@ function runTypedoc(repoRoot) {
15246
15315
  function realDiff(repoRoot) {
15247
15316
  /* v8 ignore start -- runs the real git; the probe is tested with an injected diff */
15248
15317
  return () => {
15249
- const base = process.env["BASE_SHA"] || "origin/alpha";
15318
+ const base = createEnvLookup().get("BASE_SHA") ?? "origin/alpha";
15250
15319
  return execFileSync("git", [
15251
15320
  "diff",
15252
15321
  "-U0",
@@ -20636,7 +20705,7 @@ async function runSecretSet(input) {
20636
20705
  const dryRun = input.context.dryRun ?? false;
20637
20706
  const scope = input.scope ?? { kind: "repo" };
20638
20707
  if (!loader.has("secrets")) throw new Error("`secrets` capability is not configured — add a `secrets` provider to holocron.config.json");
20639
- const value = await resolveValue(input);
20708
+ const value = await resolveValue$1(input);
20640
20709
  if (!value) throw new Error(`no value for secret \`${input.name}\` — pass it positionally, via --from-stdin, --from-env <NAME>, or set $${input.name} in the environment`);
20641
20710
  print(`Holocron secret set — ${input.name} (${describeScope$1(scope)})${dryRun ? " (dry-run)" : ""}`);
20642
20711
  if (dryRun) {
@@ -20680,7 +20749,7 @@ async function runSecretSet(input) {
20680
20749
  };
20681
20750
  }
20682
20751
  }
20683
- async function resolveValue(input) {
20752
+ async function resolveValue$1(input) {
20684
20753
  if (input.value) return input.value;
20685
20754
  if (input.fromStdin) return (await (input.readStdin ?? defaultReadStdin)()).replace(/\r?\n$/, "");
20686
20755
  if (input.fromEnv) return env$1.get(input.fromEnv);