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

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";
4
+ import path, { basename, dirname, join, relative, resolve, sep } from "node:path";
5
5
  import { checkbox, input, select } from "@inquirer/prompts";
6
- import { KNOWN_WORKFLOWS, createAstromech, extractPreviewConfig, readWorkspacePackages, reusableTemplates } from "@theholocron/astromech";
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,
@@ -1106,13 +1112,15 @@ async function runClone(input) {
1106
1112
  }).status };
1107
1113
  });
1108
1114
  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 });
1115
+ if (!existsSync(targetDir)) {
1116
+ if (dryRun) print(style.dim(` would create ${targetDir}`));
1117
+ else mkdirSync(targetDir, { recursive: true });
1118
+ }
1111
1119
  let repos;
1112
1120
  try {
1113
1121
  repos = await listOrgRepos(input.org, input.token, fetchFn);
1114
1122
  } catch (err) {
1115
- const message = err instanceof Error ? err.message : String(err);
1123
+ const message = errorMessage(err);
1116
1124
  logger.warn({
1117
1125
  org: input.org,
1118
1126
  reason: message
@@ -1129,7 +1137,8 @@ async function runClone(input) {
1129
1137
  let skipped = 0;
1130
1138
  let failed = 0;
1131
1139
  for (const repo of repos) {
1132
- const dest = join(targetDir, repo.name.startsWith(".") ? repo.name.slice(1) : repo.name);
1140
+ const dirName = repo.name.startsWith(".") ? repo.name.slice(1) : repo.name;
1141
+ const dest = join(targetDir, dirName);
1133
1142
  if (existsSync(dest)) {
1134
1143
  print(style.dim(` skip ${repo.full_name}`));
1135
1144
  skipped++;
@@ -1151,7 +1160,7 @@ async function runClone(input) {
1151
1160
  try {
1152
1161
  encodedToken = encodeTokenForGitHttpAuth(input.token);
1153
1162
  } catch (err) {
1154
- print(style.fail(` failed ${repo.full_name} — invalid token format: ${err instanceof Error ? err.message : String(err)}`));
1163
+ print(style.fail(` failed ${repo.full_name} — invalid token format: ${errorMessage(err)}`));
1155
1164
  failed++;
1156
1165
  continue;
1157
1166
  }
@@ -1199,7 +1208,6 @@ async function runClone(input) {
1199
1208
  * resolve (devDeps in a repo, or `pnpm exec`).
1200
1209
  */
1201
1210
  const COMMAND_CONTEXTS = {
1202
- version: "global",
1203
1211
  clone: "global",
1204
1212
  new: "global",
1205
1213
  "upgrade node": "global",
@@ -1214,8 +1222,10 @@ const COMMAND_CONTEXTS = {
1214
1222
  "skills install": "global",
1215
1223
  "skills remove": "global",
1216
1224
  "skills update": "global",
1225
+ "lint commit-msg": "global",
1217
1226
  run: "repo-aware",
1218
1227
  ci: "repo-aware",
1228
+ "deploy-on-release": "repo-aware",
1219
1229
  "config show": "repo-aware",
1220
1230
  "sync-readme": "repo-aware",
1221
1231
  doctor: "workspace",
@@ -1233,6 +1243,80 @@ function commandsInContext(context) {
1233
1243
  }
1234
1244
  //#endregion
1235
1245
  //#region src/commands/deploy.ts
1246
+ /**
1247
+ * `holocron deploy` — trigger a deployment via the configured
1248
+ * `deployment` capability.
1249
+ *
1250
+ * Two modes, one command: `runDeploy` (the default — a Git branch,
1251
+ * `triggerDeployment()`) and `runDeployFromFiles` (`--files <dir>` —
1252
+ * a local directory of source files, `deployFunction()`, no linked
1253
+ * repo required — for a consumer with no Git history to deploy from,
1254
+ * e.g. Sentinel, shipped as an npm package). Separate functions, not
1255
+ * one branching `runDeploy`, because their inputs genuinely differ
1256
+ * (`branch` vs `dir`) and their result shapes differ too
1257
+ * (`DeploymentRecord` carries `status`/`branch`; `DeployFunctionResult`
1258
+ * is deliberately minimal, same as `DeployScriptResult` for Workers).
1259
+ *
1260
+ * Errors clearly when `deployment` isn't loaded (no provider declared
1261
+ * in `holocron.config.json`), or when the configured provider doesn't
1262
+ * implement `deployFunction` (it's optional on `Deployment` — not
1263
+ * every provider has a files-based deploy API).
1264
+ *
1265
+ * Dry-run skips the actual deploy call but still verifies the
1266
+ * deployment capability (and, for `--files`, `deployFunction`) is
1267
+ * present, so operators can sanity-check the wiring without spinning
1268
+ * up a build.
1269
+ *
1270
+ * **Both modes wait for the deployment to finish** (holocron#911): a
1271
+ * provider accepting the upload/trigger is not the deployment succeeding.
1272
+ * Vercel builds asynchronously — an `npm install` failure there leaves
1273
+ * the deployment in `ERROR` while production keeps serving the previous
1274
+ * one, and this command used to report `ok` regardless (found live:
1275
+ * Sentinel's holocron#910 deploy "succeeded" in CI, never went live). So
1276
+ * after triggering, {@link waitForDeployment} polls
1277
+ * `Deployment.getDeployment()` until a terminal state; only `ready` is
1278
+ * `ok`, while `error` / `cancelled` / a timeout are `fail` (non-zero exit
1279
+ * via `cli.ts`).
1280
+ */
1281
+ const DEFAULT_WAIT_TIMEOUT_MS = 6e5;
1282
+ const DEFAULT_WAIT_INTERVAL_MS = 5e3;
1283
+ const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
1284
+ "ready",
1285
+ "error",
1286
+ "cancelled"
1287
+ ]);
1288
+ /**
1289
+ * Polls `getDeployment(id)` until the deployment reaches a terminal status
1290
+ * (`ready` / `error` / `cancelled`). Throws on timeout — the caller turns
1291
+ * that into a `fail` report, same as a provider throwing mid-trigger.
1292
+ */
1293
+ async function waitForDeployment(deploy, deploymentId, options = {}) {
1294
+ const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
1295
+ const intervalMs = options.intervalMs ?? DEFAULT_WAIT_INTERVAL_MS;
1296
+ const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
1297
+ const now = options.now ?? Date.now;
1298
+ const deadline = now() + timeoutMs;
1299
+ for (;;) {
1300
+ const record = await deploy.getDeployment(deploymentId);
1301
+ if (TERMINAL_STATUSES.has(record.status)) return record;
1302
+ if (now() >= deadline) throw new Error(`deployment ${deploymentId} still ${record.status} after ${Math.round(timeoutMs / 1e3)}s — check the provider's dashboard`);
1303
+ await sleep(intervalMs);
1304
+ }
1305
+ }
1306
+ /** One terminal, non-ready record as a single human-readable failure line. */
1307
+ function terminalFailure(record) {
1308
+ return `deployment ${record.id} ended ${record.status}${record.errorMessage ? `: ${record.errorMessage}` : ""}`;
1309
+ }
1310
+ /**
1311
+ * Provider `url` fields (Vercel's REST API, at least) come back as bare
1312
+ * hostnames — `"my-app.vercel.app"`, no scheme — which terminals don't
1313
+ * linkify and browsers won't navigate to unmodified. Printed output
1314
+ * should be a URL a human can click/paste; structured log fields keep
1315
+ * the raw provider value as-is.
1316
+ */
1317
+ function withScheme(url) {
1318
+ return /^https?:\/\//.test(url) ? url : `https://${url}`;
1319
+ }
1236
1320
  async function runDeploy(input) {
1237
1321
  const print = input.print ?? ((line) => console.log(line));
1238
1322
  const logger = input.logger ?? getLogger();
@@ -1259,23 +1343,43 @@ async function runDeploy(input) {
1259
1343
  };
1260
1344
  }
1261
1345
  try {
1262
- const record = await withSpinner(`Deploying ${input.branch}${input.target ? ` → ${input.target}` : ""}…`, () => deploy.triggerDeployment({
1346
+ const triggered = await withSpinner(`Deploying ${input.branch}${input.target ? ` → ${input.target}` : ""}…`, () => deploy.triggerDeployment({
1263
1347
  projectId: input.projectId,
1264
1348
  branch: input.branch,
1265
1349
  ...input.target ? { target: input.target } : {}
1266
1350
  }));
1267
- print(` ${style.success(`${record.status} — ${record.url}`)}`);
1351
+ logger.info({
1352
+ status: triggered.status,
1353
+ url: triggered.url,
1354
+ id: triggered.id
1355
+ }, "deploy: triggered");
1356
+ const record = TERMINAL_STATUSES.has(triggered.status) ? triggered : await withSpinner(`Waiting for ${withScheme(triggered.url)} to finish…`, () => waitForDeployment(deploy, triggered.id, input.wait));
1357
+ if (record.status !== "ready") {
1358
+ const message = terminalFailure(record);
1359
+ print(` ${style.fail(`${message} — ${withScheme(triggered.url)}`)}`);
1360
+ logger.warn({
1361
+ id: record.id,
1362
+ status: record.status,
1363
+ reason: record.errorMessage
1364
+ }, "deploy: failed");
1365
+ return {
1366
+ deployment: record,
1367
+ status: "fail",
1368
+ message
1369
+ };
1370
+ }
1371
+ print(` ${style.success(`${record.status} — ${withScheme(triggered.url)}`)}`);
1268
1372
  logger.info({
1269
1373
  status: record.status,
1270
- url: record.url,
1374
+ url: triggered.url,
1271
1375
  id: record.id
1272
- }, "deploy: triggered");
1376
+ }, "deploy: ready");
1273
1377
  return {
1274
1378
  deployment: record,
1275
1379
  status: "ok"
1276
1380
  };
1277
1381
  } catch (err) {
1278
- const message = err instanceof Error ? err.message : String(err);
1382
+ const message = errorMessage(err);
1279
1383
  print(` ${style.fail(message)}`);
1280
1384
  logger.warn({
1281
1385
  branch: input.branch,
@@ -1288,8 +1392,124 @@ async function runDeploy(input) {
1288
1392
  };
1289
1393
  }
1290
1394
  }
1395
+ const SKIP_DIRS$2 = /* @__PURE__ */ new Set([
1396
+ ".git",
1397
+ "node_modules",
1398
+ ".turbo"
1399
+ ]);
1400
+ /** Recursively lists absolute file paths under `dir`, skipping VCS/tooling noise. */
1401
+ function defaultWalkFiles$2(dir) {
1402
+ const results = [];
1403
+ for (const entry of readdirSync(dir)) {
1404
+ if (SKIP_DIRS$2.has(entry)) continue;
1405
+ const full = join(dir, entry);
1406
+ const stat = statSync(full);
1407
+ if (stat.isDirectory()) results.push(...defaultWalkFiles$2(full));
1408
+ else if (stat.isFile()) results.push(full);
1409
+ }
1410
+ return results;
1411
+ }
1412
+ /** `holocron deploy --files <dir>` — the non-git counterpart to `runDeploy`. */
1413
+ async function runDeployFromFiles(input) {
1414
+ const print = input.print ?? ((line) => console.log(line));
1415
+ const logger = input.logger ?? getLogger();
1416
+ const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
1417
+ await loader.load();
1418
+ assertPluginsResolvable(loader, "deploy");
1419
+ const dryRun = input.context.dryRun ?? false;
1420
+ const walkFiles = input.walkFiles ?? defaultWalkFiles$2;
1421
+ const readFile = input.readFile ?? ((p) => readFileSync(p, "utf8"));
1422
+ const files = {};
1423
+ for (const abs of walkFiles(input.dir)) {
1424
+ const rel = relative(input.dir, abs).split(sep).join("/");
1425
+ files[rel] = readFile(abs);
1426
+ }
1427
+ const fileCount = Object.keys(files).length;
1428
+ logger.info({
1429
+ dir: input.dir,
1430
+ fileCount,
1431
+ target: input.target ?? "preview",
1432
+ projectId: input.projectId,
1433
+ dryRun: dryRun || void 0
1434
+ }, "deploy: start (files)");
1435
+ print(style.header(`Holocron deploy — files=${input.dir} (${fileCount} file${fileCount === 1 ? "" : "s"})${input.target ? `, target=${input.target}` : " (preview)"}${dryRun ? " (dry-run)" : ""}`));
1436
+ if (!loader.has("deployment")) throw new Error("deployment capability is not configured — add a `deployment` provider to holocron.config.json");
1437
+ const deploy = loader.get("deployment");
1438
+ if (!deploy.deployFunction) throw new Error(`deployment provider "${deploy.providerName}" does not support deploying from files — deployFunction() is not implemented`);
1439
+ if (dryRun) {
1440
+ const message = `would: ${deploy.providerName}.deployFunction(projectId=${input.projectId}, files=${fileCount}${input.target ? `, target=${input.target}` : ""})`;
1441
+ print(` ${style.dim(`… ${message}`)}`);
1442
+ return {
1443
+ deployment: null,
1444
+ status: "dry-run",
1445
+ message
1446
+ };
1447
+ }
1448
+ try {
1449
+ const result = await withSpinner(`Deploying ${fileCount} file${fileCount === 1 ? "" : "s"} from ${input.dir}…`, () => deploy.deployFunction(input.projectId, {
1450
+ files,
1451
+ ...input.target ? { target: input.target } : {}
1452
+ }));
1453
+ logger.info({
1454
+ url: result.url,
1455
+ id: result.deploymentId
1456
+ }, "deploy: triggered (files)");
1457
+ const record = await withSpinner(`Waiting for ${withScheme(result.url)} to finish…`, () => waitForDeployment(deploy, result.deploymentId, input.wait));
1458
+ if (record.status !== "ready") {
1459
+ const message = terminalFailure(record);
1460
+ print(` ${style.fail(`${message} — ${withScheme(result.url)}`)}`);
1461
+ logger.warn({
1462
+ id: record.id,
1463
+ status: record.status,
1464
+ reason: record.errorMessage
1465
+ }, "deploy: failed (files)");
1466
+ return {
1467
+ deployment: result,
1468
+ status: "fail",
1469
+ message
1470
+ };
1471
+ }
1472
+ print(` ${style.success(withScheme(result.url))}`);
1473
+ logger.info({
1474
+ url: result.url,
1475
+ id: result.deploymentId
1476
+ }, "deploy: ready (files)");
1477
+ return {
1478
+ deployment: result,
1479
+ status: "ok"
1480
+ };
1481
+ } catch (err) {
1482
+ const message = errorMessage(err);
1483
+ print(` ${style.fail(message)}`);
1484
+ logger.warn({
1485
+ dir: input.dir,
1486
+ reason: message
1487
+ }, "deploy: failed (files)");
1488
+ return {
1489
+ deployment: null,
1490
+ status: "fail",
1491
+ message
1492
+ };
1493
+ }
1494
+ }
1291
1495
  //#endregion
1292
1496
  //#region src/commands/doctor.ts
1497
+ /**
1498
+ * `holocron doctor` — load the config, instantiate every capability,
1499
+ * print a per-capability readiness report.
1500
+ *
1501
+ * Each capability gets a smoke check appropriate to its surface:
1502
+ * source → `whoami()`
1503
+ * issues → `doctor()` (rich report)
1504
+ * secrets → `listSecrets({ kind: 'repo' })`
1505
+ * ci → `listRuns({ limit: 1 })`
1506
+ * errors → `describe()`
1507
+ * logs → `whoami()` (dataset reachability) or `describe()`
1508
+ * others → just "loaded" (no smoke endpoint defined yet)
1509
+ *
1510
+ * Output is plain text via a passed-in `print` function so tests can
1511
+ * capture lines without ANSI / spinner noise.
1512
+ */
1293
1513
  async function runDoctor(input) {
1294
1514
  const print = input.print ?? ((line) => console.log(line));
1295
1515
  const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
@@ -1387,7 +1607,7 @@ async function smokeCheck(key, provider, impl) {
1387
1607
  default: return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
1388
1608
  }
1389
1609
  } catch (err) {
1390
- return mk(key, provider, "fail", err instanceof Error ? err.message : String(err));
1610
+ return mk(key, provider, "fail", errorMessage(err));
1391
1611
  }
1392
1612
  }
1393
1613
  function countResolvedLifecycle(report) {
@@ -1657,7 +1877,7 @@ async function runNew(input) {
1657
1877
  stdio: "inherit"
1658
1878
  });
1659
1879
  } catch (err) {
1660
- throw new NewError(`gh repo create failed: ${err instanceof Error ? err.message : String(err)}`);
1880
+ throw new NewError(`gh repo create failed: ${errorMessage(err)}`);
1661
1881
  }
1662
1882
  if (input.isTemplate) try {
1663
1883
  execFn("gh", [
@@ -1752,7 +1972,7 @@ async function runNew(input) {
1752
1972
  stdio: "inherit"
1753
1973
  });
1754
1974
  } catch (err) {
1755
- print(` ✗ pnpm install failed — ${err instanceof Error ? err.message : String(err)}`);
1975
+ print(` ✗ pnpm install failed — ${errorMessage(err)}`);
1756
1976
  return {
1757
1977
  status: "fail",
1758
1978
  repoDir,
@@ -1963,14 +2183,16 @@ describe("resolveToken", () => {
1963
2183
  });
1964
2184
 
1965
2185
  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
- }
2186
+ const err = (() => {
2187
+ try {
2188
+ resolveToken({ env: {}, keyring: noKeyring });
2189
+ } catch (e) {
2190
+ return e;
2191
+ }
2192
+ })();
2193
+ expect(err).toBeInstanceOf(AuthError);
2194
+ expect((err as Error).message).toMatch(/${inputs.tokenEnv}/);
2195
+ expect((err as Error).message).toMatch(/holocron auth set ${inputs.slug}/);
1974
2196
  });
1975
2197
  });
1976
2198
  `;
@@ -2014,24 +2236,24 @@ export class ${inputs.capabilityClass} {
2014
2236
  //#endregion
2015
2237
  //#region src/commands/plugin-create/templates/capability-test.ts
2016
2238
  function render$14(inputs) {
2017
- const clientClass = `${inputs.vendorName}RestClient`;
2018
- return `import { describe, it } from "vitest";
2239
+ const factoryName = `create${inputs.vendorName}RestClient`;
2240
+ return `import { describe, expect, it } from "vitest";
2019
2241
 
2020
2242
  import { ${inputs.capabilityClass} } from "../capabilities/${inputs.capability}.js";
2021
- import { ${clientClass} } from "../rest.js";
2243
+ import { ${factoryName} } from "../rest.js";
2022
2244
  import { stubFetch } from "./helpers.js";
2023
2245
 
2024
2246
  // Stub client used by the constructor smoke test. Real capability
2025
2247
  // tests replace this with per-method stubs once implementations land.
2026
2248
  function makeCapability() {
2027
2249
  const stub = stubFetch([]);
2028
- const rest = new ${clientClass}({ token: "t", fetch: stub.fetch });
2250
+ const rest = ${factoryName}({ token: "t", fetch: stub.fetch });
2029
2251
  return new ${inputs.capabilityClass}(() => rest);
2030
2252
  }
2031
2253
 
2032
2254
  describe("${inputs.capabilityClass}", () => {
2033
2255
  it("constructs with a REST client", () => {
2034
- makeCapability();
2256
+ expect(makeCapability().key).toBe("${inputs.capability}");
2035
2257
  });
2036
2258
 
2037
2259
  // TODO: implement one test per ${inputs.capability} capability method
@@ -2047,14 +2269,11 @@ describe("${inputs.capabilityClass}", () => {
2047
2269
  //#endregion
2048
2270
  //#region src/commands/plugin-create/templates/eslint-config.ts
2049
2271
  function render$13(_inputs) {
2050
- return `import root from "../../eslint.config.js";
2272
+ return `import type { Linter } from "eslint";
2051
2273
 
2052
- export default [
2053
- ...root,
2054
- {
2055
- ignores: ["dist/**", "coverage/**"],
2056
- },
2057
- ];
2274
+ import root from "../../eslint.config.js";
2275
+
2276
+ export default [...root, { ignores: ["dist/**", "coverage/**"] }] satisfies Linter.Config[];
2058
2277
  `;
2059
2278
  }
2060
2279
  //#endregion
@@ -2137,10 +2356,17 @@ describe("AUTH_HINT", () => {
2137
2356
  //#endregion
2138
2357
  //#region src/commands/plugin-create/templates/package-json.ts
2139
2358
  function render$10(inputs) {
2359
+ const keywords = [
2360
+ inputs.capability,
2361
+ "holocron",
2362
+ "plugin",
2363
+ inputs.slug
2364
+ ].sort((a, b) => a.localeCompare(b));
2140
2365
  return JSON.stringify({
2141
2366
  name: `@theholocron/holocron-plugin-${inputs.slug}`,
2142
2367
  version: "2.0.0-alpha.1",
2143
2368
  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\`.`,
2369
+ keywords,
2144
2370
  homepage: `https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-${inputs.slug}#readme`,
2145
2371
  bugs: "https://github.com/theholocron/holocron/issues",
2146
2372
  repository: {
@@ -2150,9 +2376,13 @@ function render$10(inputs) {
2150
2376
  },
2151
2377
  license: "MIT",
2152
2378
  author: "Newton Koumantzelis",
2379
+ sideEffects: false,
2153
2380
  type: "module",
2154
- main: "./src/index.ts",
2155
- exports: { ".": "./src/index.ts" },
2381
+ exports: { ".": {
2382
+ types: "./dist/index.d.mts",
2383
+ import: "./dist/index.mjs",
2384
+ default: "./dist/index.mjs"
2385
+ } },
2156
2386
  scripts: {
2157
2387
  "delivery.build": "tsdown",
2158
2388
  "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
@@ -2161,36 +2391,33 @@ function render$10(inputs) {
2161
2391
  "test:watch": "vitest",
2162
2392
  validate: "tsx scripts/validate.mjs"
2163
2393
  },
2164
- peerDependencies: { "@theholocron/cli": "workspace:*" },
2394
+ peerDependencies: {
2395
+ "@theholocron/cli": "workspace:*",
2396
+ "@theholocron/misc-utils": "catalog:utils"
2397
+ },
2165
2398
  devDependencies: {
2166
2399
  "@theholocron/cli": "workspace:*",
2167
- "@theholocron/tsconfig": "catalog:",
2168
- "@tsconfig/node-lts": "catalog:",
2400
+ "@theholocron/misc-utils": "catalog:utils",
2401
+ "@theholocron/tsconfig": "catalog:configs",
2402
+ "@types/node": "catalog:",
2169
2403
  "@vitest/coverage-v8": "catalog:",
2170
2404
  eslint: "catalog:",
2171
2405
  globals: "catalog:",
2172
- typescript: "catalog:",
2173
- vitest: "catalog:",
2174
2406
  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
- } }
2407
+ tsx: "catalog:",
2408
+ typescript: "catalog:",
2409
+ vitest: "catalog:"
2186
2410
  },
2187
- files: ["dist", "README.md"]
2188
- }, null, " ") + "\n";
2411
+ engines: { node: ">=22" },
2412
+ publishConfig: { access: "public" },
2413
+ files: ["dist"]
2414
+ }, null, 2) + "\n";
2189
2415
  }
2190
2416
  //#endregion
2191
2417
  //#region src/commands/plugin-create/templates/plugin-index.ts
2192
2418
  function render$9(inputs) {
2193
2419
  const clientClass = `${inputs.vendorName}RestClient`;
2420
+ const factoryName = `create${inputs.vendorName}RestClient`;
2194
2421
  const capabilityInterface = inputs.capability.charAt(0).toUpperCase() + inputs.capability.slice(1);
2195
2422
  return `/**
2196
2423
  * \`@theholocron/holocron-plugin-${inputs.slug}\` — entrypoint.
@@ -2207,7 +2434,7 @@ function render$9(inputs) {
2207
2434
 
2208
2435
  import { resolveToken, type ResolveTokenInput } from "./auth.js";
2209
2436
  import { ${inputs.capabilityClass} } from "./capabilities/${inputs.capability}.js";
2210
- import { ${clientClass} } from "./rest.js";
2437
+ import { ${factoryName}, type ${clientClass} } from "./rest.js";
2211
2438
 
2212
2439
  export interface ${inputs.vendorName}PluginOptions extends ResolveTokenInput {
2213
2440
  /** Override base URL for tests. */
@@ -2228,10 +2455,12 @@ export function createContext(options: ${inputs.vendorName}PluginOptions): Plugi
2228
2455
  options,
2229
2456
  rest: () => {
2230
2457
  if (rest) return rest;
2231
- const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token: resolveToken(options) };
2458
+ const restOpts: { token: string; baseUrl?: string; fetch?: typeof fetch } = {
2459
+ token: resolveToken(options),
2460
+ };
2232
2461
  if (options.baseUrl !== undefined) restOpts.baseUrl = options.baseUrl;
2233
2462
  if (options.fetch !== undefined) restOpts.fetch = options.fetch;
2234
- return (rest = new ${clientClass}(restOpts));
2463
+ return (rest = ${factoryName}(restOpts));
2235
2464
  },
2236
2465
  };
2237
2466
  }
@@ -2265,7 +2494,7 @@ export const AUTH_HINT =
2265
2494
  // ── Public re-exports ────────────────────────────────────────────────
2266
2495
 
2267
2496
  export * from "./auth.js";
2268
- export { ${clientClass} } from "./rest.js";
2497
+ export { type ${clientClass}, ${factoryName} } from "./rest.js";
2269
2498
  export { ${inputs.capabilityClass} } from "./capabilities/${inputs.capability}.js";
2270
2499
  export { verifyToken } from "./verify-token.js";
2271
2500
  export type { VerifyTokenResult, VerifyTokenSuccess, VerifyTokenFailure } from "./verify-token.js";
@@ -2342,15 +2571,26 @@ Not yet published; capability methods are stubs.
2342
2571
  //#endregion
2343
2572
  //#region src/commands/plugin-create/templates/rest.ts
2344
2573
  function render$7(inputs) {
2345
- return `import { createRestClient, type RequestOptions, type RestClient } from "@theholocron/cli";
2574
+ const factoryName = `create${inputs.vendorName}RestClient`;
2575
+ const clientType = `${inputs.vendorName}RestClient`;
2576
+ return `import { createRestClient, type RestClient } from "@theholocron/cli";
2346
2577
 
2347
- export type { RequestOptions, RestClient };
2578
+ export type { RestClient };
2348
2579
 
2349
- export function ${`create${inputs.vendorName}RestClient`}(opts: {
2580
+ /**
2581
+ * TODO: narrow this to the specific ${inputs.vendorName} endpoints this
2582
+ * plugin's capability needs (see \`@theholocron/holocron-plugin-axiom\`'s
2583
+ * \`rest.ts\` for the pattern: an interface with one method per endpoint,
2584
+ * built internally via \`createRestClient\`). Starts as an alias for the
2585
+ * generic client so the scaffold compiles end to end immediately.
2586
+ */
2587
+ export type ${clientType} = RestClient;
2588
+
2589
+ export function ${factoryName}(opts: {
2350
2590
  \ttoken: string;
2351
2591
  \tbaseUrl?: string;
2352
2592
  \tfetch?: typeof fetch;
2353
- }): RestClient {
2593
+ }): ${clientType} {
2354
2594
  \treturn createRestClient({
2355
2595
  \t\tbaseUrl: opts.baseUrl ?? "${inputs.baseUrl}",
2356
2596
  \t\ttoken: opts.token,
@@ -2423,7 +2663,7 @@ describe("${factoryName}", () => {
2423
2663
  function render$5(inputs) {
2424
2664
  return JSON.stringify({
2425
2665
  display: `Holocron Plugin: ${inputs.vendorName}`,
2426
- extends: "@tsconfig/node-lts/tsconfig.json",
2666
+ extends: "@theholocron/tsconfig/node-lts",
2427
2667
  compilerOptions: {
2428
2668
  baseUrl: "./",
2429
2669
  outDir: "./dist",
@@ -2431,7 +2671,7 @@ function render$5(inputs) {
2431
2671
  },
2432
2672
  include: ["src/**/*.ts"],
2433
2673
  exclude: ["node_modules", "dist"]
2434
- }, null, " ") + "\n";
2674
+ }, null, 2) + "\n";
2435
2675
  }
2436
2676
  //#endregion
2437
2677
  //#region src/commands/plugin-create/templates/tsdown-config.ts
@@ -2492,6 +2732,7 @@ function render$3(inputs) {
2492
2732
 
2493
2733
  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- filled in by operator
2494
2734
  import { AuthError, createPlugin, resolveToken, verifyToken } from "../src/index.ts";
2735
+ import { errorMessage } from "@theholocron/misc-utils";
2495
2736
 
2496
2737
  const args = process.argv.slice(2);
2497
2738
 
@@ -2547,11 +2788,12 @@ console.log("Done. Fill in capability method calls above before shipping.");
2547
2788
  // ── helpers ────────────────────────────────────────────────────────
2548
2789
 
2549
2790
  /** Wrap a capability call, print ERROR + hint on failure. */
2791
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars -- called once a real capability check replaces the TODO example above
2550
2792
  async function runStep(body) {
2551
2793
  try {
2552
2794
  await body();
2553
2795
  } catch (err) {
2554
- const message = err instanceof Error ? err.message : String(err);
2796
+ const message = errorMessage(err);
2555
2797
  console.log(\` ✗ ERROR: \${message}\`);
2556
2798
  const hint = hintFor(message);
2557
2799
  if (hint) console.log(\` hint: \${hint}\`);
@@ -2586,7 +2828,7 @@ function hintFor(message) {
2586
2828
  //#endregion
2587
2829
  //#region src/commands/plugin-create/templates/verify-token.ts
2588
2830
  function render$2(inputs) {
2589
- const clientClass = `${inputs.vendorName}RestClient`;
2831
+ const factoryName = `create${inputs.vendorName}RestClient`;
2590
2832
  return `/**
2591
2833
  * \`verifyToken\` — plugin-level export used by \`holocron auth set\` +
2592
2834
  * \`holocron auth check\`. Hits a lightweight whoami-style endpoint
@@ -2603,19 +2845,10 @@ function render$2(inputs) {
2603
2845
  * \`/me\`, \`/account\`.
2604
2846
  */
2605
2847
 
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
- }
2848
+ import type { VerifyTokenResult } from "@theholocron/cli";
2849
+ import { errorMessage } from "@theholocron/misc-utils";
2617
2850
 
2618
- export type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
2851
+ import { ${factoryName} } from "./rest.js";
2619
2852
 
2620
2853
  interface MeResponse {
2621
2854
  /** Adjust to whatever ${inputs.vendorName}'s whoami endpoint returns. */
@@ -2630,18 +2863,17 @@ export interface VerifyTokenOptions {
2630
2863
  }
2631
2864
 
2632
2865
  export async function verifyToken(token: string, opts: VerifyTokenOptions = {}): Promise<VerifyTokenResult> {
2633
- const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token };
2866
+ const restOpts: { token: string; baseUrl?: string; fetch?: typeof fetch } = { token };
2634
2867
  if (opts.baseUrl !== undefined) restOpts.baseUrl = opts.baseUrl;
2635
2868
  if (opts.fetch !== undefined) restOpts.fetch = opts.fetch;
2636
- const rest = new ${clientClass}(restOpts);
2869
+ const rest = ${factoryName}(restOpts);
2637
2870
  try {
2638
2871
  const me = await rest.request<MeResponse>("/me");
2639
2872
  // Optional chaining because \`me\` is \`undefined\` on 204 / empty body.
2640
2873
  const subject = me?.email ?? me?.name ?? me?.id ?? "unknown";
2641
2874
  return { ok: true, subject: \`user @ \${subject}\` };
2642
2875
  } catch (err) {
2643
- const message = err instanceof Error ? err.message : String(err);
2644
- return { ok: false, message };
2876
+ return { ok: false, message: errorMessage(err) };
2645
2877
  }
2646
2878
  }
2647
2879
  `;
@@ -2659,18 +2891,14 @@ describe("verifyToken", () => {
2659
2891
  const stub = stubFetch([{ status: 200, body: { email: "user@example.com" } }]);
2660
2892
  const result = await verifyToken("token", { fetch: stub.fetch });
2661
2893
  expect(result.ok).toBe(true);
2662
- if (result.ok) {
2663
- expect(result.subject).toMatch(/user@example.com/);
2664
- }
2894
+ expect((result as { ok: boolean; subject?: string }).subject).toMatch(/user@example.com/);
2665
2895
  });
2666
2896
 
2667
2897
  it("returns ok:false with the error message on 401", async () => {
2668
2898
  const stub = stubFetch([{ status: 401, body: { messages: ["Invalid token"] } }]);
2669
2899
  const result = await verifyToken("bad", { fetch: stub.fetch });
2670
2900
  expect(result.ok).toBe(false);
2671
- if (!result.ok) {
2672
- expect(result.message).toMatch(/→ 401/);
2673
- }
2901
+ expect((result as { ok: boolean; message?: string }).message).toMatch(/→ 401/);
2674
2902
  });
2675
2903
 
2676
2904
  it("returns ok:false when the network layer throws", async () => {
@@ -2679,9 +2907,7 @@ describe("verifyToken", () => {
2679
2907
  };
2680
2908
  const result = await verifyToken("t", { fetch: throwing });
2681
2909
  expect(result.ok).toBe(false);
2682
- if (!result.ok) {
2683
- expect(result.message).toMatch(/network down/);
2684
- }
2910
+ expect((result as { ok: boolean; message?: string }).message).toMatch(/network down/);
2685
2911
  });
2686
2912
  });
2687
2913
  `;
@@ -2755,7 +2981,7 @@ const TEMPLATES = [
2755
2981
  render
2756
2982
  },
2757
2983
  {
2758
- path: "eslint.config.js",
2984
+ path: "eslint.config.ts",
2759
2985
  render: render$13
2760
2986
  },
2761
2987
  {
@@ -2901,7 +3127,7 @@ function runPluginCreate(input) {
2901
3127
  });
2902
3128
  print(" ✓ scaffold verified");
2903
3129
  } catch (err) {
2904
- const message = err instanceof Error ? err.message : String(err);
3130
+ const message = errorMessage(err);
2905
3131
  print(` ✗ verify failed — ${message}`);
2906
3132
  logger.warn({
2907
3133
  slug: inputs.slug,
@@ -3598,6 +3824,24 @@ const defaultLogin = async (cwd) => {
3598
3824
  };
3599
3825
  //#endregion
3600
3826
  //#region src/commands/secret-set.ts
3827
+ /**
3828
+ * `holocron secret set` — one-shot single-secret push.
3829
+ *
3830
+ * Complements `holocron secrets sync` (bulk vault → destinations) for
3831
+ * ad-hoc scenarios:
3832
+ * - Bootstrap secrets (e.g., NPM_TOKEN on theholocron/holocron itself
3833
+ * before the rest of the setup exists)
3834
+ * - One-off rotations that don't warrant a vault sync
3835
+ * - Setting secrets the vault doesn't track
3836
+ *
3837
+ * Value source resolution (in priority order):
3838
+ * 1. Positional `value` argument
3839
+ * 2. `--from-stdin` reads from stdin
3840
+ * 3. `--from-env <NAME>` reads from the named env var
3841
+ * 4. Implicit: env var matching the secret name (e.g., `NPM_TOKEN`)
3842
+ *
3843
+ * Errors clearly when no value can be sourced.
3844
+ */
3601
3845
  async function runSecretSet(input) {
3602
3846
  const print = input.print ?? ((line) => console.log(line));
3603
3847
  const logger = input.logger ?? getLogger();
@@ -3636,7 +3880,7 @@ async function runSecretSet(input) {
3636
3880
  scope
3637
3881
  };
3638
3882
  } catch (err) {
3639
- const message = err instanceof Error ? err.message : String(err);
3883
+ const message = errorMessage(err);
3640
3884
  print(` ✗ ${message}`);
3641
3885
  logger.warn({
3642
3886
  key: input.name,
@@ -3672,6 +3916,38 @@ function describeScope(scope) {
3672
3916
  }
3673
3917
  //#endregion
3674
3918
  //#region src/commands/secrets-sync.ts
3919
+ /**
3920
+ * `holocron secrets sync` — vault → destinations.
3921
+ *
3922
+ * Reads a named environment from the configured `vault` (1P
3923
+ * Environment / similar) as KEY=VALUE pairs, then fans those values
3924
+ * out to the configured destinations:
3925
+ *
3926
+ * - `secrets` capability (e.g., GH Actions secrets) — repo-scope
3927
+ * - `deployment` capability (e.g., Vercel env vars) — per-target
3928
+ * - local `.env` file (optional, planned for v5.1 — currently skipped
3929
+ * with a soft "not yet" note)
3930
+ *
3931
+ * Per-secret routing rules:
3932
+ *
3933
+ * - All keys go to `deployment` for each target the caller asks for
3934
+ * (defaults: production + preview)
3935
+ * - `secrets` (GH Actions) defaults to every key, repo-scoped — but a
3936
+ * caller can pass `githubSecretKeys` (an allowlist, from repeatable
3937
+ * `--github-secret KEY` CLI values) to restrict `secrets` to only
3938
+ * those keys, and `githubSecretScope` (same `{ kind }` shape `secret
3939
+ * set`'s own `--scope repo|env=NAME|org=NAME` parses to) to apply one
3940
+ * scope to all of them. A key not in the allowlist is skipped for
3941
+ * `secrets` entirely — still synced to `deployment` if configured.
3942
+ * Needed for a vault holding a mix of deploy-only secrets and one
3943
+ * CI-consumed, org-wide secret (holocron#781's Sentinel case: 4
3944
+ * Vercel-only keys + one org-scoped Axiom ingest token
3945
+ * `theholocron/.github`'s dispatched-check workflow also reads).
3946
+ *
3947
+ * The vault MUST implement `readEnvironment(envId)` (optional method).
3948
+ * If it doesn't, the command errors with a hint to populate the keys
3949
+ * individually via `holocron secret set` (also planned for v5.1).
3950
+ */
3675
3951
  async function runSecretsSync(input) {
3676
3952
  const print = input.print ?? ((line) => console.log(line));
3677
3953
  const logger = input.logger ?? getLogger();
@@ -3696,10 +3972,13 @@ async function runSecretsSync(input) {
3696
3972
  const rows = [];
3697
3973
  if (loader.has("secrets")) {
3698
3974
  const secrets = loader.get("secrets");
3699
- print(style.step("secrets (repo scope)"));
3975
+ const scope = input.githubSecretScope ?? { kind: "repo" };
3976
+ const allowedKeys = input.githubSecretKeys ? new Set(input.githubSecretKeys) : void 0;
3977
+ print(style.step("secrets"));
3700
3978
  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]);
3979
+ if (allowedKeys && !allowedKeys.has(key)) continue;
3980
+ rows.push(await runRow(`secrets:${secrets.providerName}`, scopeLabel(scope), key, dryRun, async () => {
3981
+ await secrets.setSecret(scope, key, envVars[key]);
3703
3982
  }));
3704
3983
  print(formatRow(rows[rows.length - 1]));
3705
3984
  }
@@ -3779,7 +4058,7 @@ async function runRow(destination, scope, key, dryRun, body) {
3779
4058
  scope,
3780
4059
  key,
3781
4060
  status: "fail",
3782
- message: err instanceof Error ? err.message : String(err)
4061
+ message: errorMessage(err)
3783
4062
  };
3784
4063
  }
3785
4064
  }
@@ -3791,6 +4070,11 @@ function formatRow(row) {
3791
4070
  if (row.status === "dry-run") return ` ${style.dim(`… ${label}`)}`;
3792
4071
  return ` ${style.dim(`· ${label}`)}`;
3793
4072
  }
4073
+ function scopeLabel(scope) {
4074
+ if (scope.kind === "repo") return "scope=repo";
4075
+ if (scope.kind === "organization") return `scope=organization,org=${scope.name}`;
4076
+ return `scope=environment,env=${scope.name}`;
4077
+ }
3794
4078
  function vaultProviderName(loader) {
3795
4079
  if (!loader.has("vault")) return "<missing>";
3796
4080
  return loader.get("vault").providerName;
@@ -3804,16 +4088,26 @@ function vaultProviderName(loader) {
3804
4088
  * package has `bin`) → `platform` — matches `holocron` itself: the CLI is
3805
4089
  * the deliverable, the plugin packages are supporting infrastructure for
3806
4090
  * 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
4091
+ * 3. Monorepo with no CLI but at least one non-private workspace package →
4092
+ * `library` — matches `clients`/`configs`/`utils`/`themes`/
4093
+ * `observability`: a family of published packages, none of them a CLI.
4094
+ * Checked *before* falling into the root-package branch below, because
4095
+ * these repos' own root `package.json` is private and often carries
4096
+ * `@theholocron/astro-config` for a docs site built from the monorepo
4097
+ * root — without this check they'd wrongly resolve to `docs` off that
4098
+ * root-level signal alone, when the docs site is a secondary concern of
4099
+ * a library collection, not what the repo fundamentally is.
4100
+ * 4. Single-package repo with `package.json#bin` → `cli`.
4101
+ * 5. Docs-only site (astro/starlight present, root package private, no
3809
4102
  * publishable exports) → `docs`.
3810
- * 5. Private, non-publishable, non-docs → `app`.
3811
- * 6. Otherwise, a single publishable package → `library`.
4103
+ * 6. Private, non-publishable, non-docs → `app`.
4104
+ * 7. Otherwise, a single publishable package → `library`.
3812
4105
  */
3813
4106
  function deriveProfile(input) {
3814
4107
  if (/-template$/.test(input.repoName)) return "template";
3815
4108
  if (input.isMonorepo) {
3816
4109
  if (input.workspacePackageJsons.some((pkg) => Boolean(pkg.bin))) return "platform";
4110
+ if (input.workspacePackageJsons.some((pkg) => pkg.private !== true)) return "library";
3817
4111
  }
3818
4112
  const pkg = input.rootPackageJson;
3819
4113
  if (pkg?.bin) return "cli";
@@ -4023,6 +4317,9 @@ var alexignore_default = ".github/*\nCHANGELOG.md\nLICENSE\n";
4023
4317
  //#region src/templates/configs/alexjs/alexrc.json
4024
4318
  var alexrc_default = { allow: [
4025
4319
  "dead",
4320
+ "execute",
4321
+ "execution",
4322
+ "executes",
4026
4323
  "failure",
4027
4324
  "failures",
4028
4325
  "hook",
@@ -4041,12 +4338,21 @@ function createIgnoreConfig$1() {
4041
4338
  }
4042
4339
  //#endregion
4043
4340
  //#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";
4341
+ var commit_msg_default = "__HOLOCRON_SCRIPT__ lint commit-msg \"$1\"\n";
4045
4342
  //#endregion
4046
4343
  //#region src/templates/configs/commit-msg/create-config.ts
4047
4344
  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}`;
4345
+ /**
4346
+ * `.husky/commit-msg` — lints the commit message via `holocron lint
4347
+ * commit-msg` (holocron#789), the real programmatic replacement for
4348
+ * shelling out to `commitlint --edit`. Installed by `holocron setup` when
4349
+ * hooks are enabled. Same `__HOLOCRON_SCRIPT__` substitution as `pre-push`.
4350
+ *
4351
+ * @param holocronScript - the command that invokes the CLI. Defaults to
4352
+ * `pnpm exec holocron`; the source repo passes `node packages/cli/dist/cli.mjs`.
4353
+ */
4354
+ function createConfig$7(holocronScript = "pnpm exec holocron") {
4355
+ return `${workflowHeader$8("shebang")}${commit_msg_default.replace("__HOLOCRON_SCRIPT__", holocronScript)}`;
4050
4356
  }
4051
4357
  //#endregion
4052
4358
  //#region src/templates/configs/devmoji/create-config.ts
@@ -4062,7 +4368,7 @@ function createConfig$6() {
4062
4368
  }
4063
4369
  //#endregion
4064
4370
  //#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";
4371
+ 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
4372
  //#endregion
4067
4373
  //#region src/templates/configs/editorconfig/create-config.ts
4068
4374
  const { workflowHeader: workflowHeader$6 } = createHeader({ source: "packages/cli/src/templates/configs/editorconfig/create-config.ts" });
@@ -4685,7 +4991,7 @@ async function upsertBranchProtection(source, dryRun, requiredChecks) {
4685
4991
  capability: "source",
4686
4992
  step,
4687
4993
  status: "fail",
4688
- message: err instanceof Error ? err.message : String(err)
4994
+ message: errorMessage(err)
4689
4995
  };
4690
4996
  }
4691
4997
  try {
@@ -4708,7 +5014,7 @@ async function upsertBranchProtection(source, dryRun, requiredChecks) {
4708
5014
  capability: "source",
4709
5015
  step,
4710
5016
  status: "fail",
4711
- message: err instanceof Error ? err.message : String(err)
5017
+ message: errorMessage(err)
4712
5018
  };
4713
5019
  }
4714
5020
  }
@@ -4801,7 +5107,7 @@ async function execStep(capability, step, dryRun, body, opts = {}) {
4801
5107
  capability,
4802
5108
  step,
4803
5109
  status: "fail",
4804
- message: err instanceof Error ? err.message : String(err)
5110
+ message: errorMessage(err)
4805
5111
  };
4806
5112
  }
4807
5113
  }
@@ -5042,7 +5348,10 @@ async function runSetup(input) {
5042
5348
  print(formatStep(steps[steps.length - 1]));
5043
5349
  if (effectivePreset && effectivePreset !== "none") {
5044
5350
  steps.push(await runStep("source", "updateRepoSettings", dryRun, async () => {
5045
- await source.updateRepoSettings(BALANCED_REPO_SETTINGS);
5351
+ await source.updateRepoSettings({
5352
+ ...BALANCED_REPO_SETTINGS,
5353
+ ...repo?.defaultBranch ? { default_branch: repo.defaultBranch } : {}
5354
+ });
5046
5355
  }));
5047
5356
  print(formatStep(steps[steps.length - 1]));
5048
5357
  const tasksConfig = { tasks: config.tasks };
@@ -5149,7 +5458,7 @@ async function runSetup(input) {
5149
5458
  }));
5150
5459
  print(formatStep(steps[steps.length - 1]));
5151
5460
  steps.push(await runStep("source", "write .husky/commit-msg", dryRun, async () => {
5152
- await source.writeRepoFile(".husky/commit-msg", createConfig$7());
5461
+ await source.writeRepoFile(".husky/commit-msg", createConfig$7(config.holocronScript));
5153
5462
  }));
5154
5463
  print(formatStep(steps[steps.length - 1]));
5155
5464
  if (hooksEnabled) {
@@ -5223,13 +5532,20 @@ async function runSetup(input) {
5223
5532
  await source.writeRepoFile("turbo.json", content);
5224
5533
  }));
5225
5534
  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);
5535
+ const rootPkgRaw = await readFile(join(input.context.repoRoot, "package.json"), "utf8").catch(() => null);
5536
+ const rootPkg = rootPkgRaw ? JSON.parse(rootPkgRaw) : null;
5227
5537
  const workspaceYaml = await readFile(join(input.context.repoRoot, "pnpm-workspace.yaml"), "utf8").catch(() => "");
5228
- const rootScripts = Object.keys(rootPkg?.scripts ?? {});
5538
+ const rootScripts = rootPkg?.scripts ?? {};
5229
5539
  const workspaceFix = astromechTurbo.ensureRootWorkspaceMember(workspaceYaml, rootScripts);
5230
5540
  if (workspaceFix.changed) steps.push(await runStep("source", "fix pnpm-workspace.yaml (root workspace member, #692)", dryRun, async () => {
5231
5541
  await source.writeRepoFile("pnpm-workspace.yaml", workspaceFix.content);
5232
5542
  }));
5543
+ if (rootPkgRaw) {
5544
+ const depFix = astromechTurbo.ensureTurboDependency(rootPkgRaw, workspaceFix.content);
5545
+ if (depFix.changed) steps.push(await runStep("source", "add turbo devDependency", dryRun, async () => {
5546
+ await source.writeRepoFile("package.json", depFix.content);
5547
+ }));
5548
+ }
5233
5549
  }
5234
5550
  print(formatStep(steps[steps.length - 1]));
5235
5551
  }
@@ -5240,7 +5556,7 @@ async function runSetup(input) {
5240
5556
  print(formatStep(steps[steps.length - 1]));
5241
5557
  }
5242
5558
  const properties = {};
5243
- if (effectivePreset && effectivePreset !== "none") properties["branch_protection_level"] = effectivePreset;
5559
+ if (effectivePreset && effectivePreset !== "none") properties["holocron_branch_protection_level"] = effectivePreset;
5244
5560
  const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
5245
5561
  properties["monorepo"] = String(isMonorepo);
5246
5562
  const manual = repo?.properties ?? {};
@@ -5258,9 +5574,9 @@ async function runSetup(input) {
5258
5574
  isMonorepo,
5259
5575
  workspacePackageJsons
5260
5576
  });
5261
- properties["holocron_stack"] = deriveStack(rootPackageJson).join(", ");
5577
+ properties["holocron_stack"] = deriveStack(rootPackageJson);
5262
5578
  const capabilities = deriveCapabilities(config.providers);
5263
- properties["holocron_capabilities"] = capabilities.join(", ");
5579
+ properties["holocron_capabilities"] = capabilities;
5264
5580
  properties["holocron_compliance"] = deriveCompliance(capabilities);
5265
5581
  }
5266
5582
  if (source.syncProperties) {
@@ -5281,34 +5597,36 @@ async function runSetup(input) {
5281
5597
  print(formatStep(steps[steps.length - 1]));
5282
5598
  }
5283
5599
  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
- }));
5600
+ if (teams.length > 0) {
5601
+ if (source.syncTeams) {
5602
+ steps.push(await runStep("source", "sync teams", dryRun, () => source.syncTeams(teams), { skipCodes: [422] }));
5603
+ print(formatStep(steps[steps.length - 1]));
5604
+ const repoCoord = input.context.repo ?? repo?.name ?? "";
5605
+ const org = repoCoord.includes("/") ? repoCoord.split("/")[0] : "";
5606
+ const writeableTeams = teams.map((t) => typeof t === "string" ? {
5607
+ slug: t,
5608
+ permission: "push"
5609
+ } : t).filter((t) => [
5610
+ "push",
5611
+ "maintain",
5612
+ "admin"
5613
+ ].includes(t.permission));
5614
+ if (org && writeableTeams.length > 0) {
5615
+ steps.push(await runStep("source", "write .github/CODEOWNERS", dryRun, async () => {
5616
+ const content = writeableTeams.map((t) => `* @${org}/${t.slug}`).join("\n") + "\n";
5617
+ await source.writeRepoFile(".github/CODEOWNERS", content);
5618
+ }));
5619
+ print(formatStep(steps[steps.length - 1]));
5620
+ }
5621
+ } else {
5622
+ steps.push({
5623
+ capability: "source",
5624
+ step: "sync teams",
5625
+ status: "skip",
5626
+ message: "provider does not implement syncTeams"
5627
+ });
5302
5628
  print(formatStep(steps[steps.length - 1]));
5303
5629
  }
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
5630
  }
5313
5631
  }
5314
5632
  if (loader.has("environments")) {
@@ -5364,11 +5682,9 @@ async function runSetup(input) {
5364
5682
  const wikiProxy = wiki.proxyConfig?.();
5365
5683
  if (wikiDns && loader.has("dns")) {
5366
5684
  const dns = loader.get("dns");
5367
- steps.push(await runStep("dns", `upsertRecord ${wikiDns.cname}`, dryRun, async () => {
5685
+ steps.push(await runStep("dns", `upsertRecord ${wikiDns.record.name}`, dryRun, async () => {
5368
5686
  await dns.upsertRecord(wikiDns.zone, {
5369
- type: "CNAME",
5370
- name: wikiDns.cname,
5371
- content: wikiDns.target,
5687
+ ...wikiDns.record,
5372
5688
  ttl: 1,
5373
5689
  ...wikiProxy ? { proxied: true } : {}
5374
5690
  });
@@ -5377,8 +5693,8 @@ async function runSetup(input) {
5377
5693
  }
5378
5694
  if (wikiProxy && wikiDns && loader.has("workers")) {
5379
5695
  const workers = loader.get("workers");
5380
- steps.push(await runStep("workers", `upsertProxy ${wikiDns.cname}`, dryRun, async () => {
5381
- await workers.upsertProxy(wikiDns.cname, wikiProxy);
5696
+ steps.push(await runStep("workers", `upsertProxy ${wikiDns.record.name}`, dryRun, async () => {
5697
+ await workers.upsertProxy(wikiDns.record.name, wikiProxy);
5382
5698
  }));
5383
5699
  print(formatStep(steps[steps.length - 1]));
5384
5700
  }
@@ -5391,11 +5707,31 @@ async function runSetup(input) {
5391
5707
  org: config.org,
5392
5708
  domain: config.domain
5393
5709
  }) : null;
5710
+ const ensureCustomDomain = async (projectId, hostname) => {
5711
+ if (!deploy.ensureCustomDomain) return;
5712
+ const customDomainDns = { value: null };
5713
+ steps.push(await runStep("deployment", `ensureCustomDomain ${hostname}`, dryRun, async () => {
5714
+ customDomainDns.value = await deploy.ensureCustomDomain(projectId, hostname);
5715
+ }));
5716
+ print(formatStep(steps[steps.length - 1]));
5717
+ if (customDomainDns.value && loader.has("dns")) {
5718
+ const dns = loader.get("dns");
5719
+ const dnsRecord = customDomainDns.value;
5720
+ steps.push(await runStep("dns", `upsertRecord ${dnsRecord.record.name}`, dryRun, async () => {
5721
+ await dns.upsertRecord(dnsRecord.zone, {
5722
+ ...dnsRecord.record,
5723
+ ttl: 1
5724
+ });
5725
+ }));
5726
+ print(formatStep(steps[steps.length - 1]));
5727
+ }
5728
+ };
5394
5729
  if (!previewCfg) {
5395
5730
  steps.push(await runStep("deployment", `ensureProject ${config.name}`, dryRun, async () => {
5396
5731
  await deploy.ensureProject({ name: config.name });
5397
5732
  }));
5398
5733
  print(formatStep(steps[steps.length - 1]));
5734
+ if (deploy.domain) await ensureCustomDomain(config.name, deploy.domain);
5399
5735
  }
5400
5736
  if (previewCfg) {
5401
5737
  steps.push(await runStep("deployment", `ensureProject ${previewCfg.project}`, dryRun, async () => {
@@ -5403,13 +5739,8 @@ async function runSetup(input) {
5403
5739
  }));
5404
5740
  print(formatStep(steps[steps.length - 1]));
5405
5741
  }
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")) {
5742
+ if (previewCfg?.domain) await ensureCustomDomain(previewCfg.project, previewCfg.domain);
5743
+ if (previewCfg?.domain && deploy.providerName === "cloudflare" && loader.has("dns")) {
5413
5744
  const dns = loader.get("dns");
5414
5745
  const wildcardDomain = `*.${previewCfg.domain}`;
5415
5746
  steps.push(await runStep("dns", `upsertRecord ${previewCfg.domain}`, dryRun, async () => {
@@ -5483,7 +5814,7 @@ async function runSetup(input) {
5483
5814
  capability: "vault",
5484
5815
  step: "list",
5485
5816
  status: "fail",
5486
- message: err instanceof Error ? err.message : String(err)
5817
+ message: errorMessage(err)
5487
5818
  });
5488
5819
  }
5489
5820
  print(formatStep(steps[steps.length - 1]));
@@ -5699,7 +6030,7 @@ async function runSkillsInstall(input) {
5699
6030
  status: "ok"
5700
6031
  }, "skills install: done");
5701
6032
  } catch (err) {
5702
- const message = err instanceof Error ? err.message : String(err);
6033
+ const message = errorMessage(err);
5703
6034
  print(` ✗ ${message}`);
5704
6035
  logger.warn({
5705
6036
  agent: config.agent,
@@ -5857,11 +6188,13 @@ async function runSyncReadme(input) {
5857
6188
  }
5858
6189
  const description = loaded.resolved.description ?? "";
5859
6190
  const homepage = loaded.resolved.homepage ?? pkg.homepage ?? "";
6191
+ const scripts = pkg.scripts ?? {};
6192
+ const packages = pkg.name ? REGISTRY_MAP[pkg.name]?.() : void 0;
5860
6193
  const sections = generateReadme({
5861
6194
  description,
5862
6195
  homepage,
5863
- scripts: pkg.scripts ?? {},
5864
- packages: pkg.name ? REGISTRY_MAP[pkg.name]?.() : void 0
6196
+ scripts,
6197
+ packages
5865
6198
  });
5866
6199
  const markerSections = {
5867
6200
  ...sections.packages !== void 0 && { packages: sections.packages },
@@ -6103,7 +6436,7 @@ async function runSyncWiki(input) {
6103
6436
  capability: "local",
6104
6437
  step: "sync wiki",
6105
6438
  status: "fail",
6106
- message: err instanceof Error ? err.message : /* c8 ignore next */ String(err)
6439
+ message: err instanceof Error ? err.message : /* c8 ignore next */ String(err)
6107
6440
  };
6108
6441
  }
6109
6442
  }
@@ -6165,55 +6498,59 @@ async function runSync(input) {
6165
6498
  for (const stepName of SYNC_STEPS) {
6166
6499
  if (requestedSteps !== void 0 && !requestedSteps.includes(stepName)) continue;
6167
6500
  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]));
6501
+ if (stepName === "labels") {
6502
+ if (source.syncLabels) {
6503
+ steps.push(await runSyncStep("source", "sync labels", dryRun, () => source.syncLabels(CANONICAL_LABELS, STALE_LABELS)));
6504
+ print(formatSyncStep(steps[steps.length - 1]));
6505
+ } else {
6506
+ steps.push({
6507
+ capability: "source",
6508
+ step: "sync labels",
6509
+ status: "skip",
6510
+ message: "provider does not implement syncLabels"
6511
+ });
6512
+ print(formatSyncStep(steps[steps.length - 1]));
6513
+ }
6179
6514
  }
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
6515
+ if (stepName === "properties") {
6516
+ if (source.syncProperties) {
6517
+ const repo = config.repo;
6518
+ const properties = {};
6519
+ const effectivePreset = repo?.protection;
6520
+ if (effectivePreset && effectivePreset !== "none") properties["holocron_branch_protection_level"] = effectivePreset;
6521
+ const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
6522
+ properties["monorepo"] = String(isMonorepo);
6523
+ const manual = repo?.properties ?? {};
6524
+ if (manual.lifecycle) properties["lifecycle"] = manual.lifecycle;
6525
+ if (manual.open_source !== void 0) properties["open_source"] = String(manual.open_source);
6526
+ if (manual.runtime_environment) properties["runtime_environment"] = manual.runtime_environment;
6527
+ if (manual.uses_external_packages !== void 0) properties["uses_external_packages"] = String(manual.uses_external_packages);
6528
+ {
6529
+ const rootPackageJson = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
6530
+ const workspacePackages = readWorkspacePackages(input.context.repoRoot);
6531
+ const workspacePackageJsons = await readWorkspacePackageJsons(input.context.repoRoot, workspacePackages);
6532
+ properties["holocron_profile"] = deriveProfile({
6533
+ rootPackageJson,
6534
+ repoName: basename(input.context.repoRoot),
6535
+ isMonorepo,
6536
+ workspacePackageJsons
6537
+ });
6538
+ properties["holocron_stack"] = deriveStack(rootPackageJson);
6539
+ const capabilities = deriveCapabilities(config.providers);
6540
+ properties["holocron_capabilities"] = capabilities;
6541
+ properties["holocron_compliance"] = deriveCompliance(capabilities);
6542
+ }
6543
+ steps.push(await runSyncStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
6544
+ print(formatSyncStep(steps[steps.length - 1]));
6545
+ } else {
6546
+ steps.push({
6547
+ capability: "source",
6548
+ step: "sync properties",
6549
+ status: "skip",
6550
+ message: "provider does not implement syncProperties"
6201
6551
  });
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);
6552
+ print(formatSyncStep(steps[steps.length - 1]));
6206
6553
  }
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
6554
  }
6218
6555
  if (stepName === "teams") {
6219
6556
  const teams = config.repo?.teams ?? [];
@@ -6425,29 +6762,34 @@ async function runSync(input) {
6425
6762
  }
6426
6763
  }
6427
6764
  }
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]));
6765
+ if (stepName === "scripts") {
6766
+ if (config.syncScripts === false) {
6767
+ steps.push({
6768
+ capability: "local",
6769
+ step: "sync scripts",
6770
+ status: "skip",
6771
+ message: "syncScripts: false"
6772
+ });
6773
+ print(formatSyncStep(steps[steps.length - 1]));
6774
+ } else {
6775
+ const tasksConfig = { tasks: config.tasks };
6776
+ if (config.holocronScript !== void 0) tasksConfig.holocronScript = config.holocronScript;
6777
+ const astromechScripts = createAstromech({
6778
+ cwd: input.context.repoRoot,
6779
+ config: tasksConfig,
6780
+ logger
6781
+ });
6782
+ const desired = astromechScripts.packageScripts();
6783
+ const turboContent = astromechScripts.turboConfig();
6784
+ const turboEligible = new Set(turboContent ? Object.keys(JSON.parse(turboContent).tasks) : []);
6785
+ steps.push(await runSyncStep("local", "sync scripts", dryRun, async () => {
6786
+ const changed = await mergePackageJsonScripts(input.context.repoRoot, desired, turboEligible);
6787
+ if (changed === null) return "no package.json";
6788
+ if (changed.length === 0) return `${Object.keys(desired).length} scripts already current`;
6789
+ return `${changed.join(", ")} set`;
6790
+ }));
6791
+ print(formatSyncStep(steps[steps.length - 1]));
6792
+ }
6451
6793
  }
6452
6794
  if (stepName === "turbo") {
6453
6795
  const astromechTurbo = createAstromech({
@@ -6469,9 +6811,10 @@ async function runSync(input) {
6469
6811
  await writeFile(join(input.context.repoRoot, "turbo.json"), content, "utf8");
6470
6812
  }));
6471
6813
  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);
6814
+ const rootPkgRaw = await readFile(join(input.context.repoRoot, "package.json"), "utf8").catch(() => null);
6815
+ const rootPkg = rootPkgRaw ? JSON.parse(rootPkgRaw) : null;
6473
6816
  const workspaceYaml = await readFile(join(input.context.repoRoot, "pnpm-workspace.yaml"), "utf8").catch(() => "");
6474
- const rootScripts = Object.keys(rootPkg?.scripts ?? {});
6817
+ const rootScripts = rootPkg?.scripts ?? {};
6475
6818
  const workspaceFix = astromechTurbo.ensureRootWorkspaceMember(workspaceYaml, rootScripts);
6476
6819
  if (workspaceFix.changed) {
6477
6820
  steps.push(await runSyncStep("local", "fix pnpm-workspace.yaml (root workspace member, #692)", dryRun, async () => {
@@ -6479,6 +6822,15 @@ async function runSync(input) {
6479
6822
  }));
6480
6823
  print(formatSyncStep(steps[steps.length - 1]));
6481
6824
  }
6825
+ if (rootPkgRaw) {
6826
+ const depFix = astromechTurbo.ensureTurboDependency(rootPkgRaw, workspaceFix.content);
6827
+ if (depFix.changed) {
6828
+ steps.push(await runSyncStep("local", "add turbo devDependency", dryRun, async () => {
6829
+ await writeFile(join(input.context.repoRoot, "package.json"), depFix.content, "utf8");
6830
+ }));
6831
+ print(formatSyncStep(steps[steps.length - 1]));
6832
+ }
6833
+ }
6482
6834
  }
6483
6835
  }
6484
6836
  if (stepName === "wiki") {
@@ -6536,7 +6888,7 @@ async function runSyncStep(capability, step, dryRun, body) {
6536
6888
  capability,
6537
6889
  step,
6538
6890
  status: "fail",
6539
- message: err instanceof Error ? err.message : String(err)
6891
+ message: errorMessage(err)
6540
6892
  };
6541
6893
  }
6542
6894
  }
@@ -6562,8 +6914,21 @@ async function writePackageJsonField(repoRoot, field, value) {
6562
6914
  * Merge `desired` script entries into `package.json#scripts` — sets only the
6563
6915
  * listed keys, never touches the rest. Returns the sorted list of keys that
6564
6916
  * drifted (empty when all current), or `null` when there is no `package.json`.
6917
+ *
6918
+ * `turboEligible` (#747): task names `turbo.json` fans out — the same set
6919
+ * {@link EnsureRootWorkspaceMemberResult} above already keys off. For those
6920
+ * only, an *existing* script that isn't the generated `holocron run <task>
6921
+ * --` wrapper is left untouched: root may genuinely be a directly-buildable
6922
+ * package (not an orchestrator) with its own real command (`tsc --noEmit`,
6923
+ * `vitest run`, …) for that task. Overwriting it would silently discard the
6924
+ * real command and, once `turbo.json` exists and root is a real workspace
6925
+ * member (#692), reintroduce infinite recursion — `turbo run <task>` →
6926
+ * root's own `<task>` script → the wrapper → `holocron run <task>` sees
6927
+ * `turbo.json` still defines the task → `turbo run <task>` again, forever.
6928
+ * Every other key (non-turbo tasks, `holocron`, `prepare`, …) has no
6929
+ * legitimate direct-command alternative and stays fully generator-owned.
6565
6930
  */
6566
- async function mergePackageJsonScripts(repoRoot, desired) {
6931
+ async function mergePackageJsonScripts(repoRoot, desired, turboEligible) {
6567
6932
  const pkgPath = join(repoRoot, "package.json");
6568
6933
  let content;
6569
6934
  try {
@@ -6574,15 +6939,31 @@ async function mergePackageJsonScripts(repoRoot, desired) {
6574
6939
  const pkg = JSON.parse(content);
6575
6940
  const scripts = pkg.scripts ?? {};
6576
6941
  const changed = [];
6577
- for (const [name, command] of Object.entries(desired)) if (scripts[name] !== command) {
6578
- scripts[name] = command;
6579
- changed.push(name);
6942
+ for (const [name, command] of Object.entries(desired)) {
6943
+ const existing = scripts[name];
6944
+ if (turboEligible.has(name) && existing !== void 0 && !isGeneratedRunWrapper(existing, name)) continue;
6945
+ if (existing !== command) {
6946
+ scripts[name] = command;
6947
+ changed.push(name);
6948
+ }
6580
6949
  }
6581
6950
  if (changed.length === 0) return [];
6582
6951
  pkg.scripts = scripts;
6583
6952
  await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
6584
6953
  return changed.sort();
6585
6954
  }
6955
+ /**
6956
+ * Matches the exact shape `packageScripts()` generates for `taskName` —
6957
+ * `<bin> run <taskName> --`, `<bin>` normally `holocron` but substitutable
6958
+ * (`holocronScript`, itself allowed to be multi-word, e.g. `"node
6959
+ packages/cli/dist/cli.mjs"` — see its own test). Checking the *suffix*
6960
+ * rather than the whole string means an old wrapper survives a
6961
+ * `holocronScript` rename intact — it's still recognized as a wrapper (safe
6962
+ * to update to the new one), not mistaken for a real command.
6963
+ */
6964
+ function isGeneratedRunWrapper(command, taskName) {
6965
+ return command.endsWith(` run ${taskName} --`);
6966
+ }
6586
6967
  const README_DESC_START = "<!-- holocron:description -->";
6587
6968
  const README_DESC_END = "<!-- /holocron:description -->";
6588
6969
  async function updateReadmeDescription(repoRoot, description) {
@@ -6954,7 +7335,7 @@ async function runSyncGithub(input) {
6954
7335
  sha: blob.sha
6955
7336
  });
6956
7337
  } catch (err) {
6957
- const msg = `failed to create blob for ${file.path}: ${err instanceof Error ? err.message : String(err)}`;
7338
+ const msg = `failed to create blob for ${file.path}: ${errorMessage(err)}`;
6958
7339
  print(` ✗ ${msg}`);
6959
7340
  return done({
6960
7341
  status: "fail",
@@ -6968,7 +7349,7 @@ async function runSyncGithub(input) {
6968
7349
  try {
6969
7350
  newTreeSha = (await client.git.createTree(repo, treeEntries, baseTreeSha)).sha;
6970
7351
  } catch (err) {
6971
- const msg = `failed to create tree: ${err instanceof Error ? err.message : String(err)}`;
7352
+ const msg = `failed to create tree: ${errorMessage(err)}`;
6972
7353
  print(` ✗ ${msg}`);
6973
7354
  return done({
6974
7355
  status: "fail",
@@ -6982,7 +7363,7 @@ async function runSyncGithub(input) {
6982
7363
  try {
6983
7364
  newCommitSha = (await client.git.createCommit(repo, message, newTreeSha, [headSha])).sha;
6984
7365
  } catch (err) {
6985
- const msg = `failed to create commit: ${err instanceof Error ? err.message : String(err)}`;
7366
+ const msg = `failed to create commit: ${errorMessage(err)}`;
6986
7367
  print(` ✗ ${msg}`);
6987
7368
  return done({
6988
7369
  status: "fail",
@@ -7001,7 +7382,7 @@ async function runSyncGithub(input) {
7001
7382
  }
7002
7383
  else await client.git.updateRef(repo, `heads/${targetBranch}`, newCommitSha);
7003
7384
  } catch (err) {
7004
- const msg = `failed to update ref: ${err instanceof Error ? err.message : String(err)}`;
7385
+ const msg = `failed to update ref: ${errorMessage(err)}`;
7005
7386
  print(` ✗ ${msg}`);
7006
7387
  return done({
7007
7388
  status: "fail",
@@ -7022,7 +7403,7 @@ async function runSyncGithub(input) {
7022
7403
  print(` → PR opened: ${prUrl}`);
7023
7404
  } catch (err) {
7024
7405
  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)}`);
7406
+ else print(` ⚠ PR creation failed: ${errorMessage(err)}`);
7026
7407
  }
7027
7408
  return done({
7028
7409
  status: "ok",
@@ -7449,6 +7830,63 @@ async function runUpgradeNode(input) {
7449
7830
  };
7450
7831
  }
7451
7832
  //#endregion
7833
+ //#region src/commit-lint/lint-message.ts
7834
+ /**
7835
+ * Lints one commit message string against an already-loaded commitlint
7836
+ * config. The genuinely environment-independent half of commit-message
7837
+ * linting (holocron#789) — *obtaining* a `QualifiedConfig` differs by
7838
+ * caller (Sentinel isolates itself from any ambient config since it runs
7839
+ * standalone, away from a real repo checkout; `lintCommitMsgFile` below
7840
+ * just lets cosmiconfig discover the invoking repo's own
7841
+ * `commitlint.config.*`, matching `commitlint --edit`'s own contract) —
7842
+ * but linting one message against a loaded config is identical either way.
7843
+ *
7844
+ * Real `@commitlint/lint` — the same programmatic API `@commitlint/cli`
7845
+ * itself uses internally — never a reimplementation of commitlint's rules.
7846
+ */
7847
+ /** `parserPreset.parserOpts`, if the loaded config sets one — same lookup `@commitlint/cli`'s own `selectParserOpts()` does. */
7848
+ function selectParserOpts(parserPreset) {
7849
+ return parserPreset?.parserOpts;
7850
+ }
7851
+ async function lintCommitMessage(message, loaded) {
7852
+ const opts = {
7853
+ /* istanbul ignore next -- see comment above */
7854
+ parserOpts: selectParserOpts(loaded.parserPreset) ?? {},
7855
+ plugins: loaded.plugins,
7856
+ /* istanbul ignore next -- see comment above */
7857
+ ignores: loaded.ignores ?? [],
7858
+ defaultIgnores: loaded.defaultIgnores !== false
7859
+ };
7860
+ const outcome = await lint(message, loaded.rules, opts);
7861
+ if (outcome.valid) return [];
7862
+ return outcome.errors.map((error) => ({
7863
+ rule: error.name,
7864
+ message: error.message
7865
+ }));
7866
+ }
7867
+ //#endregion
7868
+ //#region src/commit-lint/lint-commit-msg-file.ts
7869
+ /**
7870
+ * `holocron lint commit-msg <file>` — a real programmatic replacement for
7871
+ * shelling out to `commitlint --edit "$1"` from `.husky/commit-msg`
7872
+ * (holocron#789). Matches that CLI's own contract exactly: `file` is a
7873
+ * path to the commit message being written (the arg git's `commit-msg`
7874
+ * hook passes as `$1`), no `--config` override needed — `@commitlint/load`
7875
+ * runs from `cwd` with no seed, so cosmiconfig's own normal upward search
7876
+ * discovers the invoking repo's real `commitlint.config.*` file, exactly
7877
+ * as `commitlint --edit` (no `--config` flag) already does today. Unlike
7878
+ * Sentinel's `loadIsolatedConfig()`, no isolation is needed here — this
7879
+ * runs inside a real repo checkout with a real `node_modules`, not
7880
+ * standalone on a server.
7881
+ */
7882
+ async function lintCommitMsgFile(filePath, cwd = process.cwd()) {
7883
+ const violations = await lintCommitMessage(await readFile(filePath, "utf8"), await load({}, { cwd }));
7884
+ return {
7885
+ valid: violations.length === 0,
7886
+ violations
7887
+ };
7888
+ }
7889
+ //#endregion
7452
7890
  //#region src/config/load-config.ts
7453
7891
  /**
7454
7892
  * `holocron.config.{ts,js,mjs,cjs,json}` loader.
@@ -7463,14 +7901,19 @@ async function runUpgradeNode(input) {
7463
7901
  */
7464
7902
  const execFileAsync = promisify(execFile);
7465
7903
  /**
7466
- * Read + parse + resolve `holocron.config.*` from the given directory.
7904
+ * Read + parse + resolve `holocron.config.*` starting from the given
7905
+ * directory, walking up through ancestors to the nearest `.git` boundary
7906
+ * when `cwd` itself has no match — every command is usable from any
7907
+ * subdirectory of a repo, not only its exact root (see
7908
+ * `@theholocron/datapad`'s own doc comment for the stop conditions).
7467
7909
  * Throws {@link ConfigFileError} when nothing is found or a file cannot
7468
- * be loaded, or `ConfigError` when the config is invalid.
7910
+ * be loaded, or `ConfigError` when the config fails schema checks.
7469
7911
  */
7470
7912
  async function loadConfig(cwd) {
7471
7913
  const found = await loadConfigFile({
7472
7914
  cwd,
7473
- name: "holocron"
7915
+ name: "holocron",
7916
+ walkUp: true
7474
7917
  });
7475
7918
  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
7919
  return {
@@ -7559,14 +8002,11 @@ const numeric = (value) => /^\d+$/.test(value) ? true : "enter a number";
7559
8002
  * The full command surface, hand-maintained in parallel with `cli.ts`'s
7560
8003
  * yargs registrations (this module does not introspect yargs at runtime).
7561
8004
  * `run <task>` is deliberately excluded — it's CI/scripting-oriented, and an
7562
- * interactive prompt in front of it would work against that.
8005
+ * interactive prompt in front of it would work against that. `lint
8006
+ * commit-msg <file>` is excluded for the same reason: it's invoked
8007
+ * exclusively from `.husky/commit-msg "$1"`, never typed by a human.
7563
8008
  */
7564
8009
  const COMMAND_REGISTRY = [
7565
- {
7566
- name: "version",
7567
- description: "Print the CLI version",
7568
- positionals: []
7569
- },
7570
8010
  {
7571
8011
  name: "clone",
7572
8012
  description: "Clone all repos in a GitHub org as siblings under a single directory",
@@ -7843,10 +8283,25 @@ function buildChildArgv(entry, positionals, parentArgv) {
7843
8283
  ...forwardedFlags(parentArgv)
7844
8284
  ];
7845
8285
  }
7846
- /** Spawn `holocron <...args>` inheriting stdio; resolve with its exit code. */
8286
+ /**
8287
+ * Spawn `holocron <...args>` inheriting stdio; resolve with its exit code.
8288
+ *
8289
+ * `NO_UPDATE_NOTIFIER` is forced on in the child's env — the parent's own
8290
+ * update-notifier tail still runs after this resolves (see `launchMenu`'s
8291
+ * docstring), so without this the freshly-spawned child independently runs
8292
+ * its own `checkForUpdates()` too and the notice prints twice: once from
8293
+ * the child right after its command output, once more from the parent
8294
+ * once the child exits.
8295
+ */
7847
8296
  function spawnChild(args) {
7848
8297
  return new Promise((resolve) => {
7849
- const child = spawn(process.execPath, [process.argv[1], ...args], { stdio: "inherit" });
8298
+ const child = spawn(process.execPath, [process.argv[1], ...args], {
8299
+ stdio: "inherit",
8300
+ env: {
8301
+ ...process.env,
8302
+ NO_UPDATE_NOTIFIER: "1"
8303
+ }
8304
+ });
7850
8305
  child.on("exit", (code) => resolve(code ?? 0));
7851
8306
  child.on("error", () => resolve(1));
7852
8307
  });
@@ -7870,7 +8325,7 @@ async function launchMenu(entries, parentArgv, pickMessage, nonInteractiveMessag
7870
8325
  //#endregion
7871
8326
  //#region src/update-notifier.ts
7872
8327
  const PACKAGE_NAME = "@theholocron/cli";
7873
- const CACHE_TTL_MS = 1440 * 60 * 1e3;
8328
+ const CACHE_TTL_MS = 864e5;
7874
8329
  const FETCH_TIMEOUT_MS = 3e3;
7875
8330
  function getCacheDir() {
7876
8331
  return env.get("HOLOCRON_CACHE_DIR") ?? join(homedir(), ".cache", "holocron");
@@ -8053,7 +8508,7 @@ let finishCommand = () => {};
8053
8508
  /** Set by `.fail()` once it has printed an error, so the outer catch doesn't repeat it. */
8054
8509
  let errorReported = false;
8055
8510
  try {
8056
- await yargs(hideBin(process.argv)).scriptName("").usage("holocron <command> [options]").parserConfiguration({ "populate--": true }).option("dry-run", {
8511
+ await yargs(hideBin(process.argv)).scriptName("").usage("holocron <command> [options]").version(CLI_VERSION).alias("version", "v").parserConfiguration({ "populate--": true }).option("dry-run", {
8057
8512
  type: "boolean",
8058
8513
  default: false,
8059
8514
  describe: "Print what would be mutated without calling capability mutators. Commands branch on this; read-only commands ignore it."
@@ -8088,8 +8543,6 @@ try {
8088
8543
  org: argv.org
8089
8544
  });
8090
8545
  finishCommand = startCommand(name);
8091
- }).command("version", "Print the CLI version", () => {}, () => {
8092
- console.log(`holocron ${CLI_VERSION}`);
8093
8546
  }).command("clone", "Clone all repos in a GitHub org as siblings under a single directory", (y) => y.option("org", {
8094
8547
  type: "string",
8095
8548
  demandOption: true,
@@ -8236,9 +8689,17 @@ try {
8236
8689
  type: "array",
8237
8690
  default: ["production", "preview"],
8238
8691
  describe: "Deployment targets to sync to. Defaults to production + preview."
8692
+ }).option("github-secret", {
8693
+ type: "array",
8694
+ describe: "Vault key(s) to push to GH Actions secrets (repeatable). Omit to push every key."
8695
+ }).option("github-secret-scope", {
8696
+ type: "string",
8697
+ default: "repo",
8698
+ describe: "Scope applied to every --github-secret key: \"repo\" (default), \"env=<name>\", or \"org=<name>\"."
8239
8699
  }), async (argv) => {
8240
8700
  const tokens = tokenContext(argv.token);
8241
8701
  if (!tokens) return;
8702
+ const githubSecretScope = parseScope(argv.githubSecretScope);
8242
8703
  const [environmentId] = await promptForPositionals(getEntry("secrets sync"), argv);
8243
8704
  const loaded = await loadConfig(argv.cwd);
8244
8705
  applyResolvedConfig(argv, loaded.resolved);
@@ -8252,11 +8713,13 @@ try {
8252
8713
  },
8253
8714
  environmentId,
8254
8715
  ...argv.projectId ? { projectId: argv.projectId } : {},
8716
+ ...argv.githubSecret?.length ? { githubSecretKeys: argv.githubSecret } : {},
8717
+ githubSecretScope,
8255
8718
  targets: argv.target
8256
8719
  })).summary.fail > 0) process.exitCode = 1;
8257
8720
  }).command("deploy [branch]", "Trigger a deployment via the configured `deployment` capability", (y) => y.positional("branch", {
8258
8721
  type: "string",
8259
- describe: "Git branch to deploy"
8722
+ describe: "Git branch to deploy (omit when using --files)"
8260
8723
  }).option("project-id", {
8261
8724
  type: "string",
8262
8725
  demandOption: true,
@@ -8265,20 +8728,34 @@ try {
8265
8728
  type: "string",
8266
8729
  choices: ["production", "staging"],
8267
8730
  describe: "Named environment to deploy into. Omit for a branch preview."
8268
- }), async (argv) => {
8731
+ }).option("files", {
8732
+ type: "string",
8733
+ describe: "Deploy from a local directory of source files instead of a Git branch — calls deployFunction(), no linked repo required. Conflicts with `branch`."
8734
+ }).conflicts("files", "branch"), async (argv) => {
8269
8735
  const tokens = tokenContext(argv.token);
8270
8736
  if (!tokens) return;
8271
- const [branch] = await promptForPositionals(getEntry("deploy"), argv);
8272
8737
  const loaded = await loadConfig(argv.cwd);
8273
8738
  applyResolvedConfig(argv, loaded.resolved);
8739
+ const context = {
8740
+ repoRoot: argv.cwd,
8741
+ dryRun: argv.dryRun,
8742
+ ...tokens,
8743
+ org: resolveOrg(argv, loaded.resolved)
8744
+ };
8745
+ if (argv.files) {
8746
+ if ((await runDeployFromFiles({
8747
+ loaded,
8748
+ context,
8749
+ projectId: argv.projectId,
8750
+ dir: argv.files,
8751
+ ...argv.target ? { target: argv.target } : {}
8752
+ })).status === "fail") process.exitCode = 1;
8753
+ return;
8754
+ }
8755
+ const [branch] = await promptForPositionals(getEntry("deploy"), argv);
8274
8756
  if ((await runDeploy({
8275
8757
  loaded,
8276
- context: {
8277
- repoRoot: argv.cwd,
8278
- dryRun: argv.dryRun,
8279
- ...tokens,
8280
- org: resolveOrg(argv, loaded.resolved)
8281
- },
8758
+ context,
8282
8759
  projectId: argv.projectId,
8283
8760
  branch,
8284
8761
  ...argv.target ? { target: argv.target } : {}
@@ -8454,7 +8931,36 @@ try {
8454
8931
  scope: argv.all ? "all" : "required",
8455
8932
  ...argv.filter ? { filter: argv.filter } : {}
8456
8933
  }).status === "fail") process.exitCode = 1;
8457
- }).command("sync-github", "Sync workflow templates and composite actions to theholocron/.github", (y) => y.option("repo", {
8934
+ }).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", {
8935
+ type: "string",
8936
+ default: "",
8937
+ describe: "The release's channel: its prerelease identifier (`alpha`); empty or `main` for a stable release."
8938
+ }).option("from", {
8939
+ type: "string",
8940
+ describe: "The previous release's commit, to diff against. Omit when there is none."
8941
+ }).option("to", {
8942
+ type: "string",
8943
+ describe: "The release commit. Default HEAD."
8944
+ }), async (argv) => {
8945
+ if ((await deployOnRelease({
8946
+ cwd: argv.cwd,
8947
+ channel: argv.channel,
8948
+ ...argv.from ? { from: argv.from } : {},
8949
+ ...argv.to ? { to: argv.to } : {},
8950
+ dryRun: argv.dryRun,
8951
+ print: (line) => console.log(line)
8952
+ })).status === "fail") process.exitCode = 1;
8953
+ }).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", {
8954
+ type: "string",
8955
+ demandOption: true,
8956
+ describe: "Path to the commit message file (git's commit-msg hook passes this as $1)."
8957
+ }), async (argv) => {
8958
+ const result = await lintCommitMsgFile(argv.file, argv.cwd);
8959
+ if (!result.valid) {
8960
+ for (const violation of result.violations) console.error(`✖ ${violation.rule}: ${violation.message}`);
8961
+ process.exitCode = 1;
8962
+ }
8963
+ }), () => {}).command("sync-github", "Sync workflow templates and composite actions to theholocron/.github", (y) => y.option("repo", {
8458
8964
  type: "string",
8459
8965
  default: "theholocron/.github",
8460
8966
  describe: "Target org/repo (default: theholocron/.github)"
@@ -8896,6 +9402,7 @@ try {
8896
9402
  }).command("$0", false, () => {}, async (argv) => {
8897
9403
  await launchMenu(COMMAND_REGISTRY.filter((e) => e.group === "auth"), argv, "auth — choose a subcommand:", "Run `holocron auth --help` to see available auth subcommands.");
8898
9404
  }), () => {}).command("$0", false, () => {}, async (argv) => {
9405
+ console.log(style.dim(`holocron v${CLI_VERSION}`));
8899
9406
  await launchMenu(COMMAND_REGISTRY.filter((e) => !e.group), argv);
8900
9407
  }).strict().help().epilogue(`Execution contexts:
8901
9408
  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) => {