@theholocron/cli 5.0.0-alpha.360 → 5.0.0-alpha.362

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
@@ -239,8 +239,9 @@ repo's `.holocron/repo.ts` holds `teams`, `topics`, `variables` and `secrets`, n
239
239
  `satisfies RepoConfig` (a type-only import).
240
240
 
241
241
  **The `org` area** (#1820). The organization's constants that are provider options and that CI does not need:
242
- `.holocron/org.ts` is `{ cloudflare: { accountId }, vercel: { teamId }, checkly: { accountId }, sentry: { org } }` (typed with
243
- `satisfies OrgConfig`). The loader fills each of these into every provider entry of that name that leaves the option
242
+ `.holocron/org.ts` is `{ domain, cloudflare: { accountId }, vercel: { teamId }, checkly: { accountId }, sentry: { org } }` (typed with
243
+ `satisfies OrgConfig`). `domain` is the org's DNS zone: the loader sets `domain` on a config that leaves it out (set in
244
+ both is an error), and a file that builds a hostname while it is evaluated imports it (`import org from "./org.js"`). The loader fills each of these into every provider entry of that name that leaves the option
244
245
  out, so the config can say `deployment: ["vercel", { domain }]`, `monitoring: "checkly"` and `errors: "sentry"`. The same option set inline
245
246
  and in the file is an error that names both (`vercel.teamId is set in providers.deployment and in
246
247
  .holocron/org.ts`), with no merge and no precedence. A provider key or an option the area does not know is an error; a
