@theholocron/cli 5.0.0-alpha.12 → 5.0.0-alpha.121

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
@@ -1,9 +1,9 @@
1
1
  #!/usr/bin/env node
2
2
  import { createRequire } from "node:module";
3
3
  import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
4
- import path, { basename, dirname, join, relative, resolve } from "node:path";
5
- import { checkbox, input, select } from "@inquirer/prompts";
6
- import { KNOWN_WORKFLOWS, createAstromech, extractPreviewConfig, readWorkspacePackages, reusableTemplates } from "@theholocron/astromech";
4
+ import path, { basename, dirname, join, relative, resolve, sep } from "node:path";
5
+ import { checkbox, confirm, input, select } from "@inquirer/prompts";
6
+ import { KNOWN_WORKFLOWS, createAstromech, deployOnRelease, extractPreviewConfig, readWorkspacePackages, reusableTemplates } from "@theholocron/astromech";
7
7
  import { loadTasksConfig } from "@theholocron/astromech/config";
8
8
  import yargs from "yargs";
9
9
  import { hideBin } from "yargs/helpers";
@@ -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";
@@ -24,6 +25,8 @@ import { createGitHubClient } from "@theholocron/github-client";
24
25
  import { PostHogSink } from "@theholocron/observability/analytics";
25
26
  import { NoopAnalyticsSink, NoopErrorSink, redactObject } from "@theholocron/observability/core";
26
27
  import { SentrySink } from "@theholocron/observability/errors";
28
+ import load from "@commitlint/load";
29
+ import lint from "@commitlint/lint";
27
30
  import { promisify } from "node:util";
28
31
  import { ConfigFileError, loadConfigFile } from "@theholocron/datapad";
29
32
  import search from "@inquirer/search";
@@ -295,7 +298,8 @@ function resolveConfig(raw) {
295
298
  docs,
296
299
  env: raw.env,
297
300
  log: raw.log,
298
- telemetry: raw.telemetry
301
+ telemetry: raw.telemetry,
302
+ eslint: raw.eslint
299
303
  };
300
304
  }
301
305
  //#endregion
