@theholocron/cli 5.0.0-alpha.371 → 5.0.0-alpha.373
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +24 -23
- package/dist/cli.mjs +338 -88
- package/dist/cli.mjs.map +1 -1
- package/dist/{config-system-513IhEuT.d.mts → config-system-CLq4YZd-.d.mts} +1 -1
- package/dist/{index-DXC-Eco9.d.mts → index-BAm3hE_V.d.mts} +28 -1
- package/dist/index.d.mts +3 -3
- package/dist/plugin/capabilities.d.mts +2 -2
- package/dist/presets.d.mts +1 -1
- package/package.json +15 -15
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())
|
|
1037
|
-
|
|
1038
|
-
|
|
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
|
-
|
|
2220
|
-
|
|
2221
|
-
|
|
2222
|
-
|
|
2223
|
-
|
|
2224
|
-
|
|
2225
|
-
|
|
2226
|
-
|
|
2227
|
-
|
|
2228
|
-
|
|
2229
|
-
|
|
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 ?? (
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
}
|