@theholocron/cli 5.0.0-alpha.372 → 5.0.0-alpha.374

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
@@ -37,6 +37,7 @@ import { createServer } from "node:http";
37
37
  import { runCheckAgainstUrl } from "@theholocron/kyber/checks";
38
38
  import { moveMajorTag } from "@theholocron/kyber/git";
39
39
  import { ADR_DIR, ADR_STATUSES, CLOSED_STATUSES, SPEC_DIRS, SPEC_STATUSES, WITHDRAWN_STATE, assignSpecIds, checkSpecs, classifySpecPath, discussionBody, discussionIdLine, discussionPrLine, discussionTitle, evaluateDocsPresence, isAddedDocComment, isFeat, packageOf, parseFrontmatter, parseSkipDocs, reconcileSpecStatus, specSummary, specTitle, updateFrontmatter } from "@theholocron/astromech/repo-validation";
40
+ import { loadConfigPath } from "@theholocron/datapad";
40
41
  import { fetchLatestFromNpm, runUpgradeNode } from "@theholocron/astromech/upgrade";
41
42
  import { lintCommitMsgFile } from "@theholocron/astromech/lint";
42
43
  // src/plugin/capabilities/capabilities.ts
@@ -501,20 +502,20 @@ const ORG_OPTIONS = {
501
502
  checkly: ["accountId"],
502
503
  sentry: ["org"]
503
504
  };
504
- const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
505
- const isTuple = (entry) => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && isObject(entry[1]);
505
+ const isObject$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
506
+ const isTuple = (entry) => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && isObject$1(entry[1]);
506
507
  /**
507
508
  * Check the shape of the area file: the top-level `domain` (a non-empty string), then a closed list of providers,
508
509
  * each with a closed list of string options.
509
510
  */