@@ -491,7 +495,7 @@ var PluginLoader = class {
491
495
  /** Internal — invoke a plugin's capability factory and return the impl. */
492
496
  async loadOne(key, tuple) {
493
497
  const mod = await this.importer(tuple.packageName).catch((err) => {
494
- 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)}`);
495
499
  });
496
500
  if (isPluginModule(mod)) {
497
501
  const effectiveToken = this.context.cliTokens?.[tuple.provider] ?? this.context.cliToken;
@@ -532,7 +536,8 @@ var PluginLoader = class {
532
536
  /** Default importer — resolves from cwd first so the global CLI finds project plugins. */
533
537
  const defaultImporter$1 = async (pkg) => {
534
538
  try {
535
- return import(pathToFileURL(createRequire(process.cwd() + "/").resolve(pkg)).href);
539
+ const resolved = createRequire(process.cwd() + "/").resolve(pkg);
540
+ return import(pathToFileURL(resolved).href);
536
541
  } catch {
537
542
  return import(pkg);
538
543
  }
@@ -664,7 +669,8 @@ const style = {
664
669
  */
665
670
  const defaultImporter = async (pkg) => {
666
671
  try {
667
- return await import(pathToFileURL(createRequire(process.cwd() + "/").resolve(pkg)).href);
672
+ const resolved = createRequire(process.cwd() + "/").resolve(pkg);
673
+ return await import(pathToFileURL(resolved).href);
668
674
  } catch {
669
675
  return await import(pkg);
670
676
  }
@@ -733,7 +739,7 @@ async function runAuthSet(input) {
733
739
  subject = verified.subject;
734
740
  } else print(style.warn(`${provider} plugin has no verifyToken; storing without verification`));
735
741
  } catch (err) {
736
- const msg = err instanceof Error ? err.message : String(err);
742
+ const msg = errorMessage(err);
737
743
  print(style.warn(`cannot verify token — failed to load ${packageName}: ${msg}`));
738
744
  print(style.hint(` storing token anyway; run 'holocron auth check ${provider}' once the plugin is installed`));
739
745
  }
@@ -850,7 +856,7 @@ async function runAuthCheck(input) {
850
856
  message: verified.message
851
857
  };
852
858
  } catch (err) {
853
- const msg = err instanceof Error ? err.message : String(err);
859
+ const msg = errorMessage(err);
854
860
  if (isModuleNotFound(err)) {
855
861
  print(style.warn(`${keyringKey}: token present — verification skipped (plugin not available here)`));
856
862
  logger.info({
@@ -949,7 +955,7 @@ async function runCleanupPreview(input) {
949
955
  try {
950
956
  pr = await source.getPullRequest(input.prNumber, input.repo);
951
957
  } catch (err) {
952
- const message = err instanceof Error ? err.message : String(err);
958
+ const message = errorMessage(err);
953
959
  throw new Error(`Failed to fetch PR #${input.prNumber}: ${message}`, { cause: err });
954
960
  }
955
961
  const branch = `${(input.repo ?? input.loaded.resolved.repo?.name ?? "").split("/").pop()}-pr-${pr.number}`;
@@ -966,7 +972,7 @@ async function runCleanupPreview(input) {
966
972
  try {
967
973
  deployments = await deploy.listPreviewDeployments(input.project, branch);
968
974
  } catch (err) {
969
- const message = err instanceof Error ? err.message : String(err);
975
+ const message = errorMessage(err);
970
976
  throw new Error(`Failed to list deployments: ${message}`, { cause: err });
971
977
  }
972
978
  if (deployments.length === 0) {
@@ -1045,7 +1051,7 @@ async function runCleanupPreview(input) {
1045
1051
  status: "ok"
1046
1052
  };
1047
1053
  } catch (err) {
1048
- const message = err instanceof Error ? err.message : String(err);
1054
+ const message = errorMessage(err);
1049
1055
  print(style.fail(message));
1050
1056
  logger.warn({
1051
1057
  pr: pr.number,
@@ -1066,12 +1072,34 @@ async function runCleanupPreview(input) {
1066
1072
  }
1067
1073
  //#endregion
1068
1074
  //#region src/commands/clone.ts
1075
+ /**
1076
+ * Accepts a bare org (`"theholocron"`) — clones every repo in it — or an
1077
+ * `org/repo` coordinate (`"theholocron/new-repo"`) — clones just that one
1078
+ * repo. The repo half is never silently discarded: if it's there, it's used.
1079
+ * A trailing slash with nothing after it (`"theholocron/"`) is treated the
1080
+ * same as a bare org.
1081
+ */
1082
+ function parseCloneTarget(raw) {
1083
+ const trimmed = raw.trim();
1084
+ const slash = trimmed.indexOf("/");
1085
+ if (slash === -1) return { org: trimmed };
1086
+ const org = trimmed.slice(0, slash);
1087
+ const repo = trimmed.slice(slash + 1);
1088
+ return repo ? {
1089
+ org,
1090
+ repo
1091
+ } : { org };
1092
+ }
1069
1093
  function encodeTokenForGitHttpAuth(token) {
1070
1094
  const trimmed = token.trim();
1071
1095
  if (!trimmed) throw new Error("empty token");
1072
1096
  if (/[\u0000-\u001F\u007F\s]/.test(trimmed)) throw new Error("token contains whitespace or control characters");
1073
1097
  return encodeURIComponent(trimmed);
1074
1098
  }
1099
+ /** Strip a leading dot so a hidden repo (e.g. `.github`) is still visible in Finder once cloned. */
1100
+ function repoDirName(repo) {
1101
+ return repo.name.startsWith(".") ? repo.name.slice(1) : repo.name;
1102
+ }
1075
1103
  async function listOrgRepos(org, token, fetchFn) {
1076
1104
  const repos = [];
1077
1105
  let url = `https://api.github.com/orgs/${org}/repos?per_page=100&type=all`;
@@ -1088,14 +1116,26 @@ async function listOrgRepos(org, token, fetchFn) {
1088
1116
  }
1089
1117
  return repos;
1090
1118
  }
1119
+ async function getRepo(org, repo, token, fetchFn) {
1120
+ const res = await fetchFn(`https://api.github.com/repos/${org}/${repo}`, { headers: {
1121
+ Authorization: `Bearer ${token}`,
1122
+ Accept: "application/vnd.github+json",
1123
+ "X-GitHub-Api-Version": "2022-11-28"
1124
+ } });
1125
+ if (res.status === 404) throw new Error(`${org}/${repo} not found — check the repo name and that the token can see it`);
1126
+ if (!res.ok) throw new Error(`GitHub API ${res.status}: ${res.statusText} — check that the token has repo:read scope`);
1127
+ return await res.json();
1128
+ }
1091
1129
  async function runClone(input) {
1092
1130
  const print = input.print ?? ((line) => console.log(line));
1093
1131
  const logger = input.logger ?? getLogger();
1094
1132
  const fetchFn = input.fetch ?? globalThis.fetch;
1095
1133
  const dryRun = input.dryRun ?? false;
1096
1134
  const targetDir = resolve(input.dir ?? join(homedir(), "Code", input.org));
1135
+ const label = input.repo ? `${input.org}/${input.repo}` : `org=${input.org}`;
1097
1136
  logger.info({
1098
1137
  org: input.org,
1138
+ repo: input.repo,
1099
1139
  targetDir,
1100
1140
  dryRun: dryRun || void 0
1101
1141
  }, "clone: start");
@@ -1105,18 +1145,21 @@ async function runClone(input) {
1105
1145
  stdio: "inherit"
1106
1146
  }).status };
1107
1147
  });
1108
- print(style.header(`Holocron clone — org=${input.org} → ${targetDir}${dryRun ? " (dry-run)" : ""}`));
1109
- if (!existsSync(targetDir)) if (dryRun) print(style.dim(` would create ${targetDir}`));
1110
- else mkdirSync(targetDir, { recursive: true });
1148
+ print(style.header(`Holocron clone — ${label} → ${targetDir}${dryRun ? " (dry-run)" : ""}`));
1149
+ if (!existsSync(targetDir)) {
1150
+ if (dryRun) print(style.dim(` would create ${targetDir}`));
1151
+ else mkdirSync(targetDir, { recursive: true });
1152
+ }
1111
1153
  let repos;
1112
1154
  try {
1113
- repos = await listOrgRepos(input.org, input.token, fetchFn);
1155
+ repos = input.repo ? [await getRepo(input.org, input.repo, input.token, fetchFn)] : await listOrgRepos(input.org, input.token, fetchFn);
1114
1156
  } catch (err) {
1115
- const message = err instanceof Error ? err.message : String(err);
1157
+ const message = errorMessage(err);
1116
1158
  logger.warn({
1117
1159
  org: input.org,
1160
+ repo: input.repo,
1118
1161
  reason: message
1119
- }, "clone: failed to list org repos");
1162
+ }, "clone: failed to list repos");
1120
1163
  return {
1121
1164
  status: "fail",
1122
1165
  cloned: 0,
@@ -1125,11 +1168,33 @@ async function runClone(input) {
1125
1168
  message
1126
1169
  };
1127
1170
  }
1171
+ if (!input.repo && !dryRun && input.confirmWholeOrg) {
1172
+ const alreadyCloned = repos.filter((r) => existsSync(join(targetDir, repoDirName(r)))).length;
1173
+ const scope = {
1174
+ total: repos.length,
1175
+ alreadyCloned,
1176
+ toClone: repos.length - alreadyCloned
1177
+ };
1178
+ if (!await input.confirmWholeOrg(scope)) {
1179
+ print(style.dim(" aborted — nothing cloned"));
1180
+ logger.info({
1181
+ org: input.org,
1182
+ ...scope
1183
+ }, "clone: aborted by user");
1184
+ return {
1185
+ status: "aborted",
1186
+ cloned: 0,
1187
+ skipped: 0,
1188
+ failed: 0,
1189
+ message: "aborted by user"
1190
+ };
1191
+ }
1192
+ }
1128
1193
  let cloned = 0;
1129
1194
  let skipped = 0;
1130
1195
  let failed = 0;
1131
1196
  for (const repo of repos) {
1132
- const dest = join(targetDir, repo.name.startsWith(".") ? repo.name.slice(1) : repo.name);
1197
+ const dest = join(targetDir, repoDirName(repo));
1133
1198
  if (existsSync(dest)) {
1134
1199
  print(style.dim(` skip ${repo.full_name}`));
1135
1200
  skipped++;
@@ -1151,7 +1216,7 @@ async function runClone(input) {
1151
1216
  try {
1152
1217
  encodedToken = encodeTokenForGitHttpAuth(input.token);
1153
1218
  } catch (err) {
1154
- print(style.fail(` failed ${repo.full_name} — invalid token format: ${err instanceof Error ? err.message : String(err)}`));
1219
+ print(style.fail(` failed ${repo.full_name} — invalid token format: ${errorMessage(err)}`));
1155
1220
  failed++;
1156
1221
  continue;
1157
1222
  }
@@ -1173,6 +1238,7 @@ async function runClone(input) {
1173
1238
  const status = dryRun ? "dry-run" : failed > 0 ? "fail" : "ok";
1174
1239
  logger[failed > 0 ? "warn" : "info"]({
1175
1240
  org: input.org,
1241
+ repo: input.repo,
1176
1242
  status,
1177
1243
  cloned,
1178
1244
  skipped,
@@ -1199,7 +1265,6 @@ async function runClone(input) {
1199
1265
  * resolve (devDeps in a repo, or `pnpm exec`).
1200
1266
  */
1201
1267
  const COMMAND_CONTEXTS = {
1202
- version: "global",
1203
1268
  clone: "global",
1204
1269
  new: "global",
1205
1270
  "upgrade node": "global",
@@ -1214,8 +1279,10 @@ const COMMAND_CONTEXTS = {
1214
1279
  "skills install": "global",
1215
1280
  "skills remove": "global",
1216
1281
  "skills update": "global",
1282
+ "lint commit-msg": "global",
1217
1283
  run: "repo-aware",
1218
1284
  ci: "repo-aware",
1285
+ "deploy-on-release": "repo-aware",
1219
1286
  "config show": "repo-aware",
1220
1287
  "sync-readme": "repo-aware",
1221
1288
  doctor: "workspace",
@@ -1233,6 +1300,80 @@ function commandsInContext(context) {
1233
1300
  }
1234
1301
  //#endregion
1235
1302
  //#region src/commands/deploy.ts
1303
+ /**
1304
+ * `holocron deploy` — trigger a deployment via the configured
1305
+ * `deployment` capability.
1306
+ *
1307
+ * Two modes, one command: `runDeploy` (the default — a Git branch,
1308
+ * `triggerDeployment()`) and `runDeployFromFiles` (`--files <dir>` —
1309
+ * a local directory of source files, `deployFunction()`, no linked
1310
+ * repo required — for a consumer with no Git history to deploy from,
1311
+ * e.g. Sentinel, shipped as an npm package). Separate functions, not
1312
+ * one branching `runDeploy`, because their inputs genuinely differ
1313
+ * (`branch` vs `dir`) and their result shapes differ too
1314
+ * (`DeploymentRecord` carries `status`/`branch`; `DeployFunctionResult`
1315
+ * is deliberately minimal, same as `DeployScriptResult` for Workers).
1316
+ *
1317
+ * Errors clearly when `deployment` isn't loaded (no provider declared
1318
+ * in `holocron.config.json`), or when the configured provider doesn't
1319
+ * implement `deployFunction` (it's optional on `Deployment` — not
1320
+ * every provider has a files-based deploy API).
1321
+ *
1322
+ * Dry-run skips the actual deploy call but still verifies the
1323
+ * deployment capability (and, for `--files`, `deployFunction`) is
1324
+ * present, so operators can sanity-check the wiring without spinning
1325
+ * up a build.
1326
+ *
1327
+ * **Both modes wait for the deployment to finish** (holocron#911): a
1328
+ * provider accepting the upload/trigger is not the deployment succeeding.
1329
+ * Vercel builds asynchronously — an `npm install` failure there leaves
1330
+ * the deployment in `ERROR` while production keeps serving the previous
1331
+ * one, and this command used to report `ok` regardless (found live:
1332
+ * Sentinel's holocron#910 deploy "succeeded" in CI, never went live). So
1333
+ * after triggering, {@link waitForDeployment} polls
1334
+ * `Deployment.getDeployment()` until a terminal state; only `ready` is
1335
+ * `ok`, while `error` / `cancelled` / a timeout are `fail` (non-zero exit
1336
+ * via `cli.ts`).
1337
+ */
1338
+ const DEFAULT_WAIT_TIMEOUT_MS = 6e5;
1339
+ const DEFAULT_WAIT_INTERVAL_MS = 5e3;
1340
+ const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
1341
+ "ready",
1342
+ "error",
1343
+ "cancelled"
1344
+ ]);
1345
+ /**
1346
+ * Polls `getDeployment(id)` until the deployment reaches a terminal status
1347
+ * (`ready` / `error` / `cancelled`). Throws on timeout — the caller turns
1348
+ * that into a `fail` report, same as a provider throwing mid-trigger.
1349
+ */
1350
+ async function waitForDeployment(deploy, deploymentId, options = {}) {
1351
+ const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
1352
+ const intervalMs = options.intervalMs ?? DEFAULT_WAIT_INTERVAL_MS;
1353
+ const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
1354
+ const now = options.now ?? Date.now;
1355
+ const deadline = now() + timeoutMs;
1356
+ for (;;) {
1357
+ const record = await deploy.getDeployment(deploymentId);
1358
+ if (TERMINAL_STATUSES.has(record.status)) return record;
1359
+ if (now() >= deadline) throw new Error(`deployment ${deploymentId} still ${record.status} after ${Math.round(timeoutMs / 1e3)}s — check the provider's dashboard`);
1360
+ await sleep(intervalMs);
1361
+ }
1362
+ }
1363
+ /** One terminal, non-ready record as a single human-readable failure line. */
1364
+ function terminalFailure(record) {
1365
+ return `deployment ${record.id} ended ${record.status}${record.errorMessage ? `: ${record.errorMessage}` : ""}`;
1366
+ }
1367
+ /**
1368
+ * Provider `url` fields (Vercel's REST API, at least) come back as bare
1369
+ * hostnames — `"my-app.vercel.app"`, no scheme — which terminals don't
1370
+ * linkify and browsers won't navigate to unmodified. Printed output
1371
+ * should be a URL a human can click/paste; structured log fields keep
1372
+ * the raw provider value as-is.
1373
+ */
1374
+ function withScheme(url) {
1375
+ return /^https?:\/\//.test(url) ? url : `https://${url}`;
1376
+ }
1236
1377
  async function runDeploy(input) {
1237
1378
  const print = input.print ?? ((line) => console.log(line));
1238
1379
  const logger = input.logger ?? getLogger();
@@ -1259,23 +1400,43 @@ async function runDeploy(input) {
1259
1400
  };
1260
1401
  }
1261
1402
  try {
1262
- const record = await withSpinner(`Deploying ${input.branch}${input.target ? ` → ${input.target}` : ""}…`, () => deploy.triggerDeployment({
1403
+ const triggered = await withSpinner(`Deploying ${input.branch}${input.target ? ` → ${input.target}` : ""}…`, () => deploy.triggerDeployment({
1263
1404
  projectId: input.projectId,
1264
1405
  branch: input.branch,
1265
1406
  ...input.target ? { target: input.target } : {}
1266
1407
  }));
1267
- print(` ${style.success(`${record.status} — ${record.url}`)}`);
1408
+ logger.info({
1409
+ status: triggered.status,
1410
+ url: triggered.url,
1411
+ id: triggered.id
1412
+ }, "deploy: triggered");
1413
+ const record = TERMINAL_STATUSES.has(triggered.status) ? triggered : await withSpinner(`Waiting for ${withScheme(triggered.url)} to finish…`, () => waitForDeployment(deploy, triggered.id, input.wait));
1414
+ if (record.status !== "ready") {
1415
+ const message = terminalFailure(record);
1416
+ print(` ${style.fail(`${message} — ${withScheme(triggered.url)}`)}`);
1417
+ logger.warn({
1418
+ id: record.id,
1419
+ status: record.status,
1420
+ reason: record.errorMessage
1421
+ }, "deploy: failed");
1422
+ return {
1423
+ deployment: record,
1424
+ status: "fail",
1425
+ message
1426
+ };
1427
+ }
1428
+ print(` ${style.success(`${record.status} — ${withScheme(triggered.url)}`)}`);
1268
1429
  logger.info({
1269
1430
  status: record.status,
1270
- url: record.url,
1431
+ url: triggered.url,
1271
1432
  id: record.id
1272
- }, "deploy: triggered");
1433
+ }, "deploy: ready");
1273
1434
  return {
1274
1435
  deployment: record,
1275
1436
  status: "ok"
1276
1437
  };
1277
1438
  } catch (err) {
1278
- const message = err instanceof Error ? err.message : String(err);
1439
+ const message = errorMessage(err);
1279
1440
  print(` ${style.fail(message)}`);
1280
1441
  logger.warn({
1281
1442
  branch: input.branch,
@@ -1288,8 +1449,124 @@ async function runDeploy(input) {
1288
1449
  };
1289
1450
  }
1290
1451
  }
1452
+ const SKIP_DIRS$2 = /* @__PURE__ */ new Set([
1453
+ ".git",
1454
+ "node_modules",
1455
+ ".turbo"
1456
+ ]);
1457
+ /** Recursively lists absolute file paths under `dir`, skipping VCS/tooling noise. */
1458
+ function defaultWalkFiles$2(dir) {
1459
+ const results = [];
1460
+ for (const entry of readdirSync(dir)) {
1461
+ if (SKIP_DIRS$2.has(entry)) continue;
1462
+ const full = join(dir, entry);
1463
+ const stat = statSync(full);
1464
+ if (stat.isDirectory()) results.push(...defaultWalkFiles$2(full));
1465
+ else if (stat.isFile()) results.push(full);
1466
+ }
1467
+ return results;
1468
+ }
1469
+ /** `holocron deploy --files <dir>` — the non-git counterpart to `runDeploy`. */
1470
+ async function runDeployFromFiles(input) {
1471
+ const print = input.print ?? ((line) => console.log(line));
1472
+ const logger = input.logger ?? getLogger();
1473
+ const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
1474
+ await loader.load();
1475
+ assertPluginsResolvable(loader, "deploy");
1476
+ const dryRun = input.context.dryRun ?? false;
1477
+ const walkFiles = input.walkFiles ?? defaultWalkFiles$2;
1478
+ const readFile = input.readFile ?? ((p) => readFileSync(p, "utf8"));
1479
+ const files = {};
1480
+ for (const abs of walkFiles(input.dir)) {
1481
+ const rel = relative(input.dir, abs).split(sep).join("/");
1482
+ files[rel] = readFile(abs);
1483
+ }
1484
+ const fileCount = Object.keys(files).length;
1485
+ logger.info({
1486
+ dir: input.dir,
1487
+ fileCount,
1488
+ target: input.target ?? "preview",
1489
+ projectId: input.projectId,
1490
+ dryRun: dryRun || void 0
1491
+ }, "deploy: start (files)");
1492
+ print(style.header(`Holocron deploy — files=${input.dir} (${fileCount} file${fileCount === 1 ? "" : "s"})${input.target ? `, target=${input.target}` : " (preview)"}${dryRun ? " (dry-run)" : ""}`));
1493
+ if (!loader.has("deployment")) throw new Error("deployment capability is not configured — add a `deployment` provider to holocron.config.json");
1494
+ const deploy = loader.get("deployment");
1495
+ if (!deploy.deployFunction) throw new Error(`deployment provider "${deploy.providerName}" does not support deploying from files — deployFunction() is not implemented`);
1496
+ if (dryRun) {
1497
+ const message = `would: ${deploy.providerName}.deployFunction(projectId=${input.projectId}, files=${fileCount}${input.target ? `, target=${input.target}` : ""})`;
1498
+ print(` ${style.dim(`… ${message}`)}`);
1499
+ return {
1500
+ deployment: null,
1501
+ status: "dry-run",
1502
+ message
1503
+ };
1504
+ }
1505
+ try {
1506
+ const result = await withSpinner(`Deploying ${fileCount} file${fileCount === 1 ? "" : "s"} from ${input.dir}…`, () => deploy.deployFunction(input.projectId, {
1507
+ files,
1508
+ ...input.target ? { target: input.target } : {}
1509
+ }));
1510
+ logger.info({
1511
+ url: result.url,
1512
+ id: result.deploymentId
1513
+ }, "deploy: triggered (files)");
1514
+ const record = await withSpinner(`Waiting for ${withScheme(result.url)} to finish…`, () => waitForDeployment(deploy, result.deploymentId, input.wait));
1515
+ if (record.status !== "ready") {
1516
+ const message = terminalFailure(record);
1517
+ print(` ${style.fail(`${message} — ${withScheme(result.url)}`)}`);
1518
+ logger.warn({
1519
+ id: record.id,
1520
+ status: record.status,
1521
+ reason: record.errorMessage
1522
+ }, "deploy: failed (files)");
1523
+ return {
1524
+ deployment: result,
1525
+ status: "fail",
1526
+ message
1527
+ };
1528
+ }
1529
+ print(` ${style.success(withScheme(result.url))}`);
1530
+ logger.info({
1531
+ url: result.url,
1532
+ id: result.deploymentId
1533
+ }, "deploy: ready (files)");
1534
+ return {
1535
+ deployment: result,
1536
+ status: "ok"
1537
+ };
1538
+ } catch (err) {
1539
+ const message = errorMessage(err);
1540
+ print(` ${style.fail(message)}`);
1541
+ logger.warn({
1542
+ dir: input.dir,
1543
+ reason: message
1544
+ }, "deploy: failed (files)");
1545
+ return {
1546
+ deployment: null,
1547
+ status: "fail",
1548
+ message
1549
+ };
1550
+ }
1551
+ }
1291
1552
  //#endregion
1292
1553
  //#region src/commands/doctor.ts
1554
+ /**
1555
+ * `holocron doctor` — load the config, instantiate every capability,
1556
+ * print a per-capability readiness report.
1557
+ *
1558
+ * Each capability gets a smoke check appropriate to its surface:
1559
+ * source → `whoami()`
1560
+ * issues → `doctor()` (rich report)
1561
+ * secrets → `listSecrets({ kind: 'repo' })`
1562
+ * ci → `listRuns({ limit: 1 })`
1563
+ * errors → `describe()`
1564
+ * logs → `whoami()` (dataset reachability) or `describe()`
1565
+ * others → just "loaded" (no smoke endpoint defined yet)
1566
+ *
1567
+ * Output is plain text via a passed-in `print` function so tests can
1568
+ * capture lines without ANSI / spinner noise.
1569
+ */
1293
1570
  async function runDoctor(input) {
1294
1571
  const print = input.print ?? ((line) => console.log(line));
1295
1572
  const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
@@ -1387,7 +1664,7 @@ async function smokeCheck(key, provider, impl) {
1387
1664
  default: return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
1388
1665
  }
1389
1666
  } catch (err) {
1390
- return mk(key, provider, "fail", err instanceof Error ? err.message : String(err));
1667
+ return mk(key, provider, "fail", errorMessage(err));
1391
1668
  }
1392
1669
  }
1393
1670
  function countResolvedLifecycle(report) {
@@ -1657,7 +1934,7 @@ async function runNew(input) {
1657
1934
  stdio: "inherit"
1658
1935
  });
1659
1936
  } catch (err) {
1660
- throw new NewError(`gh repo create failed: ${err instanceof Error ? err.message : String(err)}`);
1937
+ throw new NewError(`gh repo create failed: ${errorMessage(err)}`);
1661
1938
  }
1662
1939
  if (input.isTemplate) try {
1663
1940
  execFn("gh", [
@@ -1752,7 +2029,7 @@ async function runNew(input) {
1752
2029
  stdio: "inherit"
1753
2030
  });
1754
2031
  } catch (err) {
1755
- print(` ✗ pnpm install failed — ${err instanceof Error ? err.message : String(err)}`);
2032
+ print(` ✗ pnpm install failed — ${errorMessage(err)}`);
1756
2033
  return {
1757
2034
  status: "fail",
1758
2035
  repoDir,
@@ -1963,14 +2240,16 @@ describe("resolveToken", () => {
1963
2240
  });
1964
2241
 
1965
2242
  it("throws AuthError with a helpful message when nothing is set", () => {
1966
- try {
1967
- resolveToken({ env: {}, keyring: noKeyring });
1968
- throw new Error("should have thrown");
1969
- } catch (err) {
1970
- expect(err).toBeInstanceOf(AuthError);
1971
- expect((err as Error).message).toMatch(/${inputs.tokenEnv}/);
1972
- expect((err as Error).message).toMatch(/holocron auth set ${inputs.slug}/);
1973
- }
2243
+ const err = (() => {
2244
+ try {
2245
+ resolveToken({ env: {}, keyring: noKeyring });
2246
+ } catch (e) {
2247
+ return e;
2248
+ }
2249
+ })();
2250
+ expect(err).toBeInstanceOf(AuthError);
2251
+ expect((err as Error).message).toMatch(/${inputs.tokenEnv}/);
2252
+ expect((err as Error).message).toMatch(/holocron auth set ${inputs.slug}/);
1974
2253
  });
1975
2254
  });
1976
2255
  `;
@@ -2014,24 +2293,24 @@ export class ${inputs.capabilityClass} {
2014
2293
  //#endregion
2015
2294
  //#region src/commands/plugin-create/templates/capability-test.ts
2016
2295
  function render$14(inputs) {
2017
- const clientClass = `${inputs.vendorName}RestClient`;
2018
- return `import { describe, it } from "vitest";
2296
+ const factoryName = `create${inputs.vendorName}RestClient`;
2297
+ return `import { describe, expect, it } from "vitest";
2019
2298
 
2020
2299
  import { ${inputs.capabilityClass} } from "../capabilities/${inputs.capability}.js";
2021
- import { ${clientClass} } from "../rest.js";
2300
+ import { ${factoryName} } from "../rest.js";
2022
2301
  import { stubFetch } from "./helpers.js";
2023
2302
 
2024
2303
  // Stub client used by the constructor smoke test. Real capability
2025
2304
  // tests replace this with per-method stubs once implementations land.
2026
2305
  function makeCapability() {
2027
2306
  const stub = stubFetch([]);
2028
- const rest = new ${clientClass}({ token: "t", fetch: stub.fetch });
2307
+ const rest = ${factoryName}({ token: "t", fetch: stub.fetch });
2029
2308
  return new ${inputs.capabilityClass}(() => rest);
2030
2309
  }
2031
2310
 
2032
2311
  describe("${inputs.capabilityClass}", () => {
2033
2312
  it("constructs with a REST client", () => {
2034
- makeCapability();
2313
+ expect(makeCapability().key).toBe("${inputs.capability}");
2035
2314
  });
2036
2315
 
2037
2316
  // TODO: implement one test per ${inputs.capability} capability method
@@ -2047,14 +2326,11 @@ describe("${inputs.capabilityClass}", () => {
2047
2326
  //#endregion
2048
2327
  //#region src/commands/plugin-create/templates/eslint-config.ts
2049
2328
  function render$13(_inputs) {
2050
- return `import root from "../../eslint.config.js";
2329
+ return `import type { Linter } from "eslint";
2051
2330
 
2052
- export default [
2053
- ...root,
2054
- {
2055
- ignores: ["dist/**", "coverage/**"],
2056
- },
2057
- ];
2331
+ import root from "../../eslint.config.js";
2332
+
2333
+ export default [...root, { ignores: ["dist/**", "coverage/**"] }] satisfies Linter.Config[];
2058
2334
  `;
2059
2335
  }
2060
2336
  //#endregion
@@ -2137,10 +2413,17 @@ describe("AUTH_HINT", () => {
2137
2413
  //#endregion
2138
2414
  //#region src/commands/plugin-create/templates/package-json.ts
2139
2415
  function render$10(inputs) {
2416
+ const keywords = [
2417
+ inputs.capability,
2418
+ "holocron",
2419
+ "plugin",
2420
+ inputs.slug
2421
+ ].sort((a, b) => a.localeCompare(b));
2140
2422
  return JSON.stringify({
2141
2423
  name: `@theholocron/holocron-plugin-${inputs.slug}`,
2142
2424
  version: "2.0.0-alpha.1",
2143
2425
  description: `Holocron plugin for ${inputs.vendorName}. Implements the ${inputs.capability} capability against ${inputs.vendorName}'s REST API, plus exports verifyToken + AUTH_HINT for \`holocron auth\`.`,
2426
+ keywords,
2144
2427
  homepage: `https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-${inputs.slug}#readme`,
2145
2428
  bugs: "https://github.com/theholocron/holocron/issues",
2146
2429
  repository: {
@@ -2150,9 +2433,13 @@ function render$10(inputs) {
2150
2433
  },
2151
2434
  license: "MIT",
2152
2435
  author: "Newton Koumantzelis",
2436
+ sideEffects: false,
2153
2437
  type: "module",
2154
- main: "./src/index.ts",
2155
- exports: { ".": "./src/index.ts" },
2438
+ exports: { ".": {
2439
+ types: "./dist/index.d.mts",
2440
+ import: "./dist/index.mjs",
2441
+ default: "./dist/index.mjs"
2442
+ } },
2156
2443
  scripts: {
2157
2444
  "delivery.build": "tsdown",
2158
2445
  "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
@@ -2161,36 +2448,33 @@ function render$10(inputs) {
2161
2448
  "test:watch": "vitest",
2162
2449
  validate: "tsx scripts/validate.mjs"
2163
2450
  },
2164
- peerDependencies: { "@theholocron/cli": "workspace:*" },
2451
+ peerDependencies: {
2452
+ "@theholocron/cli": "workspace:*",
2453
+ "@theholocron/misc-utils": "catalog:utils"
2454
+ },
2165
2455
  devDependencies: {
2166
2456
  "@theholocron/cli": "workspace:*",
2167
- "@theholocron/tsconfig": "catalog:",
2168
- "@tsconfig/node-lts": "catalog:",
2457
+ "@theholocron/misc-utils": "catalog:utils",
2458
+ "@theholocron/tsconfig": "catalog:configs",
2459
+ "@types/node": "catalog:",
2169
2460
  "@vitest/coverage-v8": "catalog:",
2170
2461
  eslint: "catalog:",
2171
2462
  globals: "catalog:",
2172
- typescript: "catalog:",
2173
- vitest: "catalog:",
2174
2463
  tsdown: "catalog:",
2175
- tsx: "catalog:"
2176
- },
2177
- publishConfig: {
2178
- access: "public",
2179
- main: "./dist/index.mjs",
2180
- types: "./dist/index.d.mts",
2181
- exports: { ".": {
2182
- types: "./dist/index.d.mts",
2183
- import: "./dist/index.mjs",
2184
- default: "./dist/index.mjs"
2185
- } }
2464
+ tsx: "catalog:",
2465
+ typescript: "catalog:",
2466
+ vitest: "catalog:"
2186
2467
  },
2187
- files: ["dist", "README.md"]
2188
- }, null, " ") + "\n";
2468
+ engines: { node: ">=22" },
2469
+ publishConfig: { access: "public" },
2470
+ files: ["dist"]
2471
+ }, null, 2) + "\n";
2189
2472
  }
2190
2473
  //#endregion
2191
2474
  //#region src/commands/plugin-create/templates/plugin-index.ts
2192
2475
  function render$9(inputs) {
2193
2476
  const clientClass = `${inputs.vendorName}RestClient`;
2477
+ const factoryName = `create${inputs.vendorName}RestClient`;
2194
2478
  const capabilityInterface = inputs.capability.charAt(0).toUpperCase() + inputs.capability.slice(1);
2195
2479
  return `/**
2196
2480
  * \`@theholocron/holocron-plugin-${inputs.slug}\` — entrypoint.
@@ -2207,7 +2491,7 @@ function render$9(inputs) {
2207
2491
 
2208
2492
  import { resolveToken, type ResolveTokenInput } from "./auth.js";
2209
2493
  import { ${inputs.capabilityClass} } from "./capabilities/${inputs.capability}.js";
2210
- import { ${clientClass} } from "./rest.js";
2494
+ import { ${factoryName}, type ${clientClass} } from "./rest.js";
2211
2495
 
2212
2496
  export interface ${inputs.vendorName}PluginOptions extends ResolveTokenInput {
2213
2497
  /** Override base URL for tests. */
@@ -2228,10 +2512,12 @@ export function createContext(options: ${inputs.vendorName}PluginOptions): Plugi
2228
2512
  options,
2229
2513
  rest: () => {
2230
2514
  if (rest) return rest;
2231
- const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token: resolveToken(options) };
2515
+ const restOpts: { token: string; baseUrl?: string; fetch?: typeof fetch } = {
2516
+ token: resolveToken(options),
2517
+ };
2232
2518
  if (options.baseUrl !== undefined) restOpts.baseUrl = options.baseUrl;
2233
2519
  if (options.fetch !== undefined) restOpts.fetch = options.fetch;
2234
- return (rest = new ${clientClass}(restOpts));
2520
+ return (rest = ${factoryName}(restOpts));
2235
2521
  },
2236
2522
  };
2237
2523
  }
@@ -2265,7 +2551,7 @@ export const AUTH_HINT =
2265
2551
  // ── Public re-exports ────────────────────────────────────────────────
2266
2552
 
2267
2553
  export * from "./auth.js";
2268
- export { ${clientClass} } from "./rest.js";
2554
+ export { type ${clientClass}, ${factoryName} } from "./rest.js";
2269
2555
  export { ${inputs.capabilityClass} } from "./capabilities/${inputs.capability}.js";
2270
2556
  export { verifyToken } from "./verify-token.js";
2271
2557
  export type { VerifyTokenResult, VerifyTokenSuccess, VerifyTokenFailure } from "./verify-token.js";
@@ -2342,15 +2628,26 @@ Not yet published; capability methods are stubs.
2342
2628
  //#endregion
2343
2629
  //#region src/commands/plugin-create/templates/rest.ts
2344
2630
  function render$7(inputs) {
2345
- return `import { createRestClient, type RequestOptions, type RestClient } from "@theholocron/cli";
2631
+ const factoryName = `create${inputs.vendorName}RestClient`;
2632
+ const clientType = `${inputs.vendorName}RestClient`;
2633
+ return `import { createRestClient, type RestClient } from "@theholocron/cli";
2346
2634
 
2347
- export type { RequestOptions, RestClient };
2635
+ export type { RestClient };
2348
2636
 
2349
- export function ${`create${inputs.vendorName}RestClient`}(opts: {
2637
+ /**
2638
+ * TODO: narrow this to the specific ${inputs.vendorName} endpoints this
2639
+ * plugin's capability needs (see \`@theholocron/holocron-plugin-axiom\`'s
2640
+ * \`rest.ts\` for the pattern: an interface with one method per endpoint,
2641
+ * built internally via \`createRestClient\`). Starts as an alias for the
2642
+ * generic client so the scaffold compiles end to end immediately.
2643
+ */
2644
+ export type ${clientType} = RestClient;
2645
+
2646
+ export function ${factoryName}(opts: {
2350
2647
  \ttoken: string;
2351
2648
  \tbaseUrl?: string;
2352
2649
  \tfetch?: typeof fetch;
2353
- }): RestClient {
2650
+ }): ${clientType} {
2354
2651
  \treturn createRestClient({
2355
2652
  \t\tbaseUrl: opts.baseUrl ?? "${inputs.baseUrl}",
2356
2653
  \t\ttoken: opts.token,
@@ -2423,7 +2720,7 @@ describe("${factoryName}", () => {
2423
2720
  function render$5(inputs) {
2424
2721
  return JSON.stringify({
2425
2722
  display: `Holocron Plugin: ${inputs.vendorName}`,
2426
- extends: "@tsconfig/node-lts/tsconfig.json",
2723
+ extends: "@theholocron/tsconfig/node-lts",
2427
2724
  compilerOptions: {
2428
2725
  baseUrl: "./",
2429
2726
  outDir: "./dist",
@@ -2431,7 +2728,7 @@ function render$5(inputs) {
2431
2728
  },
2432
2729
  include: ["src/**/*.ts"],
2433
2730
  exclude: ["node_modules", "dist"]
2434
- }, null, " ") + "\n";
2731
+ }, null, 2) + "\n";
2435
2732
  }
2436
2733
  //#endregion
2437
2734
  //#region src/commands/plugin-create/templates/tsdown-config.ts
@@ -2492,6 +2789,7 @@ function render$3(inputs) {
2492
2789
 
2493
2790
  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- filled in by operator
2494
2791
  import { AuthError, createPlugin, resolveToken, verifyToken } from "../src/index.ts";
2792
+ import { errorMessage } from "@theholocron/misc-utils";
2495
2793
 
2496
2794
  const args = process.argv.slice(2);
2497
2795
 
@@ -2547,11 +2845,12 @@ console.log("Done. Fill in capability method calls above before shipping.");
2547
2845
  // ── helpers ────────────────────────────────────────────────────────
2548
2846
 
2549
2847
  /** Wrap a capability call, print ERROR + hint on failure. */
2848
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars -- called once a real capability check replaces the TODO example above
2550
2849
  async function runStep(body) {
2551
2850
  try {
2552
2851
  await body();
2553
2852
  } catch (err) {
2554
- const message = err instanceof Error ? err.message : String(err);
2853
+ const message = errorMessage(err);
2555
2854
  console.log(\` ✗ ERROR: \${message}\`);
2556
2855
  const hint = hintFor(message);
2557
2856
  if (hint) console.log(\` hint: \${hint}\`);
@@ -2586,7 +2885,7 @@ function hintFor(message) {
2586
2885
  //#endregion
2587
2886
  //#region src/commands/plugin-create/templates/verify-token.ts
2588
2887
  function render$2(inputs) {
2589
- const clientClass = `${inputs.vendorName}RestClient`;
2888
+ const factoryName = `create${inputs.vendorName}RestClient`;
2590
2889
  return `/**
2591
2890
  * \`verifyToken\` — plugin-level export used by \`holocron auth set\` +
2592
2891
  * \`holocron auth check\`. Hits a lightweight whoami-style endpoint
@@ -2603,19 +2902,10 @@ function render$2(inputs) {
2603
2902
  * \`/me\`, \`/account\`.
2604
2903
  */
2605
2904
 
2606
- import { ${clientClass} } from "./rest.js";
2607
-
2608
- export interface VerifyTokenSuccess {
2609
- ok: true;
2610
- subject: string;
2611
- }
2612
-
2613
- export interface VerifyTokenFailure {
2614
- ok: false;
2615
- message: string;
2616
- }
2905
+ import type { VerifyTokenResult } from "@theholocron/cli";
2906
+ import { errorMessage } from "@theholocron/misc-utils";
2617
2907
 
2618
- export type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
2908
+ import { ${factoryName} } from "./rest.js";
2619
2909
 
2620
2910
  interface MeResponse {
2621
2911
  /** Adjust to whatever ${inputs.vendorName}'s whoami endpoint returns. */
@@ -2630,18 +2920,17 @@ export interface VerifyTokenOptions {
2630
2920
  }
2631
2921
 
2632
2922
  export async function verifyToken(token: string, opts: VerifyTokenOptions = {}): Promise<VerifyTokenResult> {
2633
- const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token };
2923
+ const restOpts: { token: string; baseUrl?: string; fetch?: typeof fetch } = { token };
2634
2924
  if (opts.baseUrl !== undefined) restOpts.baseUrl = opts.baseUrl;
2635
2925
  if (opts.fetch !== undefined) restOpts.fetch = opts.fetch;
2636
- const rest = new ${clientClass}(restOpts);
2926
+ const rest = ${factoryName}(restOpts);
2637
2927
  try {
2638
2928
  const me = await rest.request<MeResponse>("/me");
2639
2929
  // Optional chaining because \`me\` is \`undefined\` on 204 / empty body.
2640
2930
  const subject = me?.email ?? me?.name ?? me?.id ?? "unknown";
2641
2931
  return { ok: true, subject: \`user @ \${subject}\` };
2642
2932
  } catch (err) {
2643
- const message = err instanceof Error ? err.message : String(err);
2644
- return { ok: false, message };
2933
+ return { ok: false, message: errorMessage(err) };
2645
2934
  }
2646
2935
  }
2647
2936
  `;
@@ -2659,18 +2948,14 @@ describe("verifyToken", () => {
2659
2948
  const stub = stubFetch([{ status: 200, body: { email: "user@example.com" } }]);
2660
2949
  const result = await verifyToken("token", { fetch: stub.fetch });
2661
2950
  expect(result.ok).toBe(true);
2662
- if (result.ok) {
2663
- expect(result.subject).toMatch(/user@example.com/);
2664
- }
2951
+ expect((result as { ok: boolean; subject?: string }).subject).toMatch(/user@example.com/);
2665
2952
  });
2666
2953
 
2667
2954
  it("returns ok:false with the error message on 401", async () => {
2668
2955
  const stub = stubFetch([{ status: 401, body: { messages: ["Invalid token"] } }]);
2669
2956
  const result = await verifyToken("bad", { fetch: stub.fetch });
2670
2957
  expect(result.ok).toBe(false);
2671
- if (!result.ok) {
2672
- expect(result.message).toMatch(/→ 401/);
2673
- }
2958
+ expect((result as { ok: boolean; message?: string }).message).toMatch(/→ 401/);
2674
2959
  });
2675
2960
 
2676
2961
  it("returns ok:false when the network layer throws", async () => {
@@ -2679,9 +2964,7 @@ describe("verifyToken", () => {
2679
2964
  };
2680
2965
  const result = await verifyToken("t", { fetch: throwing });
2681
2966
  expect(result.ok).toBe(false);
2682
- if (!result.ok) {
2683
- expect(result.message).toMatch(/network down/);
2684
- }
2967
+ expect((result as { ok: boolean; message?: string }).message).toMatch(/network down/);
2685
2968
  });
2686
2969
  });
2687
2970
  `;
@@ -2755,7 +3038,7 @@ const TEMPLATES = [
2755
3038
  render
2756
3039
  },
2757
3040
  {
2758
- path: "eslint.config.js",
3041
+ path: "eslint.config.ts",
2759
3042
  render: render$13
2760
3043
  },
2761
3044
  {
@@ -2901,7 +3184,7 @@ function runPluginCreate(input) {
2901
3184
  });
2902
3185
  print(" ✓ scaffold verified");
2903
3186
  } catch (err) {
2904
- const message = err instanceof Error ? err.message : String(err);
3187
+ const message = errorMessage(err);
2905
3188
  print(` ✗ verify failed — ${message}`);
2906
3189
  logger.warn({
2907
3190
  slug: inputs.slug,
@@ -3598,6 +3881,24 @@ const defaultLogin = async (cwd) => {
3598
3881
  };
3599
3882
  //#endregion
3600
3883
  //#region src/commands/secret-set.ts
3884
+ /**
3885
+ * `holocron secret set` — one-shot single-secret push.
3886
+ *
3887
+ * Complements `holocron secrets sync` (bulk vault → destinations) for
3888
+ * ad-hoc scenarios:
3889
+ * - Bootstrap secrets (e.g., NPM_TOKEN on theholocron/holocron itself
3890
+ * before the rest of the setup exists)
3891
+ * - One-off rotations that don't warrant a vault sync
3892
+ * - Setting secrets the vault doesn't track
3893
+ *
3894
+ * Value source resolution (in priority order):
3895
+ * 1. Positional `value` argument
3896
+ * 2. `--from-stdin` reads from stdin
3897
+ * 3. `--from-env <NAME>` reads from the named env var
3898
+ * 4. Implicit: env var matching the secret name (e.g., `NPM_TOKEN`)
3899
+ *
3900
+ * Errors clearly when no value can be sourced.
3901
+ */
3601
3902
  async function runSecretSet(input) {
3602
3903
  const print = input.print ?? ((line) => console.log(line));
3603
3904
  const logger = input.logger ?? getLogger();
@@ -3636,7 +3937,7 @@ async function runSecretSet(input) {
3636
3937
  scope
3637
3938
  };
3638
3939
  } catch (err) {
3639
- const message = err instanceof Error ? err.message : String(err);
3940
+ const message = errorMessage(err);
3640
3941
  print(` ✗ ${message}`);
3641
3942
  logger.warn({
3642
3943
  key: input.name,
@@ -3672,6 +3973,38 @@ function describeScope(scope) {
3672
3973
  }
3673
3974
  //#endregion
3674
3975
  //#region src/commands/secrets-sync.ts
3976
+ /**
3977
+ * `holocron secrets sync` — vault → destinations.
3978
+ *
3979
+ * Reads a named environment from the configured `vault` (1P
3980
+ * Environment / similar) as KEY=VALUE pairs, then fans those values
3981
+ * out to the configured destinations:
3982
+ *
3983
+ * - `secrets` capability (e.g., GH Actions secrets) — repo-scope
3984
+ * - `deployment` capability (e.g., Vercel env vars) — per-target
3985
+ * - local `.env` file (optional, planned for v5.1 — currently skipped
3986
+ * with a soft "not yet" note)
3987
+ *
3988
+ * Per-secret routing rules:
3989
+ *
3990
+ * - All keys go to `deployment` for each target the caller asks for
3991
+ * (defaults: production + preview)
3992
+ * - `secrets` (GH Actions) defaults to every key, repo-scoped — but a
3993
+ * caller can pass `githubSecretKeys` (an allowlist, from repeatable
3994
+ * `--github-secret KEY` CLI values) to restrict `secrets` to only
3995
+ * those keys, and `githubSecretScope` (same `{ kind }` shape `secret
3996
+ * set`'s own `--scope repo|env=NAME|org=NAME` parses to) to apply one
3997
+ * scope to all of them. A key not in the allowlist is skipped for
3998
+ * `secrets` entirely — still synced to `deployment` if configured.
3999
+ * Needed for a vault holding a mix of deploy-only secrets and one
4000
+ * CI-consumed, org-wide secret (holocron#781's Sentinel case: 4
4001
+ * Vercel-only keys + one org-scoped Axiom ingest token
4002
+ * `theholocron/.github`'s dispatched-check workflow also reads).
4003
+ *
4004
+ * The vault MUST implement `readEnvironment(envId)` (optional method).
4005
+ * If it doesn't, the command errors with a hint to populate the keys
4006
+ * individually via `holocron secret set` (also planned for v5.1).
4007
+ */
3675
4008
  async function runSecretsSync(input) {
3676
4009
  const print = input.print ?? ((line) => console.log(line));
3677
4010
  const logger = input.logger ?? getLogger();
@@ -3696,10 +4029,13 @@ async function runSecretsSync(input) {
3696
4029
  const rows = [];
3697
4030
  if (loader.has("secrets")) {
3698
4031
  const secrets = loader.get("secrets");
3699
- print(style.step("secrets (repo scope)"));
4032
+ const scope = input.githubSecretScope ?? { kind: "repo" };
4033
+ const allowedKeys = input.githubSecretKeys ? new Set(input.githubSecretKeys) : void 0;
4034
+ print(style.step("secrets"));
3700
4035
  for (const key of keys) {
3701
- rows.push(await runRow(`secrets:${secrets.providerName}`, "scope=repo", key, dryRun, async () => {
3702
- await secrets.setSecret({ kind: "repo" }, key, envVars[key]);
4036
+ if (allowedKeys && !allowedKeys.has(key)) continue;
4037
+ rows.push(await runRow(`secrets:${secrets.providerName}`, scopeLabel(scope), key, dryRun, async () => {
4038
+ await secrets.setSecret(scope, key, envVars[key]);
3703
4039
  }));
3704
4040
  print(formatRow(rows[rows.length - 1]));
3705
4041
  }
@@ -3779,7 +4115,7 @@ async function runRow(destination, scope, key, dryRun, body) {
3779
4115
  scope,
3780
4116
  key,
3781
4117
  status: "fail",
3782
- message: err instanceof Error ? err.message : String(err)
4118
+ message: errorMessage(err)
3783
4119
  };
3784
4120
  }
3785
4121
  }
@@ -3791,6 +4127,11 @@ function formatRow(row) {
3791
4127
  if (row.status === "dry-run") return ` ${style.dim(`… ${label}`)}`;
3792
4128
  return ` ${style.dim(`· ${label}`)}`;
3793
4129
  }
4130
+ function scopeLabel(scope) {
4131
+ if (scope.kind === "repo") return "scope=repo";
4132
+ if (scope.kind === "organization") return `scope=organization,org=${scope.name}`;
4133
+ return `scope=environment,env=${scope.name}`;
4134
+ }
3794
4135
  function vaultProviderName(loader) {
3795
4136
  if (!loader.has("vault")) return "<missing>";
3796
4137
  return loader.get("vault").providerName;
@@ -3804,16 +4145,26 @@ function vaultProviderName(loader) {
3804
4145
  * package has `bin`) → `platform` — matches `holocron` itself: the CLI is
3805
4146
  * the deliverable, the plugin packages are supporting infrastructure for
3806
4147
  * it, not separate products.
3807
- * 3. Single-package repo with `package.json#bin` → `cli`.
3808
- * 4. Docs-only site (astro/starlight present, root package private, no
4148
+ * 3. Monorepo with no CLI but at least one non-private workspace package →
4149
+ * `library` — matches `clients`/`configs`/`utils`/`themes`/
4150
+ * `observability`: a family of published packages, none of them a CLI.
4151
+ * Checked *before* falling into the root-package branch below, because
4152
+ * these repos' own root `package.json` is private and often carries
4153
+ * `@theholocron/astro-config` for a docs site built from the monorepo
4154
+ * root — without this check they'd wrongly resolve to `docs` off that
4155
+ * root-level signal alone, when the docs site is a secondary concern of
4156
+ * a library collection, not what the repo fundamentally is.
4157
+ * 4. Single-package repo with `package.json#bin` → `cli`.
4158
+ * 5. Docs-only site (astro/starlight present, root package private, no
3809
4159
  * publishable exports) → `docs`.
3810
- * 5. Private, non-publishable, non-docs → `app`.
3811
- * 6. Otherwise, a single publishable package → `library`.
4160
+ * 6. Private, non-publishable, non-docs → `app`.
4161
+ * 7. Otherwise, a single publishable package → `library`.
3812
4162
  */
3813
4163
  function deriveProfile(input) {
3814
4164
  if (/-template$/.test(input.repoName)) return "template";
3815
4165
  if (input.isMonorepo) {
3816
4166
  if (input.workspacePackageJsons.some((pkg) => Boolean(pkg.bin))) return "platform";
4167
+ if (input.workspacePackageJsons.some((pkg) => pkg.private !== true)) return "library";
3817
4168
  }
3818
4169
  const pkg = input.rootPackageJson;
3819
4170
  if (pkg?.bin) return "cli";
@@ -4023,6 +4374,9 @@ var alexignore_default = ".github/*\nCHANGELOG.md\nLICENSE\n";
4023
4374
  //#region src/templates/configs/alexjs/alexrc.json
4024
4375
  var alexrc_default = { allow: [
4025
4376
  "dead",
4377
+ "execute",
4378
+ "execution",
4379
+ "executes",
4026
4380
  "failure",
4027
4381
  "failures",
4028
4382
  "hook",
@@ -4041,12 +4395,21 @@ function createIgnoreConfig$1() {
4041
4395
  }
4042
4396
  //#endregion
4043
4397
  //#region src/templates/configs/commit-msg/commit-msg
4044
- var commit_msg_default = "# --config <resolved shared path> (config-resolution workstream, #676) — falls\n# back to commitlint's own auto-discovery of a local commitlint.config.ts when\n# the shared package's built dist/ isn't present (not installed, or a stale\n# install predating this file).\nCOMMITLINT_CONFIG=\"node_modules/@theholocron/commitlint-config/dist/index.js\"\nif [ -f \"$COMMITLINT_CONFIG\" ]; then\n npx --no -- commitlint --config \"$COMMITLINT_CONFIG\" --edit \"$1\"\nelse\n npx --no -- commitlint --edit \"$1\"\nfi\n";
4398
+ var commit_msg_default = "__HOLOCRON_SCRIPT__ lint commit-msg \"$1\"\n";
4045
4399
  //#endregion
4046
4400
  //#region src/templates/configs/commit-msg/create-config.ts
4047
4401
  const { workflowHeader: workflowHeader$8 } = createHeader({ source: "packages/cli/src/templates/configs/commit-msg/create-config.ts" });
4048
- function createConfig$7() {
4049
- return `${workflowHeader$8("shebang")}${commit_msg_default}`;
4402
+ /**
4403
+ * `.husky/commit-msg` — lints the commit message via `holocron lint
4404
+ * commit-msg` (holocron#789), the real programmatic replacement for
4405
+ * shelling out to `commitlint --edit`. Installed by `holocron setup` when
4406
+ * hooks are enabled. Same `__HOLOCRON_SCRIPT__` substitution as `pre-push`.
4407
+ *
4408
+ * @param holocronScript - the command that invokes the CLI. Defaults to
4409
+ * `pnpm exec holocron`; the source repo passes `node packages/cli/dist/cli.mjs`.
4410
+ */
4411
+ function createConfig$7(holocronScript = "pnpm exec holocron") {
4412
+ return `${workflowHeader$8("shebang")}${commit_msg_default.replace("__HOLOCRON_SCRIPT__", holocronScript)}`;
4050
4413
  }
4051
4414
  //#endregion
4052
4415
  //#region src/templates/configs/devmoji/create-config.ts
@@ -4062,7 +4425,7 @@ function createConfig$6() {
4062
4425
  }
4063
4426
  //#endregion
4064
4427
  //#region src/templates/configs/editorconfig/editorconfig
4065
- var editorconfig_default = "root = true\n\n[*]\nend_of_line = lf\ncharset = utf-8\ntrim_trailing_whitespace = true\ninsert_final_newline = true\nindent_style = tab\nindent_size = 4\n\n[.gitattributes]\nindent_style = space\nindent_size = 2\n\n[*.{json,yml,yaml}]\nindent_style = space\nindent_size = 2\n\n[*.{md,mdx}]\ntrim_trailing_whitespace = false\n\n[.*{rc,ignore}]\nindent_style = space\nindent_size = 2\n";
4428
+ var editorconfig_default = "root = true\n\n[*]\nend_of_line = lf\ncharset = utf-8\ntrim_trailing_whitespace = true\ninsert_final_newline = true\nindent_style = tab\nindent_size = 4\n\n[.gitattributes]\nindent_style = space\nindent_size = 2\n\n[*.{json,yml,yaml}]\nindent_style = space\nindent_size = 2\n\n[*.{md,mdx}]\ntrim_trailing_whitespace = false\nindent_style = unset\n\n[.*{rc,ignore}]\nindent_style = space\nindent_size = 2\n";
4066
4429
  //#endregion
4067
4430
  //#region src/templates/configs/editorconfig/create-config.ts
4068
4431
  const { workflowHeader: workflowHeader$6 } = createHeader({ source: "packages/cli/src/templates/configs/editorconfig/create-config.ts" });
@@ -4685,7 +5048,7 @@ async function upsertBranchProtection(source, dryRun, requiredChecks) {
4685
5048
  capability: "source",
4686
5049
  step,
4687
5050
  status: "fail",
4688
- message: err instanceof Error ? err.message : String(err)
5051
+ message: errorMessage(err)
4689
5052
  };
4690
5053
  }
4691
5054
  try {
@@ -4708,7 +5071,7 @@ async function upsertBranchProtection(source, dryRun, requiredChecks) {
4708
5071
  capability: "source",
4709
5072
  step,
4710
5073
  status: "fail",
4711
- message: err instanceof Error ? err.message : String(err)
5074
+ message: errorMessage(err)
4712
5075
  };
4713
5076
  }
4714
5077
  }
@@ -4801,7 +5164,7 @@ async function execStep(capability, step, dryRun, body, opts = {}) {
4801
5164
  capability,
4802
5165
  step,
4803
5166
  status: "fail",
4804
- message: err instanceof Error ? err.message : String(err)
5167
+ message: errorMessage(err)
4805
5168
  };
4806
5169
  }
4807
5170
  }
@@ -5042,7 +5405,10 @@ async function runSetup(input) {
5042
5405
  print(formatStep(steps[steps.length - 1]));
5043
5406
  if (effectivePreset && effectivePreset !== "none") {
5044
5407
  steps.push(await runStep("source", "updateRepoSettings", dryRun, async () => {
5045
- await source.updateRepoSettings(BALANCED_REPO_SETTINGS);
5408
+ await source.updateRepoSettings({
5409
+ ...BALANCED_REPO_SETTINGS,
5410
+ ...repo?.defaultBranch ? { default_branch: repo.defaultBranch } : {}
5411
+ });
5046
5412
  }));
5047
5413
  print(formatStep(steps[steps.length - 1]));
5048
5414
  const tasksConfig = { tasks: config.tasks };
@@ -5149,7 +5515,7 @@ async function runSetup(input) {
5149
5515
  }));
5150
5516
  print(formatStep(steps[steps.length - 1]));
5151
5517
  steps.push(await runStep("source", "write .husky/commit-msg", dryRun, async () => {
5152
- await source.writeRepoFile(".husky/commit-msg", createConfig$7());
5518
+ await source.writeRepoFile(".husky/commit-msg", createConfig$7(config.holocronScript));
5153
5519
  }));
5154
5520
  print(formatStep(steps[steps.length - 1]));
5155
5521
  if (hooksEnabled) {
@@ -5223,13 +5589,20 @@ async function runSetup(input) {
5223
5589
  await source.writeRepoFile("turbo.json", content);
5224
5590
  }));
5225
5591
  print(formatStep(steps[steps.length - 1]));
5226
- const rootPkg = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
5592
+ const rootPkgRaw = await readFile(join(input.context.repoRoot, "package.json"), "utf8").catch(() => null);
5593
+ const rootPkg = rootPkgRaw ? JSON.parse(rootPkgRaw) : null;
5227
5594
  const workspaceYaml = await readFile(join(input.context.repoRoot, "pnpm-workspace.yaml"), "utf8").catch(() => "");
5228
- const rootScripts = Object.keys(rootPkg?.scripts ?? {});
5595
+ const rootScripts = rootPkg?.scripts ?? {};
5229
5596
  const workspaceFix = astromechTurbo.ensureRootWorkspaceMember(workspaceYaml, rootScripts);
5230
5597
  if (workspaceFix.changed) steps.push(await runStep("source", "fix pnpm-workspace.yaml (root workspace member, #692)", dryRun, async () => {
5231
5598
  await source.writeRepoFile("pnpm-workspace.yaml", workspaceFix.content);
5232
5599
  }));
5600
+ if (rootPkgRaw) {
5601
+ const depFix = astromechTurbo.ensureTurboDependency(rootPkgRaw, workspaceFix.content);
5602
+ if (depFix.changed) steps.push(await runStep("source", "add turbo devDependency", dryRun, async () => {
5603
+ await source.writeRepoFile("package.json", depFix.content);
5604
+ }));
5605
+ }
5233
5606
  }
5234
5607
  print(formatStep(steps[steps.length - 1]));
5235
5608
  }
@@ -5240,7 +5613,7 @@ async function runSetup(input) {
5240
5613
  print(formatStep(steps[steps.length - 1]));
5241
5614
  }
5242
5615
  const properties = {};
5243
- if (effectivePreset && effectivePreset !== "none") properties["branch_protection_level"] = effectivePreset;
5616
+ if (effectivePreset && effectivePreset !== "none") properties["holocron_branch_protection_level"] = effectivePreset;
5244
5617
  const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
5245
5618
  properties["monorepo"] = String(isMonorepo);
5246
5619
  const manual = repo?.properties ?? {};
@@ -5258,9 +5631,9 @@ async function runSetup(input) {
5258
5631
  isMonorepo,
5259
5632
  workspacePackageJsons
5260
5633
  });
5261
- properties["holocron_stack"] = deriveStack(rootPackageJson).join(", ");
5634
+ properties["holocron_stack"] = deriveStack(rootPackageJson);
5262
5635
  const capabilities = deriveCapabilities(config.providers);
5263
- properties["holocron_capabilities"] = capabilities.join(", ");
5636
+ properties["holocron_capabilities"] = capabilities;
5264
5637
  properties["holocron_compliance"] = deriveCompliance(capabilities);
5265
5638
  }
5266
5639
  if (source.syncProperties) {
@@ -5281,34 +5654,36 @@ async function runSetup(input) {
5281
5654
  print(formatStep(steps[steps.length - 1]));
5282
5655
  }
5283
5656
  const teams = repo?.teams ?? [];
5284
- if (teams.length > 0) if (source.syncTeams) {
5285
- steps.push(await runStep("source", "sync teams", dryRun, () => source.syncTeams(teams), { skipCodes: [422] }));
5286
- print(formatStep(steps[steps.length - 1]));
5287
- const repoCoord = input.context.repo ?? repo?.name ?? "";
5288
- const org = repoCoord.includes("/") ? repoCoord.split("/")[0] : "";
5289
- const writeableTeams = teams.map((t) => typeof t === "string" ? {
5290
- slug: t,
5291
- permission: "push"
5292
- } : t).filter((t) => [
5293
- "push",
5294
- "maintain",
5295
- "admin"
5296
- ].includes(t.permission));
5297
- if (org && writeableTeams.length > 0) {
5298
- steps.push(await runStep("source", "write .github/CODEOWNERS", dryRun, async () => {
5299
- const content = writeableTeams.map((t) => `* @${org}/${t.slug}`).join("\n") + "\n";
5300
- await source.writeRepoFile(".github/CODEOWNERS", content);
5301
- }));
5657
+ if (teams.length > 0) {
5658
+ if (source.syncTeams) {
5659
+ steps.push(await runStep("source", "sync teams", dryRun, () => source.syncTeams(teams), { skipCodes: [422] }));
5660
+ print(formatStep(steps[steps.length - 1]));
5661
+ const repoCoord = input.context.repo ?? repo?.name ?? "";
5662
+ const org = repoCoord.includes("/") ? repoCoord.split("/")[0] : "";
5663
+ const writeableTeams = teams.map((t) => typeof t === "string" ? {
5664
+ slug: t,
5665
+ permission: "push"
5666
+ } : t).filter((t) => [
5667
+ "push",
5668
+ "maintain",
5669
+ "admin"
5670
+ ].includes(t.permission));
5671
+ if (org && writeableTeams.length > 0) {
5672
+ steps.push(await runStep("source", "write .github/CODEOWNERS", dryRun, async () => {
5673
+ const content = writeableTeams.map((t) => `* @${org}/${t.slug}`).join("\n") + "\n";
5674
+ await source.writeRepoFile(".github/CODEOWNERS", content);
5675
+ }));
5676
+ print(formatStep(steps[steps.length - 1]));
5677
+ }
5678
+ } else {
5679
+ steps.push({
5680
+ capability: "source",
5681
+ step: "sync teams",
5682
+ status: "skip",
5683
+ message: "provider does not implement syncTeams"
5684
+ });
5302
5685
  print(formatStep(steps[steps.length - 1]));
5303
5686
  }
5304
- } else {
5305
- steps.push({
5306
- capability: "source",
5307
- step: "sync teams",
5308
- status: "skip",
5309
- message: "provider does not implement syncTeams"
5310
- });
5311
- print(formatStep(steps[steps.length - 1]));
5312
5687
  }
5313
5688
  }
5314
5689
  if (loader.has("environments")) {
@@ -5364,11 +5739,9 @@ async function runSetup(input) {
5364
5739
  const wikiProxy = wiki.proxyConfig?.();
5365
5740
  if (wikiDns && loader.has("dns")) {
5366
5741
  const dns = loader.get("dns");
5367
- steps.push(await runStep("dns", `upsertRecord ${wikiDns.cname}`, dryRun, async () => {
5742
+ steps.push(await runStep("dns", `upsertRecord ${wikiDns.record.name}`, dryRun, async () => {
5368
5743
  await dns.upsertRecord(wikiDns.zone, {
5369
- type: "CNAME",
5370
- name: wikiDns.cname,
5371
- content: wikiDns.target,
5744
+ ...wikiDns.record,
5372
5745
  ttl: 1,
5373
5746
  ...wikiProxy ? { proxied: true } : {}
5374
5747
  });
@@ -5377,8 +5750,8 @@ async function runSetup(input) {
5377
5750
  }
5378
5751
  if (wikiProxy && wikiDns && loader.has("workers")) {
5379
5752
  const workers = loader.get("workers");
5380
- steps.push(await runStep("workers", `upsertProxy ${wikiDns.cname}`, dryRun, async () => {
5381
- await workers.upsertProxy(wikiDns.cname, wikiProxy);
5753
+ steps.push(await runStep("workers", `upsertProxy ${wikiDns.record.name}`, dryRun, async () => {
5754
+ await workers.upsertProxy(wikiDns.record.name, wikiProxy);
5382
5755
  }));
5383
5756
  print(formatStep(steps[steps.length - 1]));
5384
5757
  }
@@ -5391,11 +5764,31 @@ async function runSetup(input) {
5391
5764
  org: config.org,
5392
5765
  domain: config.domain
5393
5766
  }) : null;
5767
+ const ensureCustomDomain = async (projectId, hostname) => {
5768
+ if (!deploy.ensureCustomDomain) return;
5769
+ const customDomainDns = { value: null };
5770
+ steps.push(await runStep("deployment", `ensureCustomDomain ${hostname}`, dryRun, async () => {
5771
+ customDomainDns.value = await deploy.ensureCustomDomain(projectId, hostname);
5772
+ }));
5773
+ print(formatStep(steps[steps.length - 1]));
5774
+ if (customDomainDns.value && loader.has("dns")) {
5775
+ const dns = loader.get("dns");
5776
+ const dnsRecord = customDomainDns.value;
5777
+ steps.push(await runStep("dns", `upsertRecord ${dnsRecord.record.name}`, dryRun, async () => {
5778
+ await dns.upsertRecord(dnsRecord.zone, {
5779
+ ...dnsRecord.record,
5780
+ ttl: 1
5781
+ });
5782
+ }));
5783
+ print(formatStep(steps[steps.length - 1]));
5784
+ }
5785
+ };
5394
5786
  if (!previewCfg) {
5395
5787
  steps.push(await runStep("deployment", `ensureProject ${config.name}`, dryRun, async () => {
5396
5788
  await deploy.ensureProject({ name: config.name });
5397
5789
  }));
5398
5790
  print(formatStep(steps[steps.length - 1]));
5791
+ if (deploy.domain) await ensureCustomDomain(config.name, deploy.domain);
5399
5792
  }
5400
5793
  if (previewCfg) {
5401
5794
  steps.push(await runStep("deployment", `ensureProject ${previewCfg.project}`, dryRun, async () => {
@@ -5403,13 +5796,8 @@ async function runSetup(input) {
5403
5796
  }));
5404
5797
  print(formatStep(steps[steps.length - 1]));
5405
5798
  }
5406
- if (previewCfg?.domain && deploy.ensureCustomDomain) {
5407
- steps.push(await runStep("deployment", `ensureCustomDomain ${previewCfg.domain}`, dryRun, async () => {
5408
- await deploy.ensureCustomDomain(previewCfg.project, previewCfg.domain);
5409
- }));
5410
- print(formatStep(steps[steps.length - 1]));
5411
- }
5412
- if (previewCfg?.domain && loader.has("dns")) {
5799
+ if (previewCfg?.domain) await ensureCustomDomain(previewCfg.project, previewCfg.domain);
5800
+ if (previewCfg?.domain && deploy.providerName === "cloudflare" && loader.has("dns")) {
5413
5801
  const dns = loader.get("dns");
5414
5802
  const wildcardDomain = `*.${previewCfg.domain}`;
5415
5803
  steps.push(await runStep("dns", `upsertRecord ${previewCfg.domain}`, dryRun, async () => {
@@ -5483,7 +5871,7 @@ async function runSetup(input) {
5483
5871
  capability: "vault",
5484
5872
  step: "list",
5485
5873
  status: "fail",
5486
- message: err instanceof Error ? err.message : String(err)
5874
+ message: errorMessage(err)
5487
5875
  });
5488
5876
  }
5489
5877
  print(formatStep(steps[steps.length - 1]));
@@ -5699,7 +6087,7 @@ async function runSkillsInstall(input) {
5699
6087
  status: "ok"
5700
6088
  }, "skills install: done");
5701
6089
  } catch (err) {
5702
- const message = err instanceof Error ? err.message : String(err);
6090
+ const message = errorMessage(err);
5703
6091
  print(` ✗ ${message}`);
5704
6092
  logger.warn({
5705
6093
  agent: config.agent,
@@ -5857,11 +6245,13 @@ async function runSyncReadme(input) {
5857
6245
  }
5858
6246
  const description = loaded.resolved.description ?? "";
5859
6247
  const homepage = loaded.resolved.homepage ?? pkg.homepage ?? "";
6248
+ const scripts = pkg.scripts ?? {};
6249
+ const packages = pkg.name ? REGISTRY_MAP[pkg.name]?.() : void 0;
5860
6250
  const sections = generateReadme({
5861
6251
  description,
5862
6252
  homepage,
5863
- scripts: pkg.scripts ?? {},
5864
- packages: pkg.name ? REGISTRY_MAP[pkg.name]?.() : void 0
6253
+ scripts,
6254
+ packages
5865
6255
  });
5866
6256
  const markerSections = {
5867
6257
  ...sections.packages !== void 0 && { packages: sections.packages },
@@ -6103,7 +6493,7 @@ async function runSyncWiki(input) {
6103
6493
  capability: "local",
6104
6494
  step: "sync wiki",
6105
6495
  status: "fail",
6106
- message: err instanceof Error ? err.message : /* c8 ignore next */ String(err)
6496
+ message: err instanceof Error ? err.message : /* c8 ignore next */ String(err)
6107
6497
  };
6108
6498
  }
6109
6499
  }
@@ -6165,55 +6555,59 @@ async function runSync(input) {
6165
6555
  for (const stepName of SYNC_STEPS) {
6166
6556
  if (requestedSteps !== void 0 && !requestedSteps.includes(stepName)) continue;
6167
6557
  if (LOCAL_STEPS.has(stepName)) continue;
6168
- if (stepName === "labels") if (source.syncLabels) {
6169
- steps.push(await runSyncStep("source", "sync labels", dryRun, () => source.syncLabels(CANONICAL_LABELS, STALE_LABELS)));
6170
- print(formatSyncStep(steps[steps.length - 1]));
6171
- } else {
6172
- steps.push({
6173
- capability: "source",
6174
- step: "sync labels",
6175
- status: "skip",
6176
- message: "provider does not implement syncLabels"
6177
- });
6178
- print(formatSyncStep(steps[steps.length - 1]));
6558
+ if (stepName === "labels") {
6559
+ if (source.syncLabels) {
6560
+ steps.push(await runSyncStep("source", "sync labels", dryRun, () => source.syncLabels(CANONICAL_LABELS, STALE_LABELS)));
6561
+ print(formatSyncStep(steps[steps.length - 1]));
6562
+ } else {
6563
+ steps.push({
6564
+ capability: "source",
6565
+ step: "sync labels",
6566
+ status: "skip",
6567
+ message: "provider does not implement syncLabels"
6568
+ });
6569
+ print(formatSyncStep(steps[steps.length - 1]));
6570
+ }
6179
6571
  }
6180
- if (stepName === "properties") if (source.syncProperties) {
6181
- const repo = config.repo;
6182
- const properties = {};
6183
- const effectivePreset = repo?.protection;
6184
- if (effectivePreset && effectivePreset !== "none") properties["branch_protection_level"] = effectivePreset;
6185
- const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
6186
- properties["monorepo"] = String(isMonorepo);
6187
- const manual = repo?.properties ?? {};
6188
- if (manual.lifecycle) properties["lifecycle"] = manual.lifecycle;
6189
- if (manual.open_source !== void 0) properties["open_source"] = String(manual.open_source);
6190
- if (manual.runtime_environment) properties["runtime_environment"] = manual.runtime_environment;
6191
- if (manual.uses_external_packages !== void 0) properties["uses_external_packages"] = String(manual.uses_external_packages);
6192
- {
6193
- const rootPackageJson = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
6194
- const workspacePackages = readWorkspacePackages(input.context.repoRoot);
6195
- const workspacePackageJsons = await readWorkspacePackageJsons(input.context.repoRoot, workspacePackages);
6196
- properties["holocron_profile"] = deriveProfile({
6197
- rootPackageJson,
6198
- repoName: basename(input.context.repoRoot),
6199
- isMonorepo,
6200
- workspacePackageJsons
6572
+ if (stepName === "properties") {
6573
+ if (source.syncProperties) {
6574
+ const repo = config.repo;
6575
+ const properties = {};
6576
+ const effectivePreset = repo?.protection;
6577
+ if (effectivePreset && effectivePreset !== "none") properties["holocron_branch_protection_level"] = effectivePreset;
6578
+ const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
6579
+ properties["monorepo"] = String(isMonorepo);
6580
+ const manual = repo?.properties ?? {};
6581
+ if (manual.lifecycle) properties["lifecycle"] = manual.lifecycle;
6582
+ if (manual.open_source !== void 0) properties["open_source"] = String(manual.open_source);
6583
+ if (manual.runtime_environment) properties["runtime_environment"] = manual.runtime_environment;
6584
+ if (manual.uses_external_packages !== void 0) properties["uses_external_packages"] = String(manual.uses_external_packages);
6585
+ {
6586
+ const rootPackageJson = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
6587
+ const workspacePackages = readWorkspacePackages(input.context.repoRoot);
6588
+ const workspacePackageJsons = await readWorkspacePackageJsons(input.context.repoRoot, workspacePackages);
6589
+ properties["holocron_profile"] = deriveProfile({
6590
+ rootPackageJson,
6591
+ repoName: basename(input.context.repoRoot),
6592
+ isMonorepo,
6593
+ workspacePackageJsons
6594
+ });
6595
+ properties["holocron_stack"] = deriveStack(rootPackageJson);
6596
+ const capabilities = deriveCapabilities(config.providers);
6597
+ properties["holocron_capabilities"] = capabilities;
6598
+ properties["holocron_compliance"] = deriveCompliance(capabilities);
6599
+ }
6600
+ steps.push(await runSyncStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
6601
+ print(formatSyncStep(steps[steps.length - 1]));
6602
+ } else {
6603
+ steps.push({
6604
+ capability: "source",
6605
+ step: "sync properties",
6606
+ status: "skip",
6607
+ message: "provider does not implement syncProperties"
6201
6608
  });
6202
- properties["holocron_stack"] = deriveStack(rootPackageJson).join(", ");
6203
- const capabilities = deriveCapabilities(config.providers);
6204
- properties["holocron_capabilities"] = capabilities.join(", ");
6205
- properties["holocron_compliance"] = deriveCompliance(capabilities);
6609
+ print(formatSyncStep(steps[steps.length - 1]));
6206
6610
  }
6207
- steps.push(await runSyncStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
6208
- print(formatSyncStep(steps[steps.length - 1]));
6209
- } else {
6210
- steps.push({
6211
- capability: "source",
6212
- step: "sync properties",
6213
- status: "skip",
6214
- message: "provider does not implement syncProperties"
6215
- });
6216
- print(formatSyncStep(steps[steps.length - 1]));
6217
6611
  }
6218
6612
  if (stepName === "teams") {
6219
6613
  const teams = config.repo?.teams ?? [];
@@ -6425,29 +6819,34 @@ async function runSync(input) {
6425
6819
  }
6426
6820
  }
6427
6821
  }
6428
- if (stepName === "scripts") if (config.syncScripts === false) {
6429
- steps.push({
6430
- capability: "local",
6431
- step: "sync scripts",
6432
- status: "skip",
6433
- message: "syncScripts: false"
6434
- });
6435
- print(formatSyncStep(steps[steps.length - 1]));
6436
- } else {
6437
- const tasksConfig = { tasks: config.tasks };
6438
- if (config.holocronScript !== void 0) tasksConfig.holocronScript = config.holocronScript;
6439
- const desired = createAstromech({
6440
- cwd: input.context.repoRoot,
6441
- config: tasksConfig,
6442
- logger
6443
- }).packageScripts();
6444
- steps.push(await runSyncStep("local", "sync scripts", dryRun, async () => {
6445
- const changed = await mergePackageJsonScripts(input.context.repoRoot, desired);
6446
- if (changed === null) return "no package.json";
6447
- if (changed.length === 0) return `${Object.keys(desired).length} scripts already current`;
6448
- return `${changed.join(", ")} set`;
6449
- }));
6450
- print(formatSyncStep(steps[steps.length - 1]));
6822
+ if (stepName === "scripts") {
6823
+ if (config.syncScripts === false) {
6824
+ steps.push({
6825
+ capability: "local",
6826
+ step: "sync scripts",
6827
+ status: "skip",
6828
+ message: "syncScripts: false"
6829
+ });
6830
+ print(formatSyncStep(steps[steps.length - 1]));
6831
+ } else {
6832
+ const tasksConfig = { tasks: config.tasks };
6833
+ if (config.holocronScript !== void 0) tasksConfig.holocronScript = config.holocronScript;
6834
+ const astromechScripts = createAstromech({
6835
+ cwd: input.context.repoRoot,
6836
+ config: tasksConfig,
6837
+ logger
6838
+ });
6839
+ const desired = astromechScripts.packageScripts();
6840
+ const turboContent = astromechScripts.turboConfig();
6841
+ const turboEligible = new Set(turboContent ? Object.keys(JSON.parse(turboContent).tasks) : []);
6842
+ steps.push(await runSyncStep("local", "sync scripts", dryRun, async () => {
6843
+ const changed = await mergePackageJsonScripts(input.context.repoRoot, desired, turboEligible);
6844
+ if (changed === null) return "no package.json";
6845
+ if (changed.length === 0) return `${Object.keys(desired).length} scripts already current`;
6846
+ return `${changed.join(", ")} set`;
6847
+ }));
6848
+ print(formatSyncStep(steps[steps.length - 1]));
6849
+ }
6451
6850
  }
6452
6851
  if (stepName === "turbo") {
6453
6852
  const astromechTurbo = createAstromech({
@@ -6469,9 +6868,10 @@ async function runSync(input) {
6469
6868
  await writeFile(join(input.context.repoRoot, "turbo.json"), content, "utf8");
6470
6869
  }));
6471
6870
  print(formatSyncStep(steps[steps.length - 1]));
6472
- const rootPkg = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
6871
+ const rootPkgRaw = await readFile(join(input.context.repoRoot, "package.json"), "utf8").catch(() => null);
6872
+ const rootPkg = rootPkgRaw ? JSON.parse(rootPkgRaw) : null;
6473
6873
  const workspaceYaml = await readFile(join(input.context.repoRoot, "pnpm-workspace.yaml"), "utf8").catch(() => "");
6474
- const rootScripts = Object.keys(rootPkg?.scripts ?? {});
6874
+ const rootScripts = rootPkg?.scripts ?? {};
6475
6875
  const workspaceFix = astromechTurbo.ensureRootWorkspaceMember(workspaceYaml, rootScripts);
6476
6876
  if (workspaceFix.changed) {
6477
6877
  steps.push(await runSyncStep("local", "fix pnpm-workspace.yaml (root workspace member, #692)", dryRun, async () => {
@@ -6479,6 +6879,15 @@ async function runSync(input) {
6479
6879
  }));
6480
6880
  print(formatSyncStep(steps[steps.length - 1]));
6481
6881
  }
6882
+ if (rootPkgRaw) {
6883
+ const depFix = astromechTurbo.ensureTurboDependency(rootPkgRaw, workspaceFix.content);
6884
+ if (depFix.changed) {
6885
+ steps.push(await runSyncStep("local", "add turbo devDependency", dryRun, async () => {
6886
+ await writeFile(join(input.context.repoRoot, "package.json"), depFix.content, "utf8");
6887
+ }));
6888
+ print(formatSyncStep(steps[steps.length - 1]));
6889
+ }
6890
+ }
6482
6891
  }
6483
6892
  }
6484
6893
  if (stepName === "wiki") {
@@ -6536,7 +6945,7 @@ async function runSyncStep(capability, step, dryRun, body) {
6536
6945
  capability,
6537
6946
  step,
6538
6947
  status: "fail",
6539
- message: err instanceof Error ? err.message : String(err)
6948
+ message: errorMessage(err)
6540
6949
  };
6541
6950
  }
6542
6951
  }
@@ -6562,8 +6971,21 @@ async function writePackageJsonField(repoRoot, field, value) {
6562
6971
  * Merge `desired` script entries into `package.json#scripts` — sets only the
6563
6972
  * listed keys, never touches the rest. Returns the sorted list of keys that
6564
6973
  * drifted (empty when all current), or `null` when there is no `package.json`.
6974
+ *
6975
+ * `turboEligible` (#747): task names `turbo.json` fans out — the same set
6976
+ * {@link EnsureRootWorkspaceMemberResult} above already keys off. For those
6977
+ * only, an *existing* script that isn't the generated `holocron run <task>
6978
+ * --` wrapper is left untouched: root may genuinely be a directly-buildable
6979
+ * package (not an orchestrator) with its own real command (`tsc --noEmit`,
6980
+ * `vitest run`, …) for that task. Overwriting it would silently discard the
6981
+ * real command and, once `turbo.json` exists and root is a real workspace
6982
+ * member (#692), reintroduce infinite recursion — `turbo run <task>` →
6983
+ * root's own `<task>` script → the wrapper → `holocron run <task>` sees
6984
+ * `turbo.json` still defines the task → `turbo run <task>` again, forever.
6985
+ * Every other key (non-turbo tasks, `holocron`, `prepare`, …) has no
6986
+ * legitimate direct-command alternative and stays fully generator-owned.
6565
6987
  */
6566
- async function mergePackageJsonScripts(repoRoot, desired) {
6988
+ async function mergePackageJsonScripts(repoRoot, desired, turboEligible) {
6567
6989
  const pkgPath = join(repoRoot, "package.json");
6568
6990
  let content;
6569
6991
  try {
@@ -6574,15 +6996,31 @@ async function mergePackageJsonScripts(repoRoot, desired) {
6574
6996
  const pkg = JSON.parse(content);
6575
6997
  const scripts = pkg.scripts ?? {};
6576
6998
  const changed = [];
6577
- for (const [name, command] of Object.entries(desired)) if (scripts[name] !== command) {
6578
- scripts[name] = command;
6579
- changed.push(name);
6999
+ for (const [name, command] of Object.entries(desired)) {
7000
+ const existing = scripts[name];
7001
+ if (turboEligible.has(name) && existing !== void 0 && !isGeneratedRunWrapper(existing, name)) continue;
7002
+ if (existing !== command) {
7003
+ scripts[name] = command;
7004
+ changed.push(name);
7005
+ }
6580
7006
  }
6581
7007
  if (changed.length === 0) return [];
6582
7008
  pkg.scripts = scripts;
6583
7009
  await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
6584
7010
  return changed.sort();
6585
7011
  }
7012
+ /**
7013
+ * Matches the exact shape `packageScripts()` generates for `taskName` —
7014
+ * `<bin> run <taskName> --`, `<bin>` normally `holocron` but substitutable
7015
+ * (`holocronScript`, itself allowed to be multi-word, e.g. `"node
7016
+ packages/cli/dist/cli.mjs"` — see its own test). Checking the *suffix*
7017
+ * rather than the whole string means an old wrapper survives a
7018
+ * `holocronScript` rename intact — it's still recognized as a wrapper (safe
7019
+ * to update to the new one), not mistaken for a real command.
7020
+ */
7021
+ function isGeneratedRunWrapper(command, taskName) {
7022
+ return command.endsWith(` run ${taskName} --`);
7023
+ }
6586
7024
  const README_DESC_START = "<!-- holocron:description -->";
6587
7025
  const README_DESC_END = "<!-- /holocron:description -->";
6588
7026
  async function updateReadmeDescription(repoRoot, description) {
@@ -6954,7 +7392,7 @@ async function runSyncGithub(input) {
6954
7392
  sha: blob.sha
6955
7393
  });
6956
7394
  } catch (err) {
6957
- const msg = `failed to create blob for ${file.path}: ${err instanceof Error ? err.message : String(err)}`;
7395
+ const msg = `failed to create blob for ${file.path}: ${errorMessage(err)}`;
6958
7396
  print(` ✗ ${msg}`);
6959
7397
  return done({
6960
7398
  status: "fail",
@@ -6968,7 +7406,7 @@ async function runSyncGithub(input) {
6968
7406
  try {
6969
7407
  newTreeSha = (await client.git.createTree(repo, treeEntries, baseTreeSha)).sha;
6970
7408
  } catch (err) {
6971
- const msg = `failed to create tree: ${err instanceof Error ? err.message : String(err)}`;
7409
+ const msg = `failed to create tree: ${errorMessage(err)}`;
6972
7410
  print(` ✗ ${msg}`);
6973
7411
  return done({
6974
7412
  status: "fail",
@@ -6982,7 +7420,7 @@ async function runSyncGithub(input) {
6982
7420
  try {
6983
7421
  newCommitSha = (await client.git.createCommit(repo, message, newTreeSha, [headSha])).sha;
6984
7422
  } catch (err) {
6985
- const msg = `failed to create commit: ${err instanceof Error ? err.message : String(err)}`;
7423
+ const msg = `failed to create commit: ${errorMessage(err)}`;
6986
7424
  print(` ✗ ${msg}`);
6987
7425
  return done({
6988
7426
  status: "fail",
@@ -7001,7 +7439,7 @@ async function runSyncGithub(input) {
7001
7439
  }
7002
7440
  else await client.git.updateRef(repo, `heads/${targetBranch}`, newCommitSha);
7003
7441
  } catch (err) {
7004
- const msg = `failed to update ref: ${err instanceof Error ? err.message : String(err)}`;
7442
+ const msg = `failed to update ref: ${errorMessage(err)}`;
7005
7443
  print(` ✗ ${msg}`);
7006
7444
  return done({
7007
7445
  status: "fail",
@@ -7022,7 +7460,7 @@ async function runSyncGithub(input) {
7022
7460
  print(` → PR opened: ${prUrl}`);
7023
7461
  } catch (err) {
7024
7462
  if (err instanceof ProviderApiError && err.status === 422 && String(err.details).includes("already exists")) print(` → PR already open for ${branch} — branch updated, ready to merge`);
7025
- else print(` ⚠ PR creation failed: ${err instanceof Error ? err.message : String(err)}`);
7463
+ else print(` ⚠ PR creation failed: ${errorMessage(err)}`);
7026
7464
  }
7027
7465
  return done({
7028
7466
  status: "ok",
@@ -7449,6 +7887,63 @@ async function runUpgradeNode(input) {
7449
7887
  };
7450
7888
  }
7451
7889
  //#endregion
7890
+ //#region src/commit-lint/lint-message.ts
7891
+ /**
7892
+ * Lints one commit message string against an already-loaded commitlint
7893
+ * config. The genuinely environment-independent half of commit-message
7894
+ * linting (holocron#789) — *obtaining* a `QualifiedConfig` differs by
7895
+ * caller (Sentinel isolates itself from any ambient config since it runs
7896
+ * standalone, away from a real repo checkout; `lintCommitMsgFile` below
7897
+ * just lets cosmiconfig discover the invoking repo's own
7898
+ * `commitlint.config.*`, matching `commitlint --edit`'s own contract) —
7899
+ * but linting one message against a loaded config is identical either way.
7900
+ *
7901
+ * Real `@commitlint/lint` — the same programmatic API `@commitlint/cli`
7902
+ * itself uses internally — never a reimplementation of commitlint's rules.
7903
+ */
7904
+ /** `parserPreset.parserOpts`, if the loaded config sets one — same lookup `@commitlint/cli`'s own `selectParserOpts()` does. */
7905
+ function selectParserOpts(parserPreset) {
7906
+ return parserPreset?.parserOpts;
7907
+ }
7908
+ async function lintCommitMessage(message, loaded) {
7909
+ const opts = {
7910
+ /* istanbul ignore next -- see comment above */
7911
+ parserOpts: selectParserOpts(loaded.parserPreset) ?? {},
7912
+ plugins: loaded.plugins,
7913
+ /* istanbul ignore next -- see comment above */
7914
+ ignores: loaded.ignores ?? [],
7915
+ defaultIgnores: loaded.defaultIgnores !== false
7916
+ };
7917
+ const outcome = await lint(message, loaded.rules, opts);
7918
+ if (outcome.valid) return [];
7919
+ return outcome.errors.map((error) => ({
7920
+ rule: error.name,
7921
+ message: error.message
7922
+ }));
7923
+ }
7924
+ //#endregion
7925
+ //#region src/commit-lint/lint-commit-msg-file.ts
7926
+ /**
7927
+ * `holocron lint commit-msg <file>` — a real programmatic replacement for
7928
+ * shelling out to `commitlint --edit "$1"` from `.husky/commit-msg`
7929
+ * (holocron#789). Matches that CLI's own contract exactly: `file` is a
7930
+ * path to the commit message being written (the arg git's `commit-msg`
7931
+ * hook passes as `$1`), no `--config` override needed — `@commitlint/load`
7932
+ * runs from `cwd` with no seed, so cosmiconfig's own normal upward search
7933
+ * discovers the invoking repo's real `commitlint.config.*` file, exactly
7934
+ * as `commitlint --edit` (no `--config` flag) already does today. Unlike
7935
+ * Sentinel's `loadIsolatedConfig()`, no isolation is needed here — this
7936
+ * runs inside a real repo checkout with a real `node_modules`, not
7937
+ * standalone on a server.
7938
+ */
7939
+ async function lintCommitMsgFile(filePath, cwd = process.cwd()) {
7940
+ const violations = await lintCommitMessage(await readFile(filePath, "utf8"), await load({}, { cwd }));
7941
+ return {
7942
+ valid: violations.length === 0,
7943
+ violations
7944
+ };
7945
+ }
7946
+ //#endregion
7452
7947
  //#region src/config/load-config.ts
7453
7948
  /**
7454
7949
  * `holocron.config.{ts,js,mjs,cjs,json}` loader.
@@ -7463,14 +7958,19 @@ async function runUpgradeNode(input) {
7463
7958
  */
7464
7959
  const execFileAsync = promisify(execFile);
7465
7960
  /**
7466
- * Read + parse + resolve `holocron.config.*` from the given directory.
7961
+ * Read + parse + resolve `holocron.config.*` starting from the given
7962
+ * directory, walking up through ancestors to the nearest `.git` boundary
7963
+ * when `cwd` itself has no match — every command is usable from any
7964
+ * subdirectory of a repo, not only its exact root (see
7965
+ * `@theholocron/datapad`'s own doc comment for the stop conditions).
7467
7966
  * Throws {@link ConfigFileError} when nothing is found or a file cannot
7468
- * be loaded, or `ConfigError` when the config is invalid.
7967
+ * be loaded, or `ConfigError` when the config fails schema checks.
7469
7968
  */
7470
7969
  async function loadConfig(cwd) {
7471
7970
  const found = await loadConfigFile({
7472
7971
  cwd,
7473
- name: "holocron"
7972
+ name: "holocron",
7973
+ walkUp: true
7474
7974
  });
7475
7975
  if (!found) throw new ConfigFileError(`no holocron.config.{ts,js,mjs,cjs,json} found in ${cwd}. Create one — see the README for the schema.`);
7476
7976
  return {
@@ -7559,18 +8059,20 @@ const numeric = (value) => /^\d+$/.test(value) ? true : "enter a number";
7559
8059
  * The full command surface, hand-maintained in parallel with `cli.ts`'s
7560
8060
  * yargs registrations (this module does not introspect yargs at runtime).
7561
8061
  * `run <task>` is deliberately excluded — it's CI/scripting-oriented, and an
7562
- * interactive prompt in front of it would work against that.
8062
+ * interactive prompt in front of it would work against that. `lint
8063
+ * commit-msg <file>` is excluded for the same reason: it's invoked
8064
+ * exclusively from `.husky/commit-msg "$1"`, never typed by a human.
7563
8065
  */
7564
8066
  const COMMAND_REGISTRY = [
7565
- {
7566
- name: "version",
7567
- description: "Print the CLI version",
7568
- positionals: []
7569
- },
7570
8067
  {
7571
8068
  name: "clone",
7572
- description: "Clone all repos in a GitHub org as siblings under a single directory",
7573
- positionals: []
8069
+ description: "Clone a single repo (org/repo) or every repo in an org (org)",
8070
+ positionals: [{
8071
+ key: "target",
8072
+ message: "org/repo to clone (or a bare org to clone every repo in it):",
8073
+ type: "input",
8074
+ validate: (v) => v.trim().length > 0 || "org/repo or org is required"
8075
+ }]
7574
8076
  },
7575
8077
  {
7576
8078
  name: "doctor",
@@ -7843,10 +8345,25 @@ function buildChildArgv(entry, positionals, parentArgv) {
7843
8345
  ...forwardedFlags(parentArgv)
7844
8346
  ];
7845
8347
  }
7846
- /** Spawn `holocron <...args>` inheriting stdio; resolve with its exit code. */
8348
+ /**
8349
+ * Spawn `holocron <...args>` inheriting stdio; resolve with its exit code.
8350
+ *
8351
+ * `NO_UPDATE_NOTIFIER` is forced on in the child's env — the parent's own
8352
+ * update-notifier tail still runs after this resolves (see `launchMenu`'s
8353
+ * docstring), so without this the freshly-spawned child independently runs
8354
+ * its own `checkForUpdates()` too and the notice prints twice: once from
8355
+ * the child right after its command output, once more from the parent
8356
+ * once the child exits.
8357
+ */
7847
8358
  function spawnChild(args) {
7848
8359
  return new Promise((resolve) => {
7849
- const child = spawn(process.execPath, [process.argv[1], ...args], { stdio: "inherit" });
8360
+ const child = spawn(process.execPath, [process.argv[1], ...args], {
8361
+ stdio: "inherit",
8362
+ env: {
8363
+ ...process.env,
8364
+ NO_UPDATE_NOTIFIER: "1"
8365
+ }
8366
+ });
7850
8367
  child.on("exit", (code) => resolve(code ?? 0));
7851
8368
  child.on("error", () => resolve(1));
7852
8369
  });
@@ -7870,7 +8387,7 @@ async function launchMenu(entries, parentArgv, pickMessage, nonInteractiveMessag
7870
8387
  //#endregion
7871
8388
  //#region src/update-notifier.ts
7872
8389
  const PACKAGE_NAME = "@theholocron/cli";
7873
- const CACHE_TTL_MS = 1440 * 60 * 1e3;
8390
+ const CACHE_TTL_MS = 864e5;
7874
8391
  const FETCH_TIMEOUT_MS = 3e3;
7875
8392
  function getCacheDir() {
7876
8393
  return env.get("HOLOCRON_CACHE_DIR") ?? join(homedir(), ".cache", "holocron");
@@ -8053,7 +8570,7 @@ let finishCommand = () => {};
8053
8570
  /** Set by `.fail()` once it has printed an error, so the outer catch doesn't repeat it. */
8054
8571
  let errorReported = false;
8055
8572
  try {
8056
- await yargs(hideBin(process.argv)).scriptName("").usage("holocron <command> [options]").parserConfiguration({ "populate--": true }).option("dry-run", {
8573
+ await yargs(hideBin(process.argv)).scriptName("").usage("holocron <command> [options]").version(CLI_VERSION).alias("version", "v").parserConfiguration({ "populate--": true }).option("dry-run", {
8057
8574
  type: "boolean",
8058
8575
  default: false,
8059
8576
  describe: "Print what would be mutated without calling capability mutators. Commands branch on this; read-only commands ignore it."
@@ -8088,12 +8605,9 @@ try {
8088
8605
  org: argv.org
8089
8606
  });
8090
8607
  finishCommand = startCommand(name);
8091
- }).command("version", "Print the CLI version", () => {}, () => {
8092
- console.log(`holocron ${CLI_VERSION}`);
8093
- }).command("clone", "Clone all repos in a GitHub org as siblings under a single directory", (y) => y.option("org", {
8608
+ }).command("clone [target]", "Clone a single repo (org/repo) or every repo in an org (org)", (y) => y.positional("target", {
8094
8609
  type: "string",
8095
- demandOption: true,
8096
- describe: "GitHub org to clone (e.g., theholocron)"
8610
+ describe: "org/repo to clone, or a bare org to clone every repo in it (confirms first)."
8097
8611
  }).option("dir", {
8098
8612
  type: "string",
8099
8613
  describe: "Parent directory to clone into (default: ~/Code/<org>)"
@@ -8108,11 +8622,22 @@ try {
8108
8622
  process.exitCode = 1;
8109
8623
  return;
8110
8624
  }
8625
+ const [targetInput] = await promptForPositionals(getEntry("clone"), argv);
8626
+ const { org, repo } = parseCloneTarget(targetInput);
8111
8627
  if ((await runClone({
8112
- org: argv.org,
8628
+ org,
8629
+ ...repo ? { repo } : {},
8113
8630
  token,
8114
8631
  dryRun: argv.dryRun,
8115
- ...argv.dir ? { dir: argv.dir } : {}
8632
+ ...argv.dir ? { dir: argv.dir } : {},
8633
+ ...!repo ? { confirmWholeOrg: async ({ total, alreadyCloned, toClone }) => {
8634
+ if (!process.stdin.isTTY) throw new NonInteractiveError(`clone: cloning every repo in "${org}" needs interactive confirmation — run this from a terminal, or pass a specific org/repo instead`);
8635
+ if (toClone === 0) return true;
8636
+ return confirm({
8637
+ message: `${org} has ${total} repos — ${alreadyCloned} already cloned locally, ${toClone} new. Clone them all?`,
8638
+ default: false
8639
+ });
8640
+ } } : {}
8116
8641
  })).status === "fail") process.exitCode = 1;
8117
8642
  }).command("doctor", "Load the config and run a smoke check against every provider", (y) => y.option("repo", {
8118
8643
  type: "string",
@@ -8236,9 +8761,17 @@ try {
8236
8761
  type: "array",
8237
8762
  default: ["production", "preview"],
8238
8763
  describe: "Deployment targets to sync to. Defaults to production + preview."
8764
+ }).option("github-secret", {
8765
+ type: "array",
8766
+ describe: "Vault key(s) to push to GH Actions secrets (repeatable). Omit to push every key."
8767
+ }).option("github-secret-scope", {
8768
+ type: "string",
8769
+ default: "repo",
8770
+ describe: "Scope applied to every --github-secret key: \"repo\" (default), \"env=<name>\", or \"org=<name>\"."
8239
8771
  }), async (argv) => {
8240
8772
  const tokens = tokenContext(argv.token);
8241
8773
  if (!tokens) return;
8774
+ const githubSecretScope = parseScope(argv.githubSecretScope);
8242
8775
  const [environmentId] = await promptForPositionals(getEntry("secrets sync"), argv);
8243
8776
  const loaded = await loadConfig(argv.cwd);
8244
8777
  applyResolvedConfig(argv, loaded.resolved);
@@ -8252,11 +8785,13 @@ try {
8252
8785
  },
8253
8786
  environmentId,
8254
8787
  ...argv.projectId ? { projectId: argv.projectId } : {},
8788
+ ...argv.githubSecret?.length ? { githubSecretKeys: argv.githubSecret } : {},
8789
+ githubSecretScope,
8255
8790
  targets: argv.target
8256
8791
  })).summary.fail > 0) process.exitCode = 1;
8257
8792
  }).command("deploy [branch]", "Trigger a deployment via the configured `deployment` capability", (y) => y.positional("branch", {
8258
8793
  type: "string",
8259
- describe: "Git branch to deploy"
8794
+ describe: "Git branch to deploy (omit when using --files)"
8260
8795
  }).option("project-id", {
8261
8796
  type: "string",
8262
8797
  demandOption: true,
@@ -8265,20 +8800,34 @@ try {
8265
8800
  type: "string",
8266
8801
  choices: ["production", "staging"],
8267
8802
  describe: "Named environment to deploy into. Omit for a branch preview."
8268
- }), async (argv) => {
8803
+ }).option("files", {
8804
+ type: "string",
8805
+ describe: "Deploy from a local directory of source files instead of a Git branch — calls deployFunction(), no linked repo required. Conflicts with `branch`."
8806
+ }).conflicts("files", "branch"), async (argv) => {
8269
8807
  const tokens = tokenContext(argv.token);
8270
8808
  if (!tokens) return;
8271
- const [branch] = await promptForPositionals(getEntry("deploy"), argv);
8272
8809
  const loaded = await loadConfig(argv.cwd);
8273
8810
  applyResolvedConfig(argv, loaded.resolved);
8811
+ const context = {
8812
+ repoRoot: argv.cwd,
8813
+ dryRun: argv.dryRun,
8814
+ ...tokens,
8815
+ org: resolveOrg(argv, loaded.resolved)
8816
+ };
8817
+ if (argv.files) {
8818
+ if ((await runDeployFromFiles({
8819
+ loaded,
8820
+ context,
8821
+ projectId: argv.projectId,
8822
+ dir: argv.files,
8823
+ ...argv.target ? { target: argv.target } : {}
8824
+ })).status === "fail") process.exitCode = 1;
8825
+ return;
8826
+ }
8827
+ const [branch] = await promptForPositionals(getEntry("deploy"), argv);
8274
8828
  if ((await runDeploy({
8275
8829
  loaded,
8276
- context: {
8277
- repoRoot: argv.cwd,
8278
- dryRun: argv.dryRun,
8279
- ...tokens,
8280
- org: resolveOrg(argv, loaded.resolved)
8281
- },
8830
+ context,
8282
8831
  projectId: argv.projectId,
8283
8832
  branch,
8284
8833
  ...argv.target ? { target: argv.target } : {}
@@ -8454,7 +9003,36 @@ try {
8454
9003
  scope: argv.all ? "all" : "required",
8455
9004
  ...argv.filter ? { filter: argv.filter } : {}
8456
9005
  }).status === "fail") process.exitCode = 1;
8457
- }).command("sync-github", "Sync workflow templates and composite actions to theholocron/.github", (y) => y.option("repo", {
9006
+ }).command("deploy-on-release", "Deploy every workspace package whose delivery.deploy task is `on: release` — run by the delivery.publish workflow's deploy job", (y) => y.option("channel", {
9007
+ type: "string",
9008
+ default: "",
9009
+ describe: "The release's channel: its prerelease identifier (`alpha`); empty or `main` for a stable release."
9010
+ }).option("from", {
9011
+ type: "string",
9012
+ describe: "The previous release's commit, to diff against. Omit when there is none."
9013
+ }).option("to", {
9014
+ type: "string",
9015
+ describe: "The release commit. Default HEAD."
9016
+ }), async (argv) => {
9017
+ if ((await deployOnRelease({
9018
+ cwd: argv.cwd,
9019
+ channel: argv.channel,
9020
+ ...argv.from ? { from: argv.from } : {},
9021
+ ...argv.to ? { to: argv.to } : {},
9022
+ dryRun: argv.dryRun,
9023
+ print: (line) => console.log(line)
9024
+ })).status === "fail") process.exitCode = 1;
9025
+ }).command("lint", "Lint content locally against the org's shared rules", (y) => y.command("commit-msg <file>", "Lint a commit message file — matches `commitlint --edit`'s own contract, for use from .husky/commit-msg", (yy) => yy.positional("file", {
9026
+ type: "string",
9027
+ demandOption: true,
9028
+ describe: "Path to the commit message file (git's commit-msg hook passes this as $1)."
9029
+ }), async (argv) => {
9030
+ const result = await lintCommitMsgFile(argv.file, argv.cwd);
9031
+ if (!result.valid) {
9032
+ for (const violation of result.violations) console.error(`✖ ${violation.rule}: ${violation.message}`);
9033
+ process.exitCode = 1;
9034
+ }
9035
+ }), () => {}).command("sync-github", "Sync workflow templates and composite actions to theholocron/.github", (y) => y.option("repo", {
8458
9036
  type: "string",
8459
9037
  default: "theholocron/.github",
8460
9038
  describe: "Target org/repo (default: theholocron/.github)"
@@ -8896,6 +9474,7 @@ try {
8896
9474
  }).command("$0", false, () => {}, async (argv) => {
8897
9475
  await launchMenu(COMMAND_REGISTRY.filter((e) => e.group === "auth"), argv, "auth — choose a subcommand:", "Run `holocron auth --help` to see available auth subcommands.");
8898
9476
  }), () => {}).command("$0", false, () => {}, async (argv) => {
9477
+ console.log(style.dim(`holocron v${CLI_VERSION}`));
8899
9478
  await launchMenu(COMMAND_REGISTRY.filter((e) => !e.group), argv);
8900
9479
  }).strict().help().epilogue(`Execution contexts:
8901
9480
  global works from a bare 'npm i -g': ${commandsInContext("global").join(", ")}\n repo-aware needs ./holocron.config in cwd: ${commandsInContext("repo-aware").join(", ")}\n workspace also needs the plugin packages: ${commandsInContext("workspace").join(", ")}\n https://theholocron.github.io/holocron/execution-contexts`).fail((msg, err) => {