@theholocron/cli 5.0.0-alpha.115 → 5.0.0-alpha.117

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/dist/cli.mjs CHANGED
@@ -11,6 +11,7 @@ import { AuthError, ProviderApiError, ProviderApiError as ProviderApiError$1, cr
11
11
  import { createEnvLookup } from "@theholocron/env-utils";
12
12
  import { Entry, findCredentials } from "@napi-rs/keyring";
13
13
  import { pathToFileURL } from "node:url";
14
+ import { errorMessage } from "@theholocron/misc-utils";
14
15
  import { createLogger, parseLogLevel, resolveAxiomFromEnv } from "@theholocron/observability/logger";
15
16
  import ora from "ora";
16
17
  import chalk from "chalk";
@@ -494,7 +495,7 @@ var PluginLoader = class {
494
495
  /** Internal — invoke a plugin's capability factory and return the impl. */
495
496
  async loadOne(key, tuple) {
496
497
  const mod = await this.importer(tuple.packageName).catch((err) => {
497
- throw new LoaderError(`failed to import \`${tuple.packageName}\` for capability \`${key}\`: ${err instanceof Error ? err.message : String(err)}`);
498
+ throw new LoaderError(`failed to import \`${tuple.packageName}\` for capability \`${key}\`: ${errorMessage(err)}`);
498
499
  });
499
500
  if (isPluginModule(mod)) {
500
501
  const effectiveToken = this.context.cliTokens?.[tuple.provider] ?? this.context.cliToken;
@@ -738,7 +739,7 @@ async function runAuthSet(input) {
738
739
  subject = verified.subject;
739
740
  } else print(style.warn(`${provider} plugin has no verifyToken; storing without verification`));
740
741
  } catch (err) {
741
- const msg = err instanceof Error ? err.message : String(err);
742
+ const msg = errorMessage(err);
742
743
  print(style.warn(`cannot verify token — failed to load ${packageName}: ${msg}`));
743
744
  print(style.hint(` storing token anyway; run 'holocron auth check ${provider}' once the plugin is installed`));
744
745
  }
@@ -855,7 +856,7 @@ async function runAuthCheck(input) {
855
856
  message: verified.message
856
857
  };
857
858
  } catch (err) {
858
- const msg = err instanceof Error ? err.message : String(err);
859
+ const msg = errorMessage(err);
859
860
  if (isModuleNotFound(err)) {
860
861
  print(style.warn(`${keyringKey}: token present — verification skipped (plugin not available here)`));
861
862
  logger.info({
@@ -954,7 +955,7 @@ async function runCleanupPreview(input) {
954
955
  try {
955
956
  pr = await source.getPullRequest(input.prNumber, input.repo);
956
957
  } catch (err) {
957
- const message = err instanceof Error ? err.message : String(err);
958
+ const message = errorMessage(err);
958
959
  throw new Error(`Failed to fetch PR #${input.prNumber}: ${message}`, { cause: err });
959
960
  }
960
961
  const branch = `${(input.repo ?? input.loaded.resolved.repo?.name ?? "").split("/").pop()}-pr-${pr.number}`;
@@ -971,7 +972,7 @@ async function runCleanupPreview(input) {
971
972
  try {
972
973
  deployments = await deploy.listPreviewDeployments(input.project, branch);
973
974
  } catch (err) {
974
- const message = err instanceof Error ? err.message : String(err);
975
+ const message = errorMessage(err);
975
976
  throw new Error(`Failed to list deployments: ${message}`, { cause: err });
976
977
  }
977
978
  if (deployments.length === 0) {
@@ -1050,7 +1051,7 @@ async function runCleanupPreview(input) {
1050
1051
  status: "ok"
1051
1052
  };
1052
1053
  } catch (err) {
1053
- const message = err instanceof Error ? err.message : String(err);
1054
+ const message = errorMessage(err);
1054
1055
  print(style.fail(message));
1055
1056
  logger.warn({
1056
1057
  pr: pr.number,
@@ -1119,7 +1120,7 @@ async function runClone(input) {
1119
1120
  try {
1120
1121
  repos = await listOrgRepos(input.org, input.token, fetchFn);
1121
1122
  } catch (err) {
1122
- const message = err instanceof Error ? err.message : String(err);
1123
+ const message = errorMessage(err);
1123
1124
  logger.warn({
1124
1125
  org: input.org,
1125
1126
  reason: message
@@ -1159,7 +1160,7 @@ async function runClone(input) {
1159
1160
  try {
1160
1161
  encodedToken = encodeTokenForGitHttpAuth(input.token);
1161
1162
  } catch (err) {
1162
- print(style.fail(` failed ${repo.full_name} — invalid token format: ${err instanceof Error ? err.message : String(err)}`));
1163
+ print(style.fail(` failed ${repo.full_name} — invalid token format: ${errorMessage(err)}`));
1163
1164
  failed++;
1164
1165
  continue;
1165
1166
  }
@@ -1379,7 +1380,7 @@ async function runDeploy(input) {
1379
1380
  status: "ok"
1380
1381
  };
1381
1382
  } catch (err) {
1382
- const message = err instanceof Error ? err.message : String(err);
1383
+ const message = errorMessage(err);
1383
1384
  print(` ${style.fail(message)}`);
1384
1385
  logger.warn({
1385
1386
  branch: input.branch,
@@ -1479,7 +1480,7 @@ async function runDeployFromFiles(input) {
1479
1480
  status: "ok"
1480
1481
  };
1481
1482
  } catch (err) {
1482
- const message = err instanceof Error ? err.message : String(err);
1483
+ const message = errorMessage(err);
1483
1484
  print(` ${style.fail(message)}`);
1484
1485
  logger.warn({
1485
1486
  dir: input.dir,
@@ -1494,6 +1495,22 @@ async function runDeployFromFiles(input) {
1494
1495
  }
1495
1496
  //#endregion
1496
1497
  //#region src/commands/doctor.ts
1498
+ /**
1499
+ * `holocron doctor` — load the config, instantiate every capability,
1500
+ * print a per-capability readiness report.
1501
+ *
1502
+ * Each capability gets a smoke check appropriate to its surface:
1503
+ * source → `whoami()`
1504
+ * issues → `doctor()` (rich report)
1505
+ * secrets → `listSecrets({ kind: 'repo' })`
1506
+ * ci → `listRuns({ limit: 1 })`
1507
+ * errors → `describe()`
1508
+ * logs → `whoami()` (dataset reachability) or `describe()`
1509
+ * others → just "loaded" (no smoke endpoint defined yet)
1510
+ *
1511
+ * Output is plain text via a passed-in `print` function so tests can
1512
+ * capture lines without ANSI / spinner noise.
1513
+ */
1497
1514
  async function runDoctor(input) {
1498
1515
  const print = input.print ?? ((line) => console.log(line));
1499
1516
  const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
@@ -1591,7 +1608,7 @@ async function smokeCheck(key, provider, impl) {
1591
1608
  default: return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
1592
1609
  }
1593
1610
  } catch (err) {
1594
- return mk(key, provider, "fail", err instanceof Error ? err.message : String(err));
1611
+ return mk(key, provider, "fail", errorMessage(err));
1595
1612
  }
1596
1613
  }
1597
1614
  function countResolvedLifecycle(report) {
@@ -1861,7 +1878,7 @@ async function runNew(input) {
1861
1878
  stdio: "inherit"
1862
1879
  });
1863
1880
  } catch (err) {
1864
- throw new NewError(`gh repo create failed: ${err instanceof Error ? err.message : String(err)}`);
1881
+ throw new NewError(`gh repo create failed: ${errorMessage(err)}`);
1865
1882
  }
1866
1883
  if (input.isTemplate) try {
1867
1884
  execFn("gh", [
@@ -1956,7 +1973,7 @@ async function runNew(input) {
1956
1973
  stdio: "inherit"
1957
1974
  });
1958
1975
  } catch (err) {
1959
- print(` ✗ pnpm install failed — ${err instanceof Error ? err.message : String(err)}`);
1976
+ print(` ✗ pnpm install failed — ${errorMessage(err)}`);
1960
1977
  return {
1961
1978
  status: "fail",
1962
1979
  repoDir,
@@ -2375,9 +2392,13 @@ function render$10(inputs) {
2375
2392
  "test:watch": "vitest",
2376
2393
  validate: "tsx scripts/validate.mjs"
2377
2394
  },
2378
- peerDependencies: { "@theholocron/cli": "workspace:*" },
2395
+ peerDependencies: {
2396
+ "@theholocron/cli": "workspace:*",
2397
+ "@theholocron/misc-utils": "catalog:utils"
2398
+ },
2379
2399
  devDependencies: {
2380
2400
  "@theholocron/cli": "workspace:*",
2401
+ "@theholocron/misc-utils": "catalog:utils",
2381
2402
  "@theholocron/tsconfig": "catalog:configs",
2382
2403
  "@types/node": "catalog:",
2383
2404
  "@vitest/coverage-v8": "catalog:",
@@ -2712,6 +2733,7 @@ function render$3(inputs) {
2712
2733
 
2713
2734
  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- filled in by operator
2714
2735
  import { AuthError, createPlugin, resolveToken, verifyToken } from "../src/index.ts";
2736
+ import { errorMessage } from "@theholocron/misc-utils";
2715
2737
 
2716
2738
  const args = process.argv.slice(2);
2717
2739
 
@@ -2772,7 +2794,7 @@ async function runStep(body) {
2772
2794
  try {
2773
2795
  await body();
2774
2796
  } catch (err) {
2775
- const message = err instanceof Error ? err.message : String(err);
2797
+ const message = errorMessage(err);
2776
2798
  console.log(\` ✗ ERROR: \${message}\`);
2777
2799
  const hint = hintFor(message);
2778
2800
  if (hint) console.log(\` hint: \${hint}\`);
@@ -2824,19 +2846,10 @@ function render$2(inputs) {
2824
2846
  * \`/me\`, \`/account\`.
2825
2847
  */
2826
2848
 
2827
- import { ${factoryName} } from "./rest.js";
2828
-
2829
- export interface VerifyTokenSuccess {
2830
- ok: true;
2831
- subject: string;
2832
- }
2849
+ import type { VerifyTokenResult } from "@theholocron/cli";
2850
+ import { errorMessage } from "@theholocron/misc-utils";
2833
2851
 
2834
- export interface VerifyTokenFailure {
2835
- ok: false;
2836
- message: string;
2837
- }
2838
-
2839
- export type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
2852
+ import { ${factoryName} } from "./rest.js";
2840
2853
 
2841
2854
  interface MeResponse {
2842
2855
  /** Adjust to whatever ${inputs.vendorName}'s whoami endpoint returns. */
@@ -2861,8 +2874,7 @@ export async function verifyToken(token: string, opts: VerifyTokenOptions = {}):
2861
2874
  const subject = me?.email ?? me?.name ?? me?.id ?? "unknown";
2862
2875
  return { ok: true, subject: \`user @ \${subject}\` };
2863
2876
  } catch (err) {
2864
- const message = err instanceof Error ? err.message : String(err);
2865
- return { ok: false, message };
2877
+ return { ok: false, message: errorMessage(err) };
2866
2878
  }
2867
2879
  }
2868
2880
  `;
@@ -3116,7 +3128,7 @@ function runPluginCreate(input) {
3116
3128
  });
3117
3129
  print(" ✓ scaffold verified");
3118
3130
  } catch (err) {
3119
- const message = err instanceof Error ? err.message : String(err);
3131
+ const message = errorMessage(err);
3120
3132
  print(` ✗ verify failed — ${message}`);
3121
3133
  logger.warn({
3122
3134
  slug: inputs.slug,
@@ -3813,6 +3825,24 @@ const defaultLogin = async (cwd) => {
3813
3825
  };
3814
3826
  //#endregion
3815
3827
  //#region src/commands/secret-set.ts
3828
+ /**
3829
+ * `holocron secret set` — one-shot single-secret push.
3830
+ *
3831
+ * Complements `holocron secrets sync` (bulk vault → destinations) for
3832
+ * ad-hoc scenarios:
3833
+ * - Bootstrap secrets (e.g., NPM_TOKEN on theholocron/holocron itself
3834
+ * before the rest of the setup exists)
3835
+ * - One-off rotations that don't warrant a vault sync
3836
+ * - Setting secrets the vault doesn't track
3837
+ *
3838
+ * Value source resolution (in priority order):
3839
+ * 1. Positional `value` argument
3840
+ * 2. `--from-stdin` reads from stdin
3841
+ * 3. `--from-env <NAME>` reads from the named env var
3842
+ * 4. Implicit: env var matching the secret name (e.g., `NPM_TOKEN`)
3843
+ *
3844
+ * Errors clearly when no value can be sourced.
3845
+ */
3816
3846
  async function runSecretSet(input) {
3817
3847
  const print = input.print ?? ((line) => console.log(line));
3818
3848
  const logger = input.logger ?? getLogger();
@@ -3851,7 +3881,7 @@ async function runSecretSet(input) {
3851
3881
  scope
3852
3882
  };
3853
3883
  } catch (err) {
3854
- const message = err instanceof Error ? err.message : String(err);
3884
+ const message = errorMessage(err);
3855
3885
  print(` ✗ ${message}`);
3856
3886
  logger.warn({
3857
3887
  key: input.name,
@@ -3887,6 +3917,38 @@ function describeScope(scope) {
3887
3917
  }
3888
3918
  //#endregion
3889
3919
  //#region src/commands/secrets-sync.ts
3920
+ /**
3921
+ * `holocron secrets sync` — vault → destinations.
3922
+ *
3923
+ * Reads a named environment from the configured `vault` (1P
3924
+ * Environment / similar) as KEY=VALUE pairs, then fans those values
3925
+ * out to the configured destinations:
3926
+ *
3927
+ * - `secrets` capability (e.g., GH Actions secrets) — repo-scope
3928
+ * - `deployment` capability (e.g., Vercel env vars) — per-target
3929
+ * - local `.env` file (optional, planned for v5.1 — currently skipped
3930
+ * with a soft "not yet" note)
3931
+ *
3932
+ * Per-secret routing rules:
3933
+ *
3934
+ * - All keys go to `deployment` for each target the caller asks for
3935
+ * (defaults: production + preview)
3936
+ * - `secrets` (GH Actions) defaults to every key, repo-scoped — but a
3937
+ * caller can pass `githubSecretKeys` (an allowlist, from repeatable
3938
+ * `--github-secret KEY` CLI values) to restrict `secrets` to only
3939
+ * those keys, and `githubSecretScope` (same `{ kind }` shape `secret
3940
+ * set`'s own `--scope repo|env=NAME|org=NAME` parses to) to apply one
3941
+ * scope to all of them. A key not in the allowlist is skipped for
3942
+ * `secrets` entirely — still synced to `deployment` if configured.
3943
+ * Needed for a vault holding a mix of deploy-only secrets and one
3944
+ * CI-consumed, org-wide secret (holocron#781's Sentinel case: 4
3945
+ * Vercel-only keys + one org-scoped Axiom ingest token
3946
+ * `theholocron/.github`'s dispatched-check workflow also reads).
3947
+ *
3948
+ * The vault MUST implement `readEnvironment(envId)` (optional method).
3949
+ * If it doesn't, the command errors with a hint to populate the keys
3950
+ * individually via `holocron secret set` (also planned for v5.1).
3951
+ */
3890
3952
  async function runSecretsSync(input) {
3891
3953
  const print = input.print ?? ((line) => console.log(line));
3892
3954
  const logger = input.logger ?? getLogger();
@@ -3997,7 +4059,7 @@ async function runRow(destination, scope, key, dryRun, body) {
3997
4059
  scope,
3998
4060
  key,
3999
4061
  status: "fail",
4000
- message: err instanceof Error ? err.message : String(err)
4062
+ message: errorMessage(err)
4001
4063
  };
4002
4064
  }
4003
4065
  }
@@ -4930,7 +4992,7 @@ async function upsertBranchProtection(source, dryRun, requiredChecks) {
4930
4992
  capability: "source",
4931
4993
  step,
4932
4994
  status: "fail",
4933
- message: err instanceof Error ? err.message : String(err)
4995
+ message: errorMessage(err)
4934
4996
  };
4935
4997
  }
4936
4998
  try {
@@ -4953,7 +5015,7 @@ async function upsertBranchProtection(source, dryRun, requiredChecks) {
4953
5015
  capability: "source",
4954
5016
  step,
4955
5017
  status: "fail",
4956
- message: err instanceof Error ? err.message : String(err)
5018
+ message: errorMessage(err)
4957
5019
  };
4958
5020
  }
4959
5021
  }
@@ -5046,7 +5108,7 @@ async function execStep(capability, step, dryRun, body, opts = {}) {
5046
5108
  capability,
5047
5109
  step,
5048
5110
  status: "fail",
5049
- message: err instanceof Error ? err.message : String(err)
5111
+ message: errorMessage(err)
5050
5112
  };
5051
5113
  }
5052
5114
  }
@@ -5753,7 +5815,7 @@ async function runSetup(input) {
5753
5815
  capability: "vault",
5754
5816
  step: "list",
5755
5817
  status: "fail",
5756
- message: err instanceof Error ? err.message : String(err)
5818
+ message: errorMessage(err)
5757
5819
  });
5758
5820
  }
5759
5821
  print(formatStep(steps[steps.length - 1]));
@@ -5969,7 +6031,7 @@ async function runSkillsInstall(input) {
5969
6031
  status: "ok"
5970
6032
  }, "skills install: done");
5971
6033
  } catch (err) {
5972
- const message = err instanceof Error ? err.message : String(err);
6034
+ const message = errorMessage(err);
5973
6035
  print(` ✗ ${message}`);
5974
6036
  logger.warn({
5975
6037
  agent: config.agent,
@@ -6827,7 +6889,7 @@ async function runSyncStep(capability, step, dryRun, body) {
6827
6889
  capability,
6828
6890
  step,
6829
6891
  status: "fail",
6830
- message: err instanceof Error ? err.message : String(err)
6892
+ message: errorMessage(err)
6831
6893
  };
6832
6894
  }
6833
6895
  }
@@ -7274,7 +7336,7 @@ async function runSyncGithub(input) {
7274
7336
  sha: blob.sha
7275
7337
  });
7276
7338
  } catch (err) {
7277
- const msg = `failed to create blob for ${file.path}: ${err instanceof Error ? err.message : String(err)}`;
7339
+ const msg = `failed to create blob for ${file.path}: ${errorMessage(err)}`;
7278
7340
  print(` ✗ ${msg}`);
7279
7341
  return done({
7280
7342
  status: "fail",
@@ -7288,7 +7350,7 @@ async function runSyncGithub(input) {
7288
7350
  try {
7289
7351
  newTreeSha = (await client.git.createTree(repo, treeEntries, baseTreeSha)).sha;
7290
7352
  } catch (err) {
7291
- const msg = `failed to create tree: ${err instanceof Error ? err.message : String(err)}`;
7353
+ const msg = `failed to create tree: ${errorMessage(err)}`;
7292
7354
  print(` ✗ ${msg}`);
7293
7355
  return done({
7294
7356
  status: "fail",
@@ -7302,7 +7364,7 @@ async function runSyncGithub(input) {
7302
7364
  try {
7303
7365
  newCommitSha = (await client.git.createCommit(repo, message, newTreeSha, [headSha])).sha;
7304
7366
  } catch (err) {
7305
- const msg = `failed to create commit: ${err instanceof Error ? err.message : String(err)}`;
7367
+ const msg = `failed to create commit: ${errorMessage(err)}`;
7306
7368
  print(` ✗ ${msg}`);
7307
7369
  return done({
7308
7370
  status: "fail",
@@ -7321,7 +7383,7 @@ async function runSyncGithub(input) {
7321
7383
  }
7322
7384
  else await client.git.updateRef(repo, `heads/${targetBranch}`, newCommitSha);
7323
7385
  } catch (err) {
7324
- const msg = `failed to update ref: ${err instanceof Error ? err.message : String(err)}`;
7386
+ const msg = `failed to update ref: ${errorMessage(err)}`;
7325
7387
  print(` ✗ ${msg}`);
7326
7388
  return done({
7327
7389
  status: "fail",
@@ -7342,7 +7404,7 @@ async function runSyncGithub(input) {
7342
7404
  print(` → PR opened: ${prUrl}`);
7343
7405
  } catch (err) {
7344
7406
  if (err instanceof ProviderApiError && err.status === 422 && String(err.details).includes("already exists")) print(` → PR already open for ${branch} — branch updated, ready to merge`);
7345
- else print(` ⚠ PR creation failed: ${err instanceof Error ? err.message : String(err)}`);
7407
+ else print(` ⚠ PR creation failed: ${errorMessage(err)}`);
7346
7408
  }
7347
7409
  return done({
7348
7410
  status: "ok",