510
511
  function validate(area) {
511
- if (!isObject(area.value)) throw new ConfigError(`${area.path} must export the org settings as an object`);
512
+ if (!isObject$1(area.value)) throw new ConfigError(`${area.path} must export the org settings as an object`);
512
513
  const { domain, ...rest } = area.value;
513
514
  if (domain !== void 0 && (typeof domain !== "string" || domain === "")) throw new ConfigError(`${area.path}: "domain" must be a non-empty string`);
514
515
  for (const [provider, options] of Object.entries(rest)) {
515
516
  const allowed = ORG_OPTIONS[provider];
516
517
  if (allowed === void 0) throw new ConfigError(`${area.path} has an unknown provider "${provider}". Known: ${Object.keys(ORG_OPTIONS).join(", ")}`);
517
- if (!isObject(options)) throw new ConfigError(`${area.path}: "${provider}" must be an object of options`);
518
+ if (!isObject$1(options)) throw new ConfigError(`${area.path}: "${provider}" must be an object of options`);
518
519
  for (const [option, value] of Object.entries(options)) {
519
520
  if (!allowed.includes(option)) throw new ConfigError(`${area.path}: "${provider}.${option}" is not an org option. Known: ${allowed.join(", ")}`);
520
521
  if (typeof value !== "string" || value === "") throw new ConfigError(`${area.path}: "${provider}.${option}" must be a non-empty string`);
@@ -963,6 +964,57 @@ function applyResolvedConfig(argv, resolved) {
963
964
  buildCliLogger(argv, cliLoggerOpts(argv, resolved));
964
965
  applyConfig(resolved.telemetry);
965
966
  }
967
+ // src/plugin/workspace/workspace.ts
968
+ /**
969
+ * The `workspace`-context guard.
970
+ *
971
+ * A `workspace` command (`sync`, `setup`, `doctor`, …) needs the
972
+ * configured providers' `@theholocron/holocron-plugin-*` packages to
973
+ * resolve. From a bare `npm i -g @theholocron/cli` they don't, and the
974
+ * {@link PluginLoader} — which soft-skips every failure — leaves the
975
+ * command with an empty registry and a stack of `Cannot find package`
976
+ * errors.
977
+ *
978
+ * {@link assertPluginsResolvable} turns that specific situation (every
979
+ * provider failed, and every failure is a module-resolution failure)
980
+ * into one actionable {@link WorkspaceContextError} the CLI prints
981
+ * instead of a stack trace. Any other mix — some plugins loaded, or a
982
+ * failure that's an auth/token error rather than a missing package —
983
+ * is left alone for the command's own soft-skip reporting. The check
984
+ * itself is kyber's; the message here is Holocron's.
985
+ *
986
+ * Spec: `docs/wiki/specifications/tech-cli-execution-contexts.spec.md`
987
+ * (theholocron/holocron#576).
988
+ */
989
+ /**
990
+ * Raised when a `workspace` command runs somewhere its provider plugins
991
+ * cannot be resolved — the "you're on a global install" case. Carries the
992
+ * unresolved package names so the message can be specific.
993
+ */
994
+ var WorkspaceContextError = class extends Error {
995
+ name = "WorkspaceContextError";
996
+ command;
997
+ packages;
998
+ constructor(command, packages) {
999
+ const [first, ...rest] = packages;
1000
+ const subject = rest.length > 0 ? `${first} (and ${rest.length} other${rest.length === 1 ? "" : "s"})` : first ?? "its plugins";
1001
+ super(`\`${command}\` needs ${subject}, but no plugin package resolves here.\nRun it from a repo that has the \`@theholocron/holocron-plugin-*\` packages as devDependencies, or \`pnpm exec holocron ${command}\`. A global install can't resolve them — see https://docs.theholocron.dev/holocron/execution-contexts`);
1002
+ this.command = command;
1003
+ this.packages = packages;
1004
+ }
1005
+ };
1006
+ /**
1007
+ * Throw {@link WorkspaceContextError} when a loaded `PluginLoader` shows
1008
+ * the global-install signature: nothing in the registry, at least one
1009
+ * failure, and *every* failure is a missing-package error. A no-op in
1010
+ * every other case (some capability loaded, non-import failure, or no
1011
+ * providers configured at all).
1012
+ *
1013
+ * Call it right after `await loader.load()` in a `workspace` command.
1014
+ */
1015
+ function assertPluginsResolvable$1(loader, command) {
1016
+ assertPluginsResolvable(loader, command, (cmd, packages) => new WorkspaceContextError(cmd, packages));
1017
+ }
966
1018
  // src/plugin/loader/loader.ts
967
1019
  /**
968
1020
  * `PluginLoader` — loads provider plugins per the resolved config and
@@ -1033,13 +1085,40 @@ var PluginLoader = class extends system.PluginLoader {
1033
1085
  /** The `setup` and `doctor` each loaded provider offers, by provider name. A provider with neither is left out. */
1034
1086
  providerActions() {
1035
1087
  const found = /* @__PURE__ */ new Map();
1036
- for (const [provider, plugin] of this.plugins()) if (plugin.setup || plugin.doctor) found.set(provider, {
1037
- ...plugin.setup ? { setup: plugin.setup } : {},
1038
- ...plugin.doctor ? { doctor: plugin.doctor } : {}
1039
- });
1088
+ for (const [provider, plugin] of this.plugins()) {
1089
+ const actions = actionsOf(plugin);
1090
+ if (actions.setup || actions.doctor) found.set(provider, actions);
1091
+ }
1040
1092
  return found;
1041
1093
  }
1094
+ /**
1095
+ * Loads one provider by name with the given options, whether or not `holocron.config` names it under a capability,
1096
+ * and returns its `setup` and `doctor` (either may be missing). It reads the provider's token the way a configured
1097
+ * one does (`--token`, the environment, `.env`, the `credentials` providers, the keyring) and leaves the capability
1098
+ * registry alone. Throws {@link WorkspaceContextError} when the provider's package cannot be imported here; any
1099
+ * other failure of the plugin's `createPlugin` is thrown as it is.
1100
+ */
1101
+ async loadProviderActions(provider, options) {
1102
+ const packageName = system.resolvePackage(provider);
1103
+ try {
1104
+ return actionsOf(await this.loadProvider({
1105
+ provider,
1106
+ packageName,
1107
+ options
1108
+ }));
1109
+ } catch (err) {
1110
+ if (err instanceof LoaderError && err.message.startsWith("failed to import")) throw new WorkspaceContextError("provider", [packageName]);
1111
+ throw err;
1112
+ }
1113
+ }
1042
1114
  };
1115
+ /** The `setup` and `doctor` a created plugin carries. */
1116
+ function actionsOf(plugin) {
1117
+ return {
1118
+ ...plugin.setup ? { setup: plugin.setup } : {},
1119
+ ...plugin.doctor ? { doctor: plugin.doctor } : {}
1120
+ };
1121
+ }
1043
1122
  // src/plugin/verify-vercel-project/verify-vercel-project.ts
1044
1123
  /**
1045
1124
  * `true` only when Vercel's API confirms `url` resolves to a deployment
@@ -1075,57 +1154,6 @@ async function verifyVercelDeploymentProject(url, expectedProjectId, token, opts
1075
1154
  }
1076
1155
  return (typeof body === "object" && body !== null && "projectId" in body ? body.projectId : void 0) === expectedProjectId;
1077
1156
  }
1078
- // src/plugin/workspace/workspace.ts
1079
- /**
1080
- * The `workspace`-context guard.
1081
- *
1082
- * A `workspace` command (`sync`, `setup`, `doctor`, …) needs the
1083
- * configured providers' `@theholocron/holocron-plugin-*` packages to
1084
- * resolve. From a bare `npm i -g @theholocron/cli` they don't, and the
1085
- * {@link PluginLoader} — which soft-skips every failure — leaves the
1086
- * command with an empty registry and a stack of `Cannot find package`
1087
- * errors.
1088
- *
1089
- * {@link assertPluginsResolvable} turns that specific situation (every
1090
- * provider failed, and every failure is a module-resolution failure)
1091
- * into one actionable {@link WorkspaceContextError} the CLI prints
1092
- * instead of a stack trace. Any other mix — some plugins loaded, or a
1093
- * failure that's an auth/token error rather than a missing package —
1094
- * is left alone for the command's own soft-skip reporting. The check
1095
- * itself is kyber's; the message here is Holocron's.
1096
- *
1097
- * Spec: `docs/wiki/specifications/tech-cli-execution-contexts.spec.md`
1098
- * (theholocron/holocron#576).
1099
- */
1100
- /**
1101
- * Raised when a `workspace` command runs somewhere its provider plugins
1102
- * cannot be resolved — the "you're on a global install" case. Carries the
1103
- * unresolved package names so the message can be specific.
1104
- */
1105
- var WorkspaceContextError = class extends Error {
1106
- name = "WorkspaceContextError";
1107
- command;
1108
- packages;
1109
- constructor(command, packages) {
1110
- const [first, ...rest] = packages;
1111
- const subject = rest.length > 0 ? `${first} (and ${rest.length} other${rest.length === 1 ? "" : "s"})` : first ?? "its plugins";
1112
- super(`\`${command}\` needs ${subject}, but no plugin package resolves here.\nRun it from a repo that has the \`@theholocron/holocron-plugin-*\` packages as devDependencies, or \`pnpm exec holocron ${command}\`. A global install can't resolve them — see https://docs.theholocron.dev/holocron/execution-contexts`);
1113
- this.command = command;
1114
- this.packages = packages;
1115
- }
1116
- };
1117
- /**
1118
- * Throw {@link WorkspaceContextError} when a loaded `PluginLoader` shows
1119
- * the global-install signature: nothing in the registry, at least one
1120
- * failure, and *every* failure is a missing-package error. A no-op in
1121
- * every other case (some capability loaded, non-import failure, or no
1122
- * providers configured at all).
1123
- *
1124
- * Call it right after `await loader.load()` in a `workspace` command.
1125
- */
1126
- function assertPluginsResolvable$1(loader, command) {
1127
- assertPluginsResolvable(loader, command, (cmd, packages) => new WorkspaceContextError(cmd, packages));
1128
- }
1129
1157
  // src/commands/auth/auth.ts
1130
1158
  /**
1131
1159
  * `holocron auth <subcommand>` — manage bootstrap credentials in the
@@ -2215,19 +2243,28 @@ const migrateProjectEntry = {
2215
2243
  message: "Board to move (by name):",
2216
2244
  type: "input"
2217
2245
  }],
2218
- options: [{
2219
- key: "from",
2220
- flag: "--from",
2221
- type: "input",
2222
- required: true,
2223
- message: "Move it from (github, linear:team=ENG):"
2224
- }, {
2225
- key: "to",
2226
- flag: "--to",
2227
- type: "input",
2228
- required: true,
2229
- message: "Move it to:"
2230
- }],
2246
+ options: [
2247
+ {
2248
+ key: "from",
2249
+ flag: "--from",
2250
+ type: "input",
2251
+ required: true,
2252
+ message: "Move it from (github, linear:team=ENG):"
2253
+ },
2254
+ {
2255
+ key: "to",
2256
+ flag: "--to",
2257
+ type: "input",
2258
+ required: true,
2259
+ message: "Move it to:"
2260
+ },
2261
+ {
2262
+ key: "template",
2263
+ flag: "--template",
2264
+ type: "input",
2265
+ message: "Board template to make a missing board from (default roadmap):"
2266
+ }
2267
+ ],
2231
2268
  skipOptions: [
2232
2269
  "open-only",
2233
2270
  "milestone",
@@ -2457,7 +2494,7 @@ const providerEntry = {
2457
2494
  name: "provider",
2458
2495
  description: "List the providers that have their own setup and doctor (`provider <name> setup|doctor` runs one)",
2459
2496
  positionals: [],
2460
- skipOptions: ["yes"],
2497
+ skipOptions: ["yes", "with"],
2461
2498
  supportsDryRun: false
2462
2499
  };
2463
2500
  // src/commands/publish/publish.entry.ts
@@ -11165,7 +11202,7 @@ async function openSide(input) {
11165
11202
  const { endpoint, capabilities } = input;
11166
11203
  const base = input.loaded.resolved.providers;
11167
11204
  const providers = {};
11168
- for (const key of capabilities) {
11205
+ for (const key of [...capabilities, ...input.optional ?? []]) {
11169
11206
  const own = base[key];
11170
11207
  const ownOptions = own?.cardinality === "single" && own.tuple.provider === endpoint.provider ? own.tuple.options : {};
11171
11208
  providers[key] = {
@@ -11202,8 +11239,27 @@ async function openSide(input) {
11202
11239
  if (key === "issues") side.issues = loader.get("issues");
11203
11240
  else side.projects = loader.get("projects");
11204
11241
  }
11242
+ if (input.optional?.includes("projects") && loader.has("projects")) side.projects = loader.get("projects");
11205
11243
  return side;
11206
11244
  }
11245
+ // src/commands/parse-option-pairs/parse-option-pairs.ts
11246
+ /**
11247
+ * Reads `key=value,key=value` into text options, for a flag that points a provider somewhere (`--from linear:team=ENG`,
11248
+ * `--with team=ENG`). Blank pairs are skipped; a pair with no `=`, or an empty key, is a {@link ConfigError} naming
11249
+ * `flag`. Values are text; a provider that wants more shape reads it from a config entry or a file.
11250
+ *
11251
+ * @param text - The pairs, comma separated.
11252
+ * @param flag - The flag the text came from, for the error message.
11253
+ */
11254
+ function parseOptionPairs(text, flag) {
11255
+ const options = {};
11256
+ for (const pair of text.split(",").filter((p) => p.trim() !== "")) {
11257
+ const eq = pair.indexOf("=");
11258
+ if (eq <= 0) throw new ConfigError$1(`${flag}: "${pair}" is not key=value`);
11259
+ options[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
11260
+ }
11261
+ return options;
11262
+ }
11207
11263
  // src/commands/migrate/parse-endpoint/parse-endpoint.ts
11208
11264
  /**
11209
11265
  * Reads `provider` or `provider:key=value,key=value` (`github:repo=theholocron/holocron`, `linear:team=ENG`) from
@@ -11214,16 +11270,99 @@ function parseEndpoint(spec, flag = "--from") {
11214
11270
  const colon = spec.indexOf(":");
11215
11271
  const provider = (colon === -1 ? spec : spec.slice(0, colon)).trim();
11216
11272
  if (!/^[a-z][a-z0-9-]*$/.test(provider)) throw new ConfigError$1(`${flag}: "${spec}" does not start with a provider name, e.g. github or linear:team=ENG`);
11217
- const options = {};
11218
- const rest = colon === -1 ? "" : spec.slice(colon + 1);
11219
- for (const pair of rest.split(",").filter((p) => p.trim() !== "")) {
11220
- const eq = pair.indexOf("=");
11221
- if (eq <= 0) throw new ConfigError$1(`${flag}: "${pair}" is not key=value`);
11222
- options[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
11223
- }
11224
11273
  return {
11225
11274
  provider,
11226
- options
11275
+ options: parseOptionPairs(colon === -1 ? "" : spec.slice(colon + 1), flag)
11276
+ };
11277
+ }
11278
+ // src/commands/migrate/place-on-board/place-on-board.ts
11279
+ /** The board category an issue's own status category stands for; `other` has none, so only a named status carries. */
11280
+ const BOARD_CATEGORY = {
11281
+ open: "planned",
11282
+ "in-progress": "active",
11283
+ "in-review": "active",
11284
+ done: "done",
11285
+ other: void 0
11286
+ };
11287
+ /**
11288
+ * Puts migrated issues on a board of the target: finds the open board by name or makes it from the template, then adds
11289
+ * each issue with the status and priority of its record. Nothing is written on a dry run, which only says whether the
11290
+ * board exists. A second run adds nothing twice and sets no value the item already has (`Projects.addItems`).
11291
+ */
11292
+ async function placeOnBoard(input) {
11293
+ const { projects, owner, name, template } = input;
11294
+ let board = await projects.find(owner, name);
11295
+ const created = !board;
11296
+ if (input.dryRun) return {
11297
+ board,
11298
+ created,
11299
+ items: []
11300
+ };
11301
+ board ??= await projects.create(owner, name, template);
11302
+ const byKey = new Map(input.records.map((r) => [r.key, r]));
11303
+ const placed = input.results.flatMap((result) => {
11304
+ if (!result.key) return [];
11305
+ const record = byKey.get(result.source);
11306
+ const category = record ? BOARD_CATEGORY[record.statusCategory] : void 0;
11307
+ const item = {
11308
+ key: result.key,
11309
+ ...record?.status ? { status: record.status } : {},
11310
+ ...category ? { category } : {},
11311
+ ...record?.priority ? { priority: record.priority } : {}
11312
+ };
11313
+ return [{
11314
+ source: result.source,
11315
+ item
11316
+ }];
11317
+ });
11318
+ const added = await projects.addItems(owner, board, placed.map((p) => p.item), template);
11319
+ return {
11320
+ board,
11321
+ created,
11322
+ items: placed.map((p, i) => ({
11323
+ source: p.source,
11324
+ key: p.item.key,
11325
+ added: added[i].added,
11326
+ dropped: added[i].dropped
11327
+ }))
11328
+ };
11329
+ }
11330
+ // src/commands/migrate/print-board/print-board.ts
11331
+ /** Says what became of the board a project migration put its issues on, in the rows the rest of `migrate` prints. */
11332
+ function printBoard(input) {
11333
+ const { print, name, template, placement, dryRun } = input;
11334
+ const { board, created, items } = placement;
11335
+ if (dryRun) {
11336
+ const state = created ? `would create from template ${template}` : "exists; would add the issues to it";
11337
+ print(statusRow("skip", ["migrate", `board "${name}": ${state}`]));
11338
+ return;
11339
+ }
11340
+ const added = items.filter((i) => i.added).length;
11341
+ print(statusRow("ok", ["migrate", `board "${name}": ${created ? "created" : "found"}, added ${added}, already there ${items.length - added} (${board?.url})`]));
11342
+ }
11343
+ /**
11344
+ * Settles the owner and the template for the board `migrate project` puts issues on. The owner and the template
11345
+ * directory come from `providers.projects` when the config sets them, the org otherwise; the template is a built-in or
11346
+ * one of the repo's own files, by name.
11347
+ */
11348
+ async function resolveBoardTarget(input) {
11349
+ const own = input.loaded.resolved.providers.projects;
11350
+ const parsed = resolveProjectOptions(own?.cardinality === "single" ? own.tuple.options : {}, input.fallbackOwner);
11351
+ if (!parsed.ok) return {
11352
+ ok: false,
11353
+ reason: `providers.projects: ${parsed.problems.join("; ")}`
11354
+ };
11355
+ const { templates } = await loadTemplates(parsed.options.templatesDir, input.io ?? createFsTemplatesIo(input.repoRoot));
11356
+ const wanted = input.template ?? "roadmap";
11357
+ const template = templates[wanted];
11358
+ if (!template) return {
11359
+ ok: false,
11360
+ reason: `no board template "${wanted}"; available: ${Object.keys(templates).sort().join(", ")}`
11361
+ };
11362
+ return {
11363
+ ok: true,
11364
+ owner: parsed.options.owner,
11365
+ template
11227
11366
  };
11228
11367
  }
11229
11368
  // src/commands/migrate/tally-dropped/tally-dropped.ts
@@ -11272,11 +11411,30 @@ async function runMigrate(input) {
11272
11411
  context: input.context,
11273
11412
  endpoint: to,
11274
11413
  capabilities: ["issues"],
11414
+ ...project ? { optional: ["projects"] } : {},
11275
11415
  makeLoader: input.makeLoader
11276
11416
  });
11277
11417
  if (!target.ok) return stop("fail", `target: ${target.reason}`);
11278
11418
  const importer = target.issues;
11279
11419
  if (!importer?.import) return stop("skip", `the \`${target.provider}\` provider cannot import issues`);
11420
+ const projectScope = input.scope.kind === "project" ? input.scope : void 0;
11421
+ let plan;
11422
+ if (projectScope && target.projects?.addItems) {
11423
+ const resolved = await resolveBoardTarget({
11424
+ loaded: input.loaded,
11425
+ fallbackOwner: projectScope.owner,
11426
+ repoRoot: input.context.repoRoot,
11427
+ template: input.template,
11428
+ io: input.templatesIo
11429
+ });
11430
+ if (!resolved.ok) return stop("fail", resolved.reason);
11431
+ plan = {
11432
+ projects: target.projects,
11433
+ owner: resolved.owner,
11434
+ name: projectScope.name,
11435
+ template: resolved.template
11436
+ };
11437
+ }
11280
11438
  const collected = await collectRecords({
11281
11439
  source,
11282
11440
  scope: input.scope,
@@ -11287,7 +11445,7 @@ async function runMigrate(input) {
11287
11445
  for (const note of notes) print(statusRow("skip", ["migrate", note]));
11288
11446
  if (records.length === 0) return stop("skip", "nothing to migrate");
11289
11447
  const dryRun = Boolean(input.context.dryRun);
11290
- const milestone = input.milestone ?? (input.scope.kind === "project" ? input.scope.name : void 0);
11448
+ const milestone = input.milestone ?? (projectScope && !plan ? projectScope.name : void 0);
11291
11449
  const where = `${source.provider} to ${target.provider}`;
11292
11450
  if (!dryRun && !input.yes) {
11293
11451
  if (!(input.interactive ?? Boolean(process.stdin.isTTY))) throw new NonInteractiveError(`\`migrate\` creates issues on ${target.provider}; pass --yes to run it without asking`);
@@ -11310,6 +11468,24 @@ async function runMigrate(input) {
11310
11468
  }
11311
11469
  const created = results.filter((r) => r.created).length;
11312
11470
  print(statusRow(dryRun ? "skip" : "ok", ["migrate", `${where}: ${dryRun ? "dry run, nothing written; would create" : "created"} ${created}, skipped ${results.length - created}`]));
11471
+ let placement;
11472
+ if (plan) {
11473
+ placement = await placeOnBoard({
11474
+ ...plan,
11475
+ records,
11476
+ results,
11477
+ dryRun
11478
+ });
11479
+ printBoard({
11480
+ print,
11481
+ name: plan.name,
11482
+ template: plan.template.name,
11483
+ placement,
11484
+ dryRun
11485
+ });
11486
+ const bySource = new Map(results.map((r) => [r.source, r]));
11487
+ for (const item of placement.items) bySource.get(item.source).dropped.push(...item.dropped);
11488
+ }
11313
11489
  const notCarried = tallyDropped(results);
11314
11490
  if (notCarried.length > 0) {
11315
11491
  print(" not carried across:");
@@ -11318,7 +11494,8 @@ async function runMigrate(input) {
11318
11494
  return {
11319
11495
  status: "ok",
11320
11496
  results,
11321
- notCarried
11497
+ notCarried,
11498
+ ...placement ? { board: placement } : {}
11322
11499
  };
11323
11500
  } catch (err) {
11324
11501
  return stop("fail", `${describeError(err)} (a second run continues where this stopped)`);
@@ -11345,6 +11522,7 @@ async function handleMigrate(argv, scope) {
11345
11522
  scope: scope(org ?? ""),
11346
11523
  ...argv.openOnly ? { openOnly: true } : {},
11347
11524
  ...argv.milestone ? { milestone: argv.milestone } : {},
11525
+ ...argv.template ? { template: argv.template } : {},
11348
11526
  ...argv.yes ? { yes: true } : {}
11349
11527
  })).status === "fail") process.exitCode = 1;
11350
11528
  }
@@ -11412,11 +11590,14 @@ const migrateIssuesCommand = {
11412
11590
  // src/commands/migrate/migrate-project/migrate-project.command.ts
11413
11591
  const migrateProjectCommand = {
11414
11592
  command: "project <name>",
11415
- describe: "Move a board's issues to another tracker, with the board's status and priority; they land in a project of the same name",
11593
+ describe: "Move a board's issues to another tracker, with the board's status and priority; they land on a board of the same name (GitHub) or in a project of that name (Linear)",
11416
11594
  builder: (y) => migrateOptions(y).positional("name", {
11417
11595
  type: "string",
11418
11596
  demandOption: true,
11419
11597
  describe: "The board in the source tracker, by name"
11598
+ }).option("template", {
11599
+ type: "string",
11600
+ describe: "Board template to make a missing board from on a tracker with boards (GitHub); default roadmap"
11420
11601
  }),
11421
11602
  handler: (argv) => handleMigrate(argv, (owner) => ({
11422
11603
  kind: "project",
@@ -16399,7 +16580,7 @@ function checkGenerated({ files, again, read, workflows }) {
16399
16580
  return problems;
16400
16581
  }
16401
16582
  // ../../.holocron/org.md
16402
- var org_default = "<!-- editorconfig-checker-disable-file -->\n\n# theholocron — agent operating contract\n\nOrg-level agent conventions for all `theholocron` repositories. The canonical\ncopy is `.holocron/org.md` in `theholocron/holocron`. `holocron repo sync` writes\nit into each repo's `AGENTS.md` between generated markers, so no repo needs a\nsibling checkout to read it; holocron itself imports it with `@.holocron/org.md`.\nEdit it in holocron, then run `holocron repo sync`.\n\n## Repo map\n\nEach concern lives in exactly one repo:\n\n| Concern | Repo |\n| ----------------------------------------------------------------- | ----------------------------------------- |\n| Shareable tool config (ESLint, Prettier, TSConfig, Vitest, …) | `theholocron/holocron` (`configs/`) |\n| HTTP clients and API wrappers | `theholocron/holocron` (`clients/`) |\n| Infrastructure automation, CI orchestration, repo lifecycle | `theholocron/holocron` |\n| Org-level CI workflows, composite actions, community health files | `theholocron/.github` |\n| Internal member docs and private org config | `theholocron/.github-private` (this repo) |\n| Shared agent skills registry | `theholocron/holocron` (`skills/`) |\n\nIf you find yourself copy-pasting a tool config across repos, it belongs in\nthe `configs/` folder of `theholocron/holocron`. If you find yourself writing a new\nautomation command, it belongs in `holocron` too. Generic helpers (`utils/`) and\nobservability (`observability/`) live in that monorepo as well.\n\n### `holocron.config` format\n\n- Repos **with** a `package.json` → `holocron.config.ts` with `defineConfig`\n from `@theholocron/cli`. The CLI must be resolvable at runtime for the TS\n format to work.\n- Repos **without** a `package.json` (e.g. `.github`, `.github-private`) →\n `holocron.config.json`.\n\n## Workflow\n\n- **Always open a PR — never push directly to the default branch.** Even for\n small fixes: create a branch, push it, open a PR. This lets CI run, keeps\n history reviewable, and respects branch protection. The only exception is\n bootstrapping a brand-new repo before protection is set up.\n- **Conventional Commits.** `feat:` / `fix:` / `chore:` / `docs:` / `ci:` /\n `test:` / `refactor:` / `perf:` — semantic-release uses these for versioning\n and changelogs. Repos without a release step use the subset relevant to them.\n- **Always `git commit -s`** (DCO). The `Signed-off-by:` trailer is required\n on every commit. `-s` generates it automatically from `git config user.name`\n and `user.email`.\n- **Always rebase, never merge `main`.** Use `git rebase origin/main` to keep a\n branch current. `git merge main` creates an unsigned merge commit and drags bot\n commits into the PR history — both trigger DCO check failures.\n- **No Claude attribution** in commits, PRs, issues, or docs. No\n `Co-Authored-By` trailer. The author is the user.\n- **One PR = one focused change.** Squash-merge; the PR title becomes the\n squashed commit subject that semantic-release reads.\n- **File issues for non-trivial work** and reference them in commits/PRs\n (`Closes #N` / `Refs #N`). Skip for typo fixes.\n- **Spec process: Issue before spec.** Before writing a spec file, file a GitHub\n issue first. The issue is the durable tracking artifact. The spec's frontmatter\n `issue:` field must reference it. Order: Issue → Spec → PR → Review → merge.\n\n## Before starting any coding task\n\n1. Verify you are on a feature branch, not `main`. If on `main`, create a branch\n first. Never commit directly to `main`. If on an existing feature branch, run\n `git fetch origin && git rebase origin/main` to ensure it has the latest from\n `main` — never start work on a stale branch.\n2. Any PR that adds new behavior must include tests and documentation in the same\n PR. Do not open docs-only or test-only follow-up PRs — tests and docs ship with\n the feature. This applies to new packages, capabilities, commands, APIs, and\n any observable behavior change.\n3. If adding a new client or plugin package, update the docs-theme registry in\n the same PR or a cleanly scoped immediate follow-up.\n4. One PR per logical change. Do not bundle unrelated fixes with a feature.\n\n## After completing any coding task\n\n1. Confirm you are still on the intended feature branch.\n2. Confirm all checklist items in any invoked skill are complete.\n3. Confirm CI is green before requesting review.\n\n## CI workflows\n\nAll reusable workflow implementations and composite actions **live as source in\n`theholocron/holocron` — `packages/astromech/src/templates/reusable/`** and are\ngenerated + pushed to `theholocron/.github` by `holocron sync github`.\n**`theholocron/.github` and `.github-private` are pure sync targets** — never\nhand-edit their `.github/workflows/*`, `.github/actions/*` or\n`workflow-templates/*`; edit the source in `holocron` and merge.\n\nEvery other repo (`configs`, `clients`, `holocron`, `.github-private`) gets\n**thin callers** — lightweight `.github/workflows/` files that delegate to\n`.github` via `uses: theholocron/.github/.github/workflows/<name>.yml@main` and\n`secrets: inherit`. Thin callers are generated from the manifest by\n`astromech.thinCallers()` (`holocron repo sync` / `holocron repo setup`).\n\n### Sync\n\nThe `sync-workflow-templates` workflow in `theholocron/holocron` keeps thin\ncallers up to date. It runs automatically on push to `main` when\n`packages/cli/src/templates/**` or `packages/astromech/src/templates/**` change.\nChanges to other parts of the sync machinery (e.g. `sync-github.ts`) require a\nmanual dispatch:\n\n```sh\ngh workflow run sync-workflow-templates.yml --repo theholocron/holocron --ref main\n```\n\n### Per-repo task list\n\nEach secondary repo controls which tasks (and their CI workflows) it\nreceives — and can supply per-task `with:` overrides — via the `tasks`\narray in its `holocron.config.ts` (or `holocron.config.json`).\n`@theholocron/astromech` reads it as the single source for `holocron run`\n/ `holocron run ci` / the generated workflow thin callers:\n\n```typescript\ntasks: [\"lint\", { name: \"release\", with: { \"run-build\": false } }];\n```\n\nOnly add a task if the corresponding capability exists in the repo:\n\n| Task | Requires |\n| ------------- | ------------------------------------------------- |\n| `test` | vitest suite with `--coverage` |\n| `typecheck` | TypeScript (`pnpm typecheck` script) |\n| `audit` | a bundle build step (`pnpm build` script) |\n| `sync-github` | `packages/cli/src/templates/**` — `holocron` only |\n\n### Release workflow — npm prefix and registry-url\n\n**Never run `npm config set prefix <path>` in a release workflow.** It writes\n`prefix=<path>` to `~/.npmrc`, which pnpm reads for npm configuration. With a\nnon-default prefix set, pnpm cannot locate the registry auth it needs to perform\nthe GitHub OIDC token exchange and fails with `ENEEDAUTH` — even when Trusted\nPublishers are correctly configured on npmjs.com.\n\nNode.js from `hostedtoolcache` already provides a user-writable npm prefix on\nPATH. Run `npm install -g <pkg>` directly.\n\n**Never cache `~/.npm-global` or any npm global directory in release workflows.**\nA stale cache restores old auth config that poisons the OIDC exchange.\n\n**Never set `registry-url` in the shared `setup-node` composite action.** It\ncauses `actions/setup-node` to write `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}`\nto a temp `.npmrc` and set `NPM_CONFIG_USERCONFIG` pointing at it. pnpm then\nreads that file, fails env-var substitution when the token is empty, and loses\nauth entirely.\n\nThe reference implementation is `theholocron/holocron`'s own release workflow —\nno prefix step, no cache, no `registry-url`.\n\n### Discarding a bad sync PR\n\n**Delete the branch, don't only close the PR.** A closed-but-existing branch\nblocks future PR creation — GitHub returns 422 \"A pull request already exists\"\nand the sync silently skips opening a new one.\n\n```sh\ngh pr close <n> --repo <owner>/<repo> --delete-branch\n```\n\n## Code standards\n\n### Package manager\n\n**pnpm only.** Never use `npm` or `yarn`. Run workspace-wide tasks through\nTurbo (`pnpm test`, `pnpm build`, etc.); run single-package tasks with\n`pnpm --filter <name> <script>`.\n\n### TypeScript\n\n**No `any`.** Use `unknown` for values of genuinely unknown shape and narrow\nwith type guards. Use generics instead of `any` in function signatures.\n`as never` and `as unknown as T` are acceptable for internal casts where the\ntype system can't follow; `any` is not.\n\n### Node.js version\n\n`engines.node` must be set in every `package.json`. To update the Node.js\nversion across a repo run `holocron repo upgrade node <to>` from any repo that has\nthe CLI installed — it patches `engines.node`, `@types/node`, `.nvmrc`,\n`.node-version`, and `.github/workflows/*.yml` automatically.\n\n### `.alexrc.json`\n\n**Generated by `holocron repo setup` — do not edit manually.** The canonical\nallow-list lives in `ALEX_CONFIG` in\n`theholocron/holocron · packages/cli/src/inclusive-language/config.ts`. To\nallow a new term across all repos: edit that constant, open a PR in\n`holocron`, merge, then re-run `holocron repo setup` in each consuming repo.\n\n### Running `holocron repo setup`\n\nInstall `@theholocron/cli` and `@theholocron/holocron-plugin-github` under\n`catalogs.holocron` in `pnpm-workspace.yaml`:\n\n```yaml\ncatalogs:\n holocron:\n \"@theholocron/cli\": <version>\n \"@theholocron/holocron-plugin-github\": <version>\n```\n\nThen run:\n\n```sh\nGITHUB_TOKEN=$(gh auth token) \\\nHOLOCRON_ORG_TOKEN=$(security find-generic-password -s \"com.theholocron.cli\" -a \"github.org\" -w) \\\npnpm exec holocron repo setup --token $(security find-generic-password -s \"com.theholocron.cli\" -a \"github.admin\" -w)\n```\n\nAll tokens are stored in the macOS keychain under service `com.theholocron.cli`. See `docs/tokens.md` in the `holocron` repo for the full token matrix and required scopes.\n\nBump both catalog entries together when upgrading — they publish in lockstep.\n\n### README structure\n\nEvery repo README follows this layout. Use `holocron repo sync readme` to regenerate the Installation + Usage block automatically.\n\n```markdown\n# Package Name\n\n<!-- holocron:description -->\n\nOne-line description (synced from holocron.config.ts description field).\n<!-- /holocron:description -->\n\n<!-- holocron:installation -->\n\n## Installation\n\n...generated from package.json bin / exports...\n\n## Usage\n\n...generated from package.json bin / exports...\n<!-- /holocron:installation -->\n\n## What's Included ← template repos only; omit for libraries\n\n...feature table...\n\n## Development\n\npnpm scripts table or code block\n\n## Releases\n\nAutomated via semantic-release. Link to CHANGELOG.md.\n\n## Documentation\n\nLink to docs site.\n```\n\n**Rules:**\n\n- Never write \"Getting Started\" — use separate \"Installation\" and \"Usage\" headings.\n- The `<!-- holocron:description -->` and `<!-- holocron:installation -->` marker blocks must stay in sync with the config/package; run `holocron repo sync readme` after changing `description` in `holocron.config.ts` or `bin` in `package.json`.\n- The \"What's Included\" section belongs only in template repos (cli-template, node-template, react-template, etc.) where it describes what the template ships. Library and app repos omit it.\n\n---\n\n## This repo (`.github-private`)\n\n> **Local path:** `~/Code/theholocron/github-private/`\n> **GitHub repo:** `theholocron/.github-private`\n\nInternal member documentation and private org-level configuration for the\n`theholocron` org. Content here is only visible to org members.\n\nConventional Commit types used here: `docs:` for content changes, `ci:` for\nworkflow changes, `chore:` for maintenance.\n\nNo test suite (documentation repo). `pnpm lint` runs `yamllint` on workflow\nfiles. Branch protection on `main` requires DCO and passing CI checks.\n";
16583
+ var org_default = "<!-- editorconfig-checker-disable-file -->\n\n# theholocron — agent operating contract\n\nOrg-level agent conventions for all `theholocron` repositories. The canonical\ncopy is `.holocron/org.md` in `theholocron/holocron`. `holocron repo sync` writes\nit into each repo's `AGENTS.md` between generated markers, so no repo needs a\nsibling checkout to read it; holocron itself imports it with `@.holocron/org.md`.\nEdit it in holocron, then run `holocron repo sync`.\n\n## Repo map\n\nEach concern lives in exactly one repo:\n\n| Concern | Repo |\n| ----------------------------------------------------------------- | ----------------------------------------- |\n| Shareable tool config (ESLint, Prettier, TSConfig, Vitest, …) | `theholocron/holocron` (`configs/`) |\n| HTTP clients and API wrappers | `theholocron/holocron` (`clients/`) |\n| Infrastructure automation, CI orchestration, repo lifecycle | `theholocron/holocron` |\n| Org-level CI workflows, composite actions, community health files | `theholocron/.github` |\n| Internal member docs and private org config | `theholocron/.github-private` (this repo) |\n| Shared agent skills registry | `theholocron/holocron` (`skills/`) |\n\nIf you find yourself copy-pasting a tool config across repos, it belongs in\nthe `configs/` folder of `theholocron/holocron`. If you find yourself writing a new\nautomation command, it belongs in `holocron` too. Generic helpers (`utils/`) and\nobservability (`observability/`) live in that monorepo as well.\n\n### `holocron.config` format\n\n- Repos **with** a `package.json` → `holocron.config.ts` with `defineConfig`\n from `@theholocron/cli`. The CLI must be resolvable at runtime for the TS\n format to work.\n- Repos **without** a `package.json` (e.g. `.github`, `.github-private`) →\n `holocron.config.json`.\n\n## Workflow\n\n- **Always open a PR — never push directly to the default branch.** Even for\n small fixes: create a branch, push it, open a PR. This lets CI run, keeps\n history reviewable, and respects branch protection. The only exception is\n bootstrapping a brand-new repo before protection is set up.\n- **Conventional Commits.** `feat:` / `fix:` / `chore:` / `docs:` / `ci:` /\n `test:` / `refactor:` / `perf:` — semantic-release uses these for versioning\n and changelogs. Repos without a release step use the subset relevant to them.\n- **Always `git commit -s`** (DCO). The `Signed-off-by:` trailer is required\n on every commit. `-s` generates it automatically from `git config user.name`\n and `user.email`.\n- **Always rebase, never merge `main`.** Use `git rebase origin/main` to keep a\n branch current. `git merge main` creates an unsigned merge commit and drags bot\n commits into the PR history — both trigger DCO check failures.\n- **No Claude attribution** in commits, PRs, issues, or docs. No\n `Co-Authored-By` trailer. The author is the user.\n- **One PR = one focused change.** Squash-merge; the PR title becomes the\n squashed commit subject that semantic-release reads.\n- **File issues for non-trivial work** and reference them in commits/PRs\n (`Closes #N` / `Refs #N`). Skip for typo fixes.\n- **Spec process: Issue before spec.** Before writing a spec file, file an issue\n first, in the tracker the config's `issues` provider names (GitHub when the\n config sets no `issues` provider). The issue is the durable tracking artifact.\n The spec's frontmatter `issue:` field must reference it. Order: Issue → Spec →\n PR → Review → merge.\n- **Reference the issue in that tracker's syntax** in commits and the PR: `Closes #N`\n / `Refs #N` for GitHub, the issue key (`Closes ENG-42` / `Refs ENG-42`) for Linear.\n\n## Before starting any coding task\n\n1. Verify you are on a feature branch, not `main`. If on `main`, create a branch\n first. Never commit directly to `main`. If on an existing feature branch, run\n `git fetch origin && git rebase origin/main` to ensure it has the latest from\n `main` — never start work on a stale branch.\n2. Any PR that adds new behavior must include tests and documentation in the same\n PR. Do not open docs-only or test-only follow-up PRs — tests and docs ship with\n the feature. This applies to new packages, capabilities, commands, APIs, and\n any observable behavior change.\n3. If adding a new client or plugin package, update the docs-theme registry in\n the same PR or a cleanly scoped immediate follow-up.\n4. One PR per logical change. Do not bundle unrelated fixes with a feature.\n\n## After completing any coding task\n\n1. Confirm you are still on the intended feature branch.\n2. Confirm all checklist items in any invoked skill are complete.\n3. Confirm CI is green before requesting review.\n\n## CI workflows\n\nAll reusable workflow implementations and composite actions **live as source in\n`theholocron/holocron` — `packages/astromech/src/templates/reusable/`** and are\ngenerated + pushed to `theholocron/.github` by `holocron sync github`.\n**`theholocron/.github` and `.github-private` are pure sync targets** — never\nhand-edit their `.github/workflows/*`, `.github/actions/*` or\n`workflow-templates/*`; edit the source in `holocron` and merge.\n\nEvery other repo (`configs`, `clients`, `holocron`, `.github-private`) gets\n**thin callers** — lightweight `.github/workflows/` files that delegate to\n`.github` via `uses: theholocron/.github/.github/workflows/<name>.yml@main` and\n`secrets: inherit`. Thin callers are generated from the manifest by\n`astromech.thinCallers()` (`holocron repo sync` / `holocron repo setup`).\n\n### Sync\n\nThe `sync-workflow-templates` workflow in `theholocron/holocron` keeps thin\ncallers up to date. It runs automatically on push to `main` when\n`packages/cli/src/templates/**` or `packages/astromech/src/templates/**` change.\nChanges to other parts of the sync machinery (e.g. `sync-github.ts`) require a\nmanual dispatch:\n\n```sh\ngh workflow run sync-workflow-templates.yml --repo theholocron/holocron --ref main\n```\n\n### Per-repo task list\n\nEach secondary repo controls which tasks (and their CI workflows) it\nreceives — and can supply per-task `with:` overrides — via the `tasks`\narray in its `holocron.config.ts` (or `holocron.config.json`).\n`@theholocron/astromech` reads it as the single source for `holocron run`\n/ `holocron run ci` / the generated workflow thin callers:\n\n```typescript\ntasks: [\"lint\", { name: \"release\", with: { \"run-build\": false } }];\n```\n\nOnly add a task if the corresponding capability exists in the repo:\n\n| Task | Requires |\n| ------------- | ------------------------------------------------- |\n| `test` | vitest suite with `--coverage` |\n| `typecheck` | TypeScript (`pnpm typecheck` script) |\n| `audit` | a bundle build step (`pnpm build` script) |\n| `sync-github` | `packages/cli/src/templates/**` — `holocron` only |\n\n### Release workflow — npm prefix and registry-url\n\n**Never run `npm config set prefix <path>` in a release workflow.** It writes\n`prefix=<path>` to `~/.npmrc`, which pnpm reads for npm configuration. With a\nnon-default prefix set, pnpm cannot locate the registry auth it needs to perform\nthe GitHub OIDC token exchange and fails with `ENEEDAUTH` — even when Trusted\nPublishers are correctly configured on npmjs.com.\n\nNode.js from `hostedtoolcache` already provides a user-writable npm prefix on\nPATH. Run `npm install -g <pkg>` directly.\n\n**Never cache `~/.npm-global` or any npm global directory in release workflows.**\nA stale cache restores old auth config that poisons the OIDC exchange.\n\n**Never set `registry-url` in the shared `setup-node` composite action.** It\ncauses `actions/setup-node` to write `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}`\nto a temp `.npmrc` and set `NPM_CONFIG_USERCONFIG` pointing at it. pnpm then\nreads that file, fails env-var substitution when the token is empty, and loses\nauth entirely.\n\nThe reference implementation is `theholocron/holocron`'s own release workflow —\nno prefix step, no cache, no `registry-url`.\n\n### Discarding a bad sync PR\n\n**Delete the branch, don't only close the PR.** A closed-but-existing branch\nblocks future PR creation — GitHub returns 422 \"A pull request already exists\"\nand the sync silently skips opening a new one.\n\n```sh\ngh pr close <n> --repo <owner>/<repo> --delete-branch\n```\n\n## Code standards\n\n### Package manager\n\n**pnpm only.** Never use `npm` or `yarn`. Run workspace-wide tasks through\nTurbo (`pnpm test`, `pnpm build`, etc.); run single-package tasks with\n`pnpm --filter <name> <script>`.\n\n### TypeScript\n\n**No `any`.** Use `unknown` for values of genuinely unknown shape and narrow\nwith type guards. Use generics instead of `any` in function signatures.\n`as never` and `as unknown as T` are acceptable for internal casts where the\ntype system can't follow; `any` is not.\n\n### Node.js version\n\n`engines.node` must be set in every `package.json`. To update the Node.js\nversion across a repo run `holocron repo upgrade node <to>` from any repo that has\nthe CLI installed — it patches `engines.node`, `@types/node`, `.nvmrc`,\n`.node-version`, and `.github/workflows/*.yml` automatically.\n\n### `.alexrc.json`\n\n**Generated by `holocron repo setup` — do not edit manually.** The canonical\nallow-list lives in `ALEX_CONFIG` in\n`theholocron/holocron · packages/cli/src/inclusive-language/config.ts`. To\nallow a new term across all repos: edit that constant, open a PR in\n`holocron`, merge, then re-run `holocron repo setup` in each consuming repo.\n\n### Running `holocron repo setup`\n\nInstall `@theholocron/cli` and `@theholocron/holocron-plugin-github` under\n`catalogs.holocron` in `pnpm-workspace.yaml`:\n\n```yaml\ncatalogs:\n holocron:\n \"@theholocron/cli\": <version>\n \"@theholocron/holocron-plugin-github\": <version>\n```\n\nThen run:\n\n```sh\nGITHUB_TOKEN=$(gh auth token) \\\nHOLOCRON_ORG_TOKEN=$(security find-generic-password -s \"com.theholocron.cli\" -a \"github.org\" -w) \\\npnpm exec holocron repo setup --token $(security find-generic-password -s \"com.theholocron.cli\" -a \"github.admin\" -w)\n```\n\nAll tokens are stored in the macOS keychain under service `com.theholocron.cli`. See `docs/tokens.md` in the `holocron` repo for the full token matrix and required scopes.\n\nBump both catalog entries together when upgrading — they publish in lockstep.\n\n### README structure\n\nEvery repo README follows this layout. Use `holocron repo sync readme` to regenerate the Installation + Usage block automatically.\n\n```markdown\n# Package Name\n\n<!-- holocron:description -->\n\nOne-line description (synced from holocron.config.ts description field).\n<!-- /holocron:description -->\n\n<!-- holocron:installation -->\n\n## Installation\n\n...generated from package.json bin / exports...\n\n## Usage\n\n...generated from package.json bin / exports...\n<!-- /holocron:installation -->\n\n## What's Included ← template repos only; omit for libraries\n\n...feature table...\n\n## Development\n\npnpm scripts table or code block\n\n## Releases\n\nAutomated via semantic-release. Link to CHANGELOG.md.\n\n## Documentation\n\nLink to docs site.\n```\n\n**Rules:**\n\n- Never write \"Getting Started\" — use separate \"Installation\" and \"Usage\" headings.\n- The `<!-- holocron:description -->` and `<!-- holocron:installation -->` marker blocks must stay in sync with the config/package; run `holocron repo sync readme` after changing `description` in `holocron.config.ts` or `bin` in `package.json`.\n- The \"What's Included\" section belongs only in template repos (cli-template, node-template, react-template, etc.) where it describes what the template ships. Library and app repos omit it.\n\n---\n\n## This repo (`.github-private`)\n\n> **Local path:** `~/Code/theholocron/github-private/`\n> **GitHub repo:** `theholocron/.github-private`\n\nInternal member documentation and private org-level configuration for the\n`theholocron` org. Content here is only visible to org members.\n\nConventional Commit types used here: `docs:` for content changes, `ci:` for\nworkflow changes, `chore:` for maintenance.\n\nNo test suite (documentation repo). `pnpm lint` runs `yamllint` on workflow\nfiles. Branch protection on `main` requires DCO and passing CI checks.\n";
16403
16584
  // src/commands/repo-files/generate-agent-files.ts
16404
16585
  const ORG_BLOCK_BEGIN = "<!-- BEGIN holocron org agent instructions (generated by `holocron repo sync` from theholocron/holocron .agents/org.md; do not edit) -->";
16405
16586
  const ORG_BLOCK_END = "<!-- END holocron org agent instructions -->";
@@ -18455,6 +18636,14 @@ function listing(groups) {
18455
18636
  const width = Math.max(0, ...[...groups.keys()].map((name) => name.length));
18456
18637
  return [...groups].sort(([a], [b]) => a.localeCompare(b)).map(([name, actions]) => ` ${name.padEnd(width)} ${ACTIONS.filter((a) => actions[a]).join(", ")}`);
18457
18638
  }
18639
+ /** The options of the first config entry that names `provider`, whichever capability it sits under. */
18640
+ function configOptions(providers, provider) {
18641
+ for (const entry of Object.values(providers)) {
18642
+ const found = (entry?.cardinality === "many" ? entry.tuples : entry ? [entry.tuple] : []).find((tuple) => tuple.provider === provider);
18643
+ if (found) return found.options;
18644
+ }
18645
+ return {};
18646
+ }
18458
18647
  async function runProvider(input) {
18459
18648
  const print = input.print ?? ((line) => console.log(line));
18460
18649
  /* v8 ignore next -- the real loader is only built outside tests, which always inject one */
@@ -18462,6 +18651,7 @@ async function runProvider(input) {
18462
18651
  await loader.load();
18463
18652
  assertPluginsResolvable$1(loader, "provider");
18464
18653
  const groups = loader.providerActions();
18654
+ if (input.options && !input.provider) return fail(print, "`--with` needs a provider name", "e.g. `holocron provider linear doctor --with team=ENG`");
18465
18655
  if (!input.provider) {
18466
18656
  if (groups.size === 0) print(" no configured provider offers `setup` or `doctor`");
18467
18657
  else {
@@ -18473,7 +18663,19 @@ async function runProvider(input) {
18473
18663
  rows: []
18474
18664
  };
18475
18665
  }
18476
- const actions = groups.get(input.provider);
18666
+ let actions;
18667
+ if (input.options) {
18668
+ try {
18669
+ actions = await loader.loadProviderActions(input.provider, {
18670
+ ...configOptions(input.loaded.resolved.providers, input.provider),
18671
+ ...input.options
18672
+ });
18673
+ } catch (err) {
18674
+ if (err instanceof WorkspaceContextError) throw err;
18675
+ return fail(print, `\`${input.provider}\` did not load`, describeError(err));
18676
+ }
18677
+ if (!actions.setup && !actions.doctor) return fail(print, `\`${input.provider}\` offers neither \`setup\` nor \`doctor\``);
18678
+ } else actions = groups.get(input.provider);
18477
18679
  if (!actions) return fail(print, `no configured provider \`${input.provider}\` offers \`setup\` or \`doctor\``, groups.size > 0 ? `try: ${[...groups.keys()].sort().join(", ")}` : "none does");
18478
18680
  if (!input.action) {
18479
18681
  for (const line of listing(/* @__PURE__ */ new Map([[input.provider, actions]]))) print(line);
@@ -18534,6 +18736,48 @@ async function runProvider(input) {
18534
18736
  rows
18535
18737
  };
18536
18738
  }
18739
+ // src/commands/provider/read-with-options/read-with-options.ts
18740
+ /** A `--with` value that is `key=value` text rather than a file path. */
18741
+ const PAIR = /^[A-Za-z][\w-]*=/;
18742
+ const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
18743
+ /**
18744
+ * Reads the values of `--with` into one provider options object. Each value is either a `key=value` pair
18745
+ * (`team=ENG`, text) or the path of a file (`.json`, or `.ts`, `.js`, `.mjs`, `.cjs` with the options object as its
18746
+ * default export), relative to `cwd`. They are laid over each other in the order given, one key at a time, so a later
18747
+ * value wins and a nested object is replaced whole, not merged. Returns `undefined` when `--with` was not given at
18748
+ * all, which is not the same as `{}`: it is how the command knows the options come from the config alone.
18749
+ *
18750
+ * A missing or unreadable file, or one whose value is not an object, is a {@link ConfigError} naming the file.
18751
+ *
18752
+ * @param values - What `--with` was given, in order.
18753
+ * @param cwd - The directory a relative path is resolved against.
18754
+ */
18755
+ async function readWithOptions(values, cwd) {
18756
+ if (!values || values.length === 0) return void 0;
18757
+ let options = {};
18758
+ for (const value of values) {
18759
+ if (PAIR.test(value)) {
18760
+ options = {
18761
+ ...options,
18762
+ ...parseOptionPairs(value, "--with")
18763
+ };
18764
+ continue;
18765
+ }
18766
+ const filepath = resolve(cwd, value);
18767
+ let loaded;
18768
+ try {
18769
+ loaded = await loadConfigPath(filepath);
18770
+ } catch (err) {
18771
+ throw new ConfigError$1(`--with ${value}: ${describeError(err)}`);
18772
+ }
18773
+ if (!isObject(loaded)) throw new ConfigError$1(`--with ${value}: must hold an object of the provider's options`);
18774
+ options = {
18775
+ ...options,
18776
+ ...loaded
18777
+ };
18778
+ }
18779
+ return options;
18780
+ }
18537
18781
  // src/commands/provider/provider.command.ts
18538
18782
  const providerArgs = (y) => y.positional("provider", {
18539
18783
  type: "string",
@@ -18541,6 +18785,10 @@ const providerArgs = (y) => y.positional("provider", {
18541
18785
  }).positional("action", {
18542
18786
  type: "string",
18543
18787
  describe: "`setup` or `doctor` (omit to list the provider's)"
18788
+ }).option("with", {
18789
+ type: "string",
18790
+ array: true,
18791
+ describe: "The provider's options when the config does not name it (or to override its entry): a `key=value` pair, or a `.json`, `.ts` or `.js` file holding the options object; repeat to add more, a later one wins"
18544
18792
  }).option("yes", {
18545
18793
  type: "boolean",
18546
18794
  default: false,
@@ -18548,11 +18796,12 @@ const providerArgs = (y) => y.positional("provider", {
18548
18796
  });
18549
18797
  const providerCommand = {
18550
18798
  command: "provider [provider] [action]",
18551
- describe: "Set up or check what only one provider has, from its own block of holocron.config",
18799
+ describe: "Set up or check what only one provider has, from its block of holocron.config or --with",
18552
18800
  builder: providerArgs,
18553
18801
  handler: async (argv) => {
18554
18802
  const tokens = tokenContext$1(argv.token);
18555
18803
  if (!tokens) return;
18804
+ const options = await readWithOptions(argv.with, argv.cwd);
18556
18805
  const loaded = await loadConfig(argv.cwd);
18557
18806
  applyResolvedConfig(argv, loaded.resolved);
18558
18807
  if ((await runProvider({
@@ -18565,6 +18814,7 @@ const providerCommand = {
18565
18814
  },
18566
18815
  ...argv.provider ? { provider: argv.provider } : {},
18567
18816
  ...argv.action ? { action: argv.action } : {},
18817
+ ...options ? { options } : {},
18568
18818
  yes: argv.yes
18569
18819
  })).status === "fail") process.exitCode = 1;
18570
18820
  }