@@ -249,7 +250,7 @@ also reads the repository root's `.holocron/org.ts` (the nearest ancestor with a
249
250
  `.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
251
  root file needs no copy in the app. The other areas (`repo`, `notifications`) describe the repository and are not
251
252
  shared. Anything CI needs (`CLOUDFLARE_ACCOUNT_ID`,
252
- `TURBO_TEAM`, `AXIOM_DATASET`) stays out: it lives in 1Password and syncs to a GitHub variable (`repo.variables.sync`),
253
+ `TURBO_TEAM`, `HOLOCRON_AXIOM_DATASET`) stays out: it lives in 1Password and syncs to a GitHub variable (`repo.variables.sync`),
253
254
  and nothing else carries a copy. `.holocron/org.md` (the agent contract the CLI embeds) is not an area: only
254
255
  `.ts`, `.js`, `.mjs`, `.cjs` and `.json` are read.
255
256
 
@@ -793,14 +794,14 @@ Axiom shipping activates when a token (`HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN`
793
794
  `AXIOM_DATASET` lives) both resolve; env vars win. The token is never read from a
794
795
  config file.
795
796
 
796
- The dataset side of that resolution is **execution-context-aware** (ADR-0012):
797
- a `global`-context command (`clone`, `new`, `auth set`, `upgrade node`, `plugin
798
- create`, …) always ships to holocron's own dataset regardless of `$PWD` — it
799
- isn't "about" any repo, so routing it through whichever repo's `.envrc`
800
- happens to be active would be wrong. `repo-aware` / `workspace` commands
801
- (`doctor`, `deploy`, `sync`, …) keep the env-var/config chain above, so a
802
- per-repo `HOLOCRON_AXIOM_DATASET` — e.g. via a `.envrc` + `direnv` — separates
803
- each consuming repo's logs. See the [logging guide](https://docs.theholocron.dev/holocron/logging/).
797
+ Each service has one dataset for all its environments (ADR-0019; the CLI's is `holocron`); each line carries `env`
798
+ (`local`, `development`, `ci`, `test`, `production`), so a query filters by it.
799
+ `log.axiom.dataset` is only a per-repo override. The dataset side of the
800
+ resolution is **execution-context-aware** (ADR-0012): a `global`-context command
801
+ (`clone`, `new`, `auth set`, `upgrade node`, `plugin create`, …) is not "about"
802
+ any repo, so it skips the repo's `log.axiom.dataset` and uses the CLI's dataset
803
+ from the environment or credential chain. `repo-aware` / `workspace` commands
804
+ (`doctor`, `deploy`, `sync`, …) keep the full chain above. See the [logging guide](https://docs.theholocron.dev/holocron/logging/).
804
805
 
805
806
  ### Telemetry
806
807
 
package/dist/cli.mjs CHANGED
@@ -503,10 +503,15 @@ const ORG_OPTIONS = {
503
503
  };
504
504
  const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
505
505
  const isTuple = (entry) => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && isObject(entry[1]);
506
- /** Check the shape of the area file: a closed list of providers, each with a closed list of string options. */
506
+ /**
507
+ * Check the shape of the area file: the top-level `domain` (a non-empty string), then a closed list of providers,
508
+ * each with a closed list of string options.
509
+ */
507
510
  function validate(area) {
508
511
  if (!isObject(area.value)) throw new ConfigError(`${area.path} must export the org settings as an object`);
509
- for (const [provider, options] of Object.entries(area.value)) {
512
+ const { domain, ...rest } = area.value;
513
+ if (domain !== void 0 && (typeof domain !== "string" || domain === "")) throw new ConfigError(`${area.path}: "domain" must be a non-empty string`);
514
+ for (const [provider, options] of Object.entries(rest)) {
510
515
  const allowed = ORG_OPTIONS[provider];
511
516
  if (allowed === void 0) throw new ConfigError(`${area.path} has an unknown provider "${provider}". Known: ${Object.keys(ORG_OPTIONS).join(", ")}`);
512
517
  if (!isObject(options)) throw new ConfigError(`${area.path}: "${provider}" must be an object of options`);
@@ -515,22 +520,36 @@ function validate(area) {
515
520
  if (typeof value !== "string" || value === "") throw new ConfigError(`${area.path}: "${provider}.${option}" must be a non-empty string`);
516
521
  }
517
522
  }
518
- return area.value;
523
+ return {
524
+ ...domain !== void 0 ? { domain } : {},
525
+ providers: rest
526
+ };
519
527
  }
520
528
  /**
521
529
  * The org options of an area and, when the repository root has the same area, the root's under them: an option set in
522
530
  * both takes the config's own value, option by option (the root's other options stay). Each file is checked on its own.
523
531
  */
524
532
  function merge(area) {
525
- const merged = {};
526
- for (const layer of area.root ? [area.root, area] : [area]) for (const [provider, options] of Object.entries(validate(layer))) {
527
- const sourced = merged[provider] ??= {};
528
- for (const [option, value] of Object.entries(options)) sourced[option] = {
529
- value,
533
+ const providers = {};
534
+ let domain;
535
+ for (const layer of area.root ? [area.root, area] : [area]) {
536
+ const checked = validate(layer);
537
+ if (checked.domain !== void 0) domain = {
538
+ value: checked.domain,
530
539
  path: layer.path
531
540
  };
541
+ for (const [provider, options] of Object.entries(checked.providers)) {
542
+ const sourced = providers[provider] ??= {};
543
+ for (const [option, value] of Object.entries(options)) sourced[option] = {
544
+ value,
545
+ path: layer.path
546
+ };
547
+ }
532
548
  }
533
- return merged;
549
+ return {
550
+ ...domain ? { domain } : {},
551
+ providers
552
+ };
534
553
  }
535
554
  /** Fill one entry when it names a provider the area holds; throws when the config already sets one of its options. */
536
555
  function fill(entry, org, capability) {
@@ -548,7 +567,9 @@ function fill(entry, org, capability) {
548
567
  }];
549
568
  }
550
569
  /**
551
- * Fill the provider options of `.holocron/org.*` into the providers the config uses. A provider entry (a name, a
570
+ * Fill `.holocron/org.*` into the config. Its top-level `domain` (the org's zone) is set on a config that leaves
571
+ * `domain` out; set inline and in the file it is a `ConfigError` naming both. Its provider options go into the
572
+ * providers the config uses. A provider entry (a name, a
552
573
  * `[name, options]` tuple, or either inside a list) that names a provider the file holds gets each option it leaves
553
574
  * out. An option set inline and in the file is a `ConfigError` naming both (no merge, no precedence); a provider the
554
575
  * config does not use is ignored; a provider or option the file lists but `OrgConfig` does not know is an error.
@@ -556,12 +577,17 @@ function fill(entry, org, capability) {
556
577
  * option by option and the config's own file wins; that is not an error.
557
578
  */
558
579
  function placeOrg(raw, area) {
559
- const org = merge(area);
560
- if (raw.providers === void 0) return raw;
561
- const providers = { ...raw.providers };
562
- 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);
563
- return {
580
+ const { domain, providers: org } = merge(area);
581
+ if (domain !== void 0 && raw.domain !== void 0) throw new ConfigError(`domain is set in the config and in ${domain.path}. Set it in one place: remove the inline value or the key from ${domain.path}`);
582
+ const withDomain = domain === void 0 ? raw : {
564
583
  ...raw,
584
+ domain: domain.value
585
+ };
586
+ if (withDomain.providers === void 0) return withDomain;
587
+ const providers = { ...withDomain.providers };
588
+ for (const [capability, entry] of Object.entries(withDomain.providers)) providers[capability] = Array.isArray(entry) && !isTuple(entry) ? entry.map((item) => fill(item, org, capability)) : fill(entry, org, capability);
589
+ return {
590
+ ...withDomain,
565
591
  providers
566
592
  };
567
593
  }
@@ -781,48 +807,31 @@ const env$9 = createEnvLookup();
781
807
  const PREFIX$1 = "HOLOCRON";
782
808
  const holocronEnv$1 = withEnvPrefix(env$9, PREFIX$1);
783
809
  /**
784
- * Dataset for `global`-context commands (`clone`, `auth set`, `upgrade
785
- * node`, …) — ADR-0012. These commands aren't "about" any repo, so their
786
- * logs must never depend on `$PWD` or which repo's `.envrc` happens to be
787
- * active; they always ship to holocron's own dataset instead of whatever
788
- * `HOLOCRON_AXIOM_DATASET` resolves to locally. Mirrors
789
- * `resolve-telemetry.ts`'s `FALLBACK_DSN` — a holocron-owned default, not a
790
- * per-repo override.
791
- */
792
- const GLOBAL_AXIOM_DATASET = "holocron-global";
793
- /**
794
- * The dataset of a non-global command: the process environment (`HOLOCRON_AXIOM_DATASET`, then the unprefixed
795
- * `AXIOM_DATASET`, through the prefix lookup), then `log.axiom.dataset`, then the credential chain, which is asked for
796
- * the same pair of names. `resolveValue` takes a plain list of names, so the pair is built from {@link PREFIX} instead of
810
+ * The CLI's Axiom dataset (`holocron`; each service has its own): the process environment (`HOLOCRON_AXIOM_DATASET`, then the unprefixed `AXIOM_DATASET`,
811
+ * through the prefix lookup), then the repo's `log.axiom.dataset`, then the credential chain, which is asked for the
812
+ * same pair of names. `resolveValue` takes a plain list of names, so the pair is built from {@link PREFIX} instead of
797
813
  * adding a prefix option to kyber for one caller.
814
+ *
815
+ * A service's environments ship to the same dataset and are told apart by the `env` field on each line (ADR-0019). The
816
+ * config dataset is only a per-repo override, so a `global`-context command (`clone`, `auth set`, `upgrade node`, ...,
817
+ * ADR-0012) leaves it out: it is not about any repo, and the repo it happens to run in must not choose where its
818
+ * lines go.
798
819
  */
799
- function resolveCliDataset(opts) {
800
- return holocronEnv$1.get("AXIOM_DATASET") ?? opts.configAxiomDataset ?? resolveValue$2([`${PREFIX$1}_AXIOM_DATASET`, "AXIOM_DATASET"]);
820
+ function resolveCliDataset(opts, isGlobal) {
821
+ return holocronEnv$1.get("AXIOM_DATASET") ?? (isGlobal ? void 0 : opts.configAxiomDataset) ?? resolveValue$2([`${PREFIX$1}_AXIOM_DATASET`, "AXIOM_DATASET"]);
801
822
  }
802
823
  /**
803
824
  * Resolve Axiom credentials for the CLI.
804
825
  *
805
- * A `global`-context command (ADR-0012) always resolves to
806
- * {@link GLOBAL_AXIOM_DATASET}, ignoring `HOLOCRON_AXIOM_DATASET` /
807
- * `AXIOM_DATASET` / `holocron.config` `log.axiom.dataset` entirely — it
808
- * isn't "about" any repo, so the active directory's dataset is never the
809
- * right answer. Everything else keeps the existing chain: env vars win
810
- * (same contract as `@theholocron/observability`'s `resolveAxiomFromEnv`),
811
- * falling back to the CLI-only bridge that pairs the OS-keyring token
812
- * (`axiom.<org>` then bare `axiom`) with a dataset from the process
813
- * environment (`HOLOCRON_AXIOM_DATASET`, then `AXIOM_DATASET`), then
814
- * `log.axiom.dataset`, then the credential chain (`resolveValue`, which finds the
815
- * 1Password-synced `AXIOM_DATASET`). The config sits before the chain so a local
816
- * run with no `.envrc` still ships to `holocron-local`, not to the CI dataset.
817
- * Returns `undefined` unless both a token and a dataset are found.
826
+ * Env vars win (same contract as `@theholocron/observability`'s `resolveAxiomFromEnv`), falling back to the CLI-only
827
+ * bridge that pairs the OS-keyring token (`axiom.<org>` then bare `axiom`) with the dataset from
828
+ * {@link resolveCliDataset}. Returns `undefined` unless both a token and a dataset are found, so a local run with
829
+ * neither stays off Axiom.
818
830
  */
819
831
  function resolveCliAxiom(opts, ctx) {
820
- const isGlobal = contextForCommand(ctx.command ?? "") === "global";
821
- if (!isGlobal) {
822
- const fromEnv = resolveAxiomFromEnv();
823
- if (fromEnv) return fromEnv;
824
- }
825
- const dataset = isGlobal ? GLOBAL_AXIOM_DATASET : resolveCliDataset(opts);
832
+ const fromEnv = resolveAxiomFromEnv();
833
+ if (fromEnv) return fromEnv;
834
+ const dataset = resolveCliDataset(opts, contextForCommand(ctx.command ?? "") === "global");
826
835
  if (!dataset) return void 0;
827
836
  const org = opts.org ?? env$9.get(`${PREFIX$1}_ORG`);
828
837
  const token = holocronEnv$1.get("AXIOM_TOKEN") || (org ? keyring.get(`axiom.${org}`) : null) || keyring.get("axiom");
@@ -4031,7 +4040,7 @@ async function runTunnelUp(input) {
4031
4040
  service
4032
4041
  });
4033
4042
  } catch (err) {
4034
- row(false, `tunnel ${input.name}`, errorMessage(err));
4043
+ row(false, `tunnel ${input.name}`, describeError(err));
4035
4044
  return finish("fail");
4036
4045
  }
4037
4046
  const did = [ensured.created ? "created" : "found", ensured.configured ? "route set" : "route in step"];
@@ -4044,7 +4053,7 @@ async function runTunnelUp(input) {
4044
4053
  proxied: true
4045
4054
  });
4046
4055
  } catch (err) {
4047
- row(false, `dns ${input.hostname}`, errorMessage(err));
4056
+ row(false, `dns ${input.hostname}`, describeError(err));
4048
4057
  return finish("fail", { tunnelId: ensured.id });
4049
4058
  }
4050
4059
  row(true, `dns ${input.hostname}`, "proxied CNAME to the tunnel");
@@ -4063,7 +4072,7 @@ async function runTunnelUp(input) {
4063
4072
  print(`running cloudflared (Ctrl-C stops it): ${url} to ${service}`);
4064
4073
  exitCode = await (input.runConnector ?? runCloudflared)(token);
4065
4074
  } catch (err) {
4066
- row(false, "cloudflared", errorMessage(err));
4075
+ row(false, "cloudflared", describeError(err));
4067
4076
  return finish("fail", {
4068
4077
  tunnelId: ensured.id,
4069
4078
  url
@@ -4192,7 +4201,7 @@ async function runDev(input) {
4192
4201
  try {
4193
4202
  values = await vault.readEnvironment(input.environment);
4194
4203
  } catch (err) {
4195
- row(false, `vault ${input.environment}`, errorMessage(err));
4204
+ row(false, `vault ${input.environment}`, describeError(err));
4196
4205
  return finish("fail");
4197
4206
  }
4198
4207
  row(true, `vault ${input.environment}`, `${Object.keys(values).length} variables, passed to the application`);
@@ -4200,7 +4209,7 @@ async function runDev(input) {
4200
4209
  try {
4201
4210
  token = await loader.get("tunnels").tunnelToken(tunnel.tunnelId);
4202
4211
  } catch (err) {
4203
- row(false, "cloudflared", errorMessage(err));
4212
+ row(false, "cloudflared", describeError(err));
4204
4213
  return finish("fail");
4205
4214
  }
4206
4215
  print("");
@@ -4228,7 +4237,7 @@ async function runDev(input) {
4228
4237
  }
4229
4238
  }));
4230
4239
  } catch (err) {
4231
- row(false, "dev", errorMessage(err));
4240
+ row(false, "dev", describeError(err));
4232
4241
  return finish("fail");
4233
4242
  }
4234
4243
  row(exitCode === 0, "dev", `ended with ${exitCode}`);
@@ -19023,11 +19032,18 @@ async function runSetup(input) {
19023
19032
  if (loader.has("logs")) {
19024
19033
  const logs = loader.get("logs");
19025
19034
  print(style.step("logs"));
19026
- if (logs.ensureDataset) for (const dataset of ["holocron-ci", "holocron-local"]) {
19027
- steps.push(await runStep("logs", `ensureDataset ${dataset}`, dryRun, async () => {
19035
+ if (logs.ensureDataset) {
19036
+ const dataset = withEnvPrefix(createEnvLookup(), "HOLOCRON").get("AXIOM_DATASET");
19037
+ if (dataset) steps.push(await runStep("logs", `ensureDataset ${dataset}`, dryRun, async () => {
19028
19038
  const result = await logs.ensureDataset(dataset);
19029
19039
  return `${dataset} ${result.alreadyExists ? "exists" : "created"}`;
19030
19040
  }));
19041
+ else steps.push({
19042
+ capability: "logs",
19043
+ step: "ensureDataset",
19044
+ status: "skip",
19045
+ message: "no dataset named (set HOLOCRON_AXIOM_DATASET or AXIOM_DATASET)"
19046
+ });
19031
19047
  print(formatStep(steps[steps.length - 1]));
19032
19048
  }
19033
19049
  }