@theholocron/cli 5.0.0-alpha.339 → 5.0.0-alpha.340

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
@@ -220,6 +220,10 @@ const COMMAND_CONTEXTS = {
220
220
  "secrets set": "workspace",
221
221
  "secrets sync": "workspace",
222
222
  "tunnel up": "workspace",
223
+ "project list": "workspace",
224
+ "project create": "workspace",
225
+ "project close": "workspace",
226
+ "project setup": "workspace",
223
227
  dev: "workspace",
224
228
  "dev serve": "repo-aware",
225
229
  "notifications channel add": "workspace",
@@ -228,10 +232,13 @@ const COMMAND_CONTEXTS = {
228
232
  "notifications create-server": "workspace",
229
233
  "notifications sync-roles": "workspace",
230
234
  "specs sync": "workspace",
235
+ "project reconcile": "workspace",
231
236
  "doctor all": "workspace",
232
237
  "doctor notifications": "workspace",
233
238
  "doctor environments": "workspace",
234
239
  "doctor credentials": "workspace",
240
+ "doctor project": "workspace",
241
+ "project move": "workspace",
235
242
  "doctor dns": "workspace",
236
243
  "doctor repo": "workspace",
237
244
  "doctor secrets": "workspace",
@@ -898,6 +905,20 @@ const doctorNotificationsEntry = {
898
905
  }],
899
906
  supportsDryRun: false
900
907
  };
908
+ // src/commands/doctor-project/doctor-project.entry.ts
909
+ const doctorProjectEntry = {
910
+ name: "doctor project",
911
+ description: "Compare each declared project board with its template, and report items that need a status (read-only)",
912
+ positionals: [],
913
+ options: [{
914
+ key: "post",
915
+ flag: "--post",
916
+ type: "confirm",
917
+ default: false,
918
+ message: "Post the result to #alerts (the failures, or just the summary)?"
919
+ }],
920
+ supportsDryRun: false
921
+ };
901
922
  // src/commands/doctor-repo/doctor-repo.entry.ts
902
923
  const doctorRepoEntry = {
903
924
  name: "doctor repo",
@@ -1112,6 +1133,73 @@ const probeEntry = {
1112
1133
  positionals: [],
1113
1134
  opensMenu: true
1114
1135
  };
1136
+ // src/commands/project/move/move.entry.ts
1137
+ const projectMoveEntry = {
1138
+ name: "project move",
1139
+ description: "Move the open items of one board to another, with their status and priority; closed ones stay behind",
1140
+ positionals: [{
1141
+ key: "from",
1142
+ message: "Board to move the open items from:",
1143
+ type: "input"
1144
+ }, {
1145
+ key: "to",
1146
+ message: "Board to move them to:",
1147
+ type: "input"
1148
+ }],
1149
+ skipOptions: ["template", "yes"],
1150
+ supportsDryRun: true
1151
+ };
1152
+ // src/commands/project/project-close/project-close.entry.ts
1153
+ const projectCloseEntry = {
1154
+ name: "project close",
1155
+ description: "Close a board (reversible)",
1156
+ positionals: [{
1157
+ key: "board",
1158
+ message: "Board number or name:",
1159
+ type: "input"
1160
+ }],
1161
+ options: [{
1162
+ key: "yes",
1163
+ flag: "--yes",
1164
+ type: "confirm",
1165
+ message: "Close without asking?"
1166
+ }],
1167
+ supportsDryRun: true
1168
+ };
1169
+ // src/commands/project/project-create/project-create.entry.ts
1170
+ const projectCreateEntry = {
1171
+ name: "project create",
1172
+ description: "Make a board from a template",
1173
+ positionals: [],
1174
+ options: [{
1175
+ key: "title",
1176
+ flag: "--title",
1177
+ type: "input",
1178
+ message: "Board title (blank = the template's name):"
1179
+ }],
1180
+ supportsDryRun: true
1181
+ };
1182
+ // src/commands/project/project-list/project-list.entry.ts
1183
+ const projectListEntry = {
1184
+ name: "project list",
1185
+ description: "List the boards of the organization, with their number, name and state",
1186
+ positionals: []
1187
+ };
1188
+ // src/commands/project/project-setup/project-setup.entry.ts
1189
+ const projectSetupEntry = {
1190
+ name: "project setup",
1191
+ description: "Make each board providers.projects declares match its template, creating the ones that are missing",
1192
+ positionals: [],
1193
+ supportsDryRun: true
1194
+ };
1195
+ // src/commands/project/reconcile/reconcile.entry.ts
1196
+ const projectReconcileEntry = {
1197
+ name: "project reconcile",
1198
+ description: "Set item statuses where a rule says so: blocked, unblocked, closed (status only)",
1199
+ positionals: [],
1200
+ options: [],
1201
+ supportsDryRun: true
1202
+ };
1115
1203
  // src/commands/publish/publish.entry.ts
1116
1204
  const PUBLISH_TAG_OPTION = {
1117
1205
  key: "tag",
@@ -1181,6 +1269,8 @@ const COMMAND_REGISTRY = [
1181
1269
  doctorNotificationsEntry,
1182
1270
  doctorEnvironmentsEntry,
1183
1271
  doctorCredentialsEntry,
1272
+ doctorProjectEntry,
1273
+ projectMoveEntry,
1184
1274
  doctorDnsEntry,
1185
1275
  doctorRepoEntry,
1186
1276
  doctorSecretsEntry,
@@ -1440,7 +1530,12 @@ const COMMAND_REGISTRY = [
1440
1530
  }
1441
1531
  ],
1442
1532
  supportsDryRun: true
1443
- }
1533
+ },
1534
+ projectListEntry,
1535
+ projectCreateEntry,
1536
+ projectCloseEntry,
1537
+ projectSetupEntry,
1538
+ projectReconcileEntry
1444
1539
  ];
1445
1540
  /** Look up a {@link CommandEntry} by its full name — for Layer 3 call sites in `cli.ts`. */
1446
1541
  function getEntry(name) {
@@ -2900,12 +2995,12 @@ async function runDoctorTokens(input) {
2900
2995
  try {
2901
2996
  module = await importer(pkg);
2902
2997
  } catch (err) {
2903
- rows.push(row$4(pkg, "skip", `cannot load the plugin: ${errorMessage(err)}`));
2998
+ rows.push(row$6(pkg, "skip", `cannot load the plugin: ${errorMessage(err)}`));
2904
2999
  continue;
2905
3000
  }
2906
3001
  for (const token of module.tokens ?? []) rows.push(await checkToken(token, module, env, keyring, now()));
2907
3002
  }
2908
- if (rows.length === 0) rows.push(row$4("tokens", "skip", "no configured plugin lists the tokens it takes"));
3003
+ if (rows.length === 0) rows.push(row$6("tokens", "skip", "no configured plugin lists the tokens it takes"));
2909
3004
  printCheckRows(rows, print);
2910
3005
  const summary = summariseChecks(rows);
2911
3006
  printCheckSummary(summary, print);
@@ -2926,7 +3021,7 @@ function configuredPackages(input) {
2926
3021
  const packages = Object.values(input.loaded.resolved.providers).flatMap((entry) => entry.cardinality === "single" ? [entry.tuple.packageName] : entry.tuples.map((t) => t.packageName));
2927
3022
  return [...new Set(packages)];
2928
3023
  }
2929
- function row$4(id, status, detail) {
3024
+ function row$6(id, status, detail) {
2930
3025
  return {
2931
3026
  id,
2932
3027
  title: id,
@@ -2939,20 +3034,20 @@ async function checkToken(token, module, env, keyring, now) {
2939
3034
  const { keyringKey, envName, vendorEnvName } = token;
2940
3035
  const fromEnv = env.get(envName) ? envName : vendorEnvName && env.get(vendorEnvName) ? vendorEnvName : void 0;
2941
3036
  const value = fromEnv ? env.get(fromEnv) : keyring(keyringKey);
2942
- if (!value) return row$4(keyringKey, "skip", `not set (${vendorEnvName ? `${envName} / ${vendorEnvName}` : envName}, or \`holocron auth set ${keyringKey}\`)`);
2943
- if (!module.verifyToken || token.verifiable === false) return row$4(keyringKey, "skip", "set, but its plugin cannot verify it");
3037
+ if (!value) return row$6(keyringKey, "skip", `not set (${vendorEnvName ? `${envName} / ${vendorEnvName}` : envName}, or \`holocron auth set ${keyringKey}\`)`);
3038
+ if (!module.verifyToken || token.verifiable === false) return row$6(keyringKey, "skip", "set, but its plugin cannot verify it");
2944
3039
  const from = fromEnv ?? "keyring";
2945
3040
  try {
2946
3041
  const verified = await module.verifyToken(value);
2947
- if (!verified.ok) return row$4(keyringKey, "fail", `rejected (${from}): ${verified.message}`);
3042
+ if (!verified.ok) return row$6(keyringKey, "fail", `rejected (${from}): ${verified.message}`);
2948
3043
  const expiry = verified.expiresAt ? describeExpiry(verified.expiresAt, now) : void 0;
2949
- if (!expiry) return row$4(keyringKey, "ok", `${verified.subject} (${from})`);
3044
+ if (!expiry) return row$6(keyringKey, "ok", `${verified.subject} (${from})`);
2950
3045
  return expiry.soon ? {
2951
- ...row$4(keyringKey, "fail", `${verified.subject} (${from}), ${expiry.text}`),
3046
+ ...row$6(keyringKey, "fail", `${verified.subject} (${from}), ${expiry.text}`),
2952
3047
  problems: [`${expiry.text}: renew it`]
2953
- } : row$4(keyringKey, "ok", `${verified.subject} (${from}), ${expiry.text}`);
3048
+ } : row$6(keyringKey, "ok", `${verified.subject} (${from}), ${expiry.text}`);
2954
3049
  } catch (err) {
2955
- return row$4(keyringKey, "fail", `could not be verified (${from}): ${errorMessage(err)}`);
3050
+ return row$6(keyringKey, "fail", `could not be verified (${from}): ${errorMessage(err)}`);
2956
3051
  }
2957
3052
  }
2958
3053
  // src/commands/doctor-tokens/doctor-tokens.command.ts
@@ -3038,7 +3133,7 @@ async function finishCredentialsFile(input) {
3038
3133
  * printed to a screen or left in scrollback; to the clipboard when asked. A regular file as stdout (`> file`) is
3039
3134
  * refused, because it would leave plaintext tokens on disk without any of those protections.
3040
3135
  */
3041
- const COMMAND$4 = "auth export";
3136
+ const COMMAND$8 = "auth export";
3042
3137
  /** Plain code-unit order: the same on every machine, whatever its locale. The names it sorts are all different. */
3043
3138
  const compare$1 = (a, b) => a < b ? -1 : 1;
3044
3139
  /** The file the lines go to on a terminal when none is named. */
@@ -3053,7 +3148,7 @@ async function runAuthExport(input) {
3053
3148
  logger.warn({
3054
3149
  status: "fail",
3055
3150
  reason
3056
- }, COMMAND$4);
3151
+ }, COMMAND$8);
3057
3152
  return {
3058
3153
  status: "fail",
3059
3154
  exported: [],
@@ -3104,7 +3199,7 @@ async function runAuthExport(input) {
3104
3199
  });
3105
3200
  }
3106
3201
  }
3107
- if (packages.length > 0 && unavailable.length === packages.length) throw new WorkspaceContextError(COMMAND$4, unavailable);
3202
+ if (packages.length > 0 && unavailable.length === packages.length) throw new WorkspaceContextError(COMMAND$8, unavailable);
3108
3203
  const literals = /* @__PURE__ */ new Map();
3109
3204
  const placeholders = [];
3110
3205
  if (input.only?.length) {
@@ -3241,7 +3336,7 @@ async function runAuthExport(input) {
3241
3336
  unavailable: unavailable.length,
3242
3337
  status,
3243
3338
  destination
3244
- }, COMMAND$4);
3339
+ }, COMMAND$8);
3245
3340
  return {
3246
3341
  status,
3247
3342
  exported,
@@ -4601,7 +4696,7 @@ function runCloudflared(token, spawnImpl = spawn) {
4601
4696
  * hostname at it. Both are idempotent, so a second run changes nothing. With `run`, the connector is started in the
4602
4697
  * foreground with the token in its environment. The token is never printed.
4603
4698
  */
4604
- const COMMAND$3 = "tunnel up";
4699
+ const COMMAND$7 = "tunnel up";
4605
4700
  /** Why a provider is missing: its own load error when it failed to load, else how to configure it. */
4606
4701
  function missing(loader, key, hint) {
4607
4702
  const failure = loader.loadFailures().find((f) => f.key === key);
@@ -4626,7 +4721,7 @@ async function runTunnelUp(input) {
4626
4721
  logger[status === "ok" ? "info" : "warn"]({
4627
4722
  status,
4628
4723
  ...summary
4629
- }, COMMAND$3);
4724
+ }, COMMAND$7);
4630
4725
  return {
4631
4726
  status,
4632
4727
  summary,
@@ -4635,7 +4730,7 @@ async function runTunnelUp(input) {
4635
4730
  };
4636
4731
  const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
4637
4732
  await (0, ui_exports.withSpinner)("Loading plugins…", () => loader.load());
4638
- assertPluginsResolvable(loader, COMMAND$3);
4733
+ assertPluginsResolvable(loader, COMMAND$7);
4639
4734
  const dryRun = input.context.dryRun ?? false;
4640
4735
  print(ui_exports.style.header(`Holocron tunnel up — ${input.hostname}${dryRun ? " (dry-run)" : ""}`));
4641
4736
  print("");
@@ -4752,7 +4847,7 @@ const tunnelUpCommand = {
4752
4847
  }
4753
4848
  };
4754
4849
  // src/commands/dev/dev.ts
4755
- const COMMAND$2 = "dev";
4850
+ const COMMAND$6 = "dev";
4756
4851
  /** The environment the application is told it runs in, which its logger tags every line with. */
4757
4852
  const APP_ENVIRONMENT = "development";
4758
4853
  async function runDev(input) {
@@ -4774,7 +4869,7 @@ async function runDev(input) {
4774
4869
  logger[status === "ok" ? "info" : "warn"]({
4775
4870
  status,
4776
4871
  ...summary
4777
- }, COMMAND$2);
4872
+ }, COMMAND$6);
4778
4873
  return {
4779
4874
  status,
4780
4875
  summary,
@@ -4783,7 +4878,7 @@ async function runDev(input) {
4783
4878
  };
4784
4879
  const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
4785
4880
  await (0, ui_exports.withSpinner)("Loading plugins…", () => loader.load());
4786
- assertPluginsResolvable(loader, COMMAND$2);
4881
+ assertPluginsResolvable(loader, COMMAND$6);
4787
4882
  const dryRun = input.context.dryRun ?? false;
4788
4883
  const [program, ...args] = input.command;
4789
4884
  const shown = input.command.join(" ");
@@ -5231,7 +5326,7 @@ async function runDoctorCredentials(input) {
5231
5326
  };
5232
5327
  }
5233
5328
  /** A row for the provider as a whole, or for one of its variables when `name` is given. */
5234
- function row$3(provider, status, detail, name) {
5329
+ function row$5(provider, status, detail, name) {
5235
5330
  return name === void 0 ? {
5236
5331
  id: provider,
5237
5332
  title: provider,
@@ -5248,32 +5343,32 @@ function row$3(provider, status, detail, name) {
5248
5343
  }
5249
5344
  async function checkCredentials(input, loader) {
5250
5345
  const { resolved } = input.loaded;
5251
- if (!resolved.providers.credentials) return [row$3("credentials", "skip", "no `credentials` provider is configured")];
5252
- const rows = loader.loadFailures().filter((f) => f.key === "credentials").map((f) => row$3(f.provider, "fail", `failed to load: ${errorMessage(f.error)}`));
5346
+ if (!resolved.providers.credentials) return [row$5("credentials", "skip", "no `credentials` provider is configured")];
5347
+ const rows = loader.loadFailures().filter((f) => f.key === "credentials").map((f) => row$5(f.provider, "fail", `failed to load: ${errorMessage(f.error)}`));
5253
5348
  if (!loader.has("credentials")) return rows;
5254
5349
  const expected = await expectedTokens(input);
5255
5350
  const { tuples } = resolved.providers.credentials;
5256
5351
  for (const impl of loader.get("credentials")) {
5257
5352
  const tuple = tuples.find((t) => t.provider === impl.providerName);
5258
5353
  const environment = tuple && credentialsEnvironment(tuple, resolved);
5259
- rows.push(...environment ? await checkProvider(impl, environment, expected) : [row$3(impl.providerName, "skip", "no `environment` option and `credentials.environment` is not set")]);
5354
+ rows.push(...environment ? await checkProvider(impl, environment, expected) : [row$5(impl.providerName, "skip", "no `environment` option and `credentials.environment` is not set")]);
5260
5355
  }
5261
5356
  return rows;
5262
5357
  }
5263
5358
  async function checkProvider(impl, environment, expected) {
5264
5359
  const provider = impl.providerName;
5265
- if (!impl.inspect) return [row$3(provider, "skip", "cannot list the variables without reading their values")];
5266
- if (expected.length === 0) return [row$3(provider, "skip", "no configured plugin lists the tokens it takes")];
5360
+ if (!impl.inspect) return [row$5(provider, "skip", "cannot list the variables without reading their values")];
5361
+ if (expected.length === 0) return [row$5(provider, "skip", "no configured plugin lists the tokens it takes")];
5267
5362
  try {
5268
5363
  const found = await impl.inspect(environment);
5269
5364
  const held = new Set(found.names);
5270
5365
  const where = found.environment === environment ? `"${found.environment}"` : `"${found.environment}" (the config writes "${environment}")`;
5271
5366
  return expected.map(({ name, optional }) => {
5272
- if (held.has(name)) return row$3(provider, "ok", `present in ${where}`, name);
5273
- return optional ? row$3(provider, "skip", `optional, not set in ${where}`, name) : row$3(provider, "fail", `missing from ${where}`, name);
5367
+ if (held.has(name)) return row$5(provider, "ok", `present in ${where}`, name);
5368
+ return optional ? row$5(provider, "skip", `optional, not set in ${where}`, name) : row$5(provider, "fail", `missing from ${where}`, name);
5274
5369
  });
5275
5370
  } catch (err) {
5276
- return [row$3(provider, "fail", errorMessage(err))];
5371
+ return [row$5(provider, "fail", errorMessage(err))];
5277
5372
  }
5278
5373
  }
5279
5374
  /**
@@ -6103,7 +6198,7 @@ async function runDoctorDns(input) {
6103
6198
  });
6104
6199
  else if (!loader.has("dns")) {
6105
6200
  const why = whyMissing(loader, "dns", "no `dns` provider to check them with");
6106
- for (const zone of zones) rows.push(row$2(zone, "skip", why));
6201
+ for (const zone of zones) rows.push(row$4(zone, "skip", why));
6107
6202
  for (const { hostname } of domains) rows.push(domainRow(hostname, "skip", why));
6108
6203
  } else {
6109
6204
  const dns = loader.get("dns");
@@ -6125,7 +6220,7 @@ async function runDoctorDns(input) {
6125
6220
  ...status === "skip" ? { reason: [...new Set(rows.map((r) => r.detail))].join("; ") } : {}
6126
6221
  };
6127
6222
  }
6128
- function row$2(zone, status, detail, problems = []) {
6223
+ function row$4(zone, status, detail, problems = []) {
6129
6224
  return {
6130
6225
  id: `dns-${zone}`,
6131
6226
  title: `${zone} records exist`,
@@ -6154,7 +6249,7 @@ async function checkDomain(dns, deploy, project, hostname) {
6154
6249
  return noToken !== void 0 ? domainRow(hostname, "skip", noToken) : domainRow(hostname, "fail", errorMessage(err));
6155
6250
  }
6156
6251
  }
6157
- async function checkZone(dns, zone, wanted, rowOf = (...args) => row$2(zone, ...args)) {
6252
+ async function checkZone(dns, zone, wanted, rowOf = (...args) => row$4(zone, ...args)) {
6158
6253
  try {
6159
6254
  const have = await dns.listRecords(zone);
6160
6255
  const problems = declaredVsActual(new Map(wanted.map((w) => [keyOf(w), w])), new Map(have.map((h) => [keyOf(h), h])), {
@@ -7933,11 +8028,11 @@ const LIMIT = 1900;
7933
8028
  * The message `doctor notifications --post` sends, in Discord's markdown: a heading, the counts, and, when a step
7934
8029
  * failed, each failing step in bold with its problems as a list. A clean run is only the heading and the counts.
7935
8030
  * Built from the report, never from printed output, and flattened and capped line by line like the terminal's own
7936
- * rows. A `#channel` in a problem is turned into a link by the provider that posts it.
8031
+ * rows. `name` is the deep check the post is about (default `notifications`). A `#channel` in a problem is turned into a link by the provider that posts it.
7937
8032
  */
7938
- function formatDoctorPost(report) {
8033
+ function formatDoctorPost(report, name = "notifications") {
7939
8034
  const { pass, fail, skip } = report.summary;
7940
- const lines = [`### ${fail === 0 ? "✅" : "❌"} \`holocron doctor notifications\``, `**${pass}** ok · **${fail}** fail · **${skip}** skipped`];
8035
+ const lines = [`### ${fail === 0 ? "✅" : "❌"} \`holocron doctor ${name}\``, `**${pass}** ok · **${fail}** fail · **${skip}** skipped`];
7941
8036
  for (const check of report.checks.filter((c) => c.status === "fail")) {
7942
8037
  lines.push("", `**${sanitizeDetail(check.title)}** — ${sanitizeDetail(check.detail)}`);
7943
8038
  for (const problem of check.problems) lines.push(`- ${sanitizeDetail(problem)}`);
@@ -7947,13 +8042,13 @@ function formatDoctorPost(report) {
7947
8042
  }
7948
8043
  // src/commands/post-doctor-report/post-doctor-report.ts
7949
8044
  /**
7950
- * Posts a `doctor notifications` result to a channel and returns the line to print about it. Never throws: a post
8045
+ * Posts a `doctor notifications` (or, with `name`, another deep check's) result to a channel and returns the line to print about it. Never throws: a post
7951
8046
  * that could not be made is reported and leaves the check's own result, and so its exit code, as it was.
7952
8047
  */
7953
- async function postDoctorReport(notifications, channel, report) {
8048
+ async function postDoctorReport(notifications, channel, report, name = "notifications") {
7954
8049
  if (!notifications.postMessage) return `not posted: the \`${notifications.providerName}\` provider cannot post a message as the bot`;
7955
8050
  try {
7956
- await notifications.postMessage(channel, formatDoctorPost(report));
8051
+ await notifications.postMessage(channel, formatDoctorPost(report, name));
7957
8052
  return `posted to #${sanitizeDetail(channel)}`;
7958
8053
  } catch (err) {
7959
8054
  return `not posted: ${sanitizeDetail(describeProviderError(err))}`;
@@ -8703,6 +8798,639 @@ const doctorNotificationsCommand = {
8703
8798
  })).status === "fail") process.exitCode = 1;
8704
8799
  }
8705
8800
  };
8801
+ // src/commands/project/fs-templates-io/fs-templates-io.ts
8802
+ /** The real file system for `loadTemplates`, with a relative directory taken from `repoRoot`. A missing directory is empty. */
8803
+ function createFsTemplatesIo(repoRoot) {
8804
+ return {
8805
+ async listFiles(dir) {
8806
+ try {
8807
+ return await readdir(resolve(repoRoot, dir));
8808
+ } catch (err) {
8809
+ if (err.code === "ENOENT") return [];
8810
+ throw err;
8811
+ }
8812
+ },
8813
+ readFile: (path) => readFile(resolve(repoRoot, path), "utf8")
8814
+ };
8815
+ }
8816
+ // src/commands/project/templates/builtin-templates/builtin-templates.ts
8817
+ /** The templates that ship in `@theholocron/cli`, by name. A repo's own template with the same name replaces one. */
8818
+ const BUILTIN_TEMPLATES = {
8819
+ roadmap: {
8820
+ name: "roadmap",
8821
+ statuses: [
8822
+ {
8823
+ name: "Someday",
8824
+ category: "backlog",
8825
+ color: "GRAY",
8826
+ description: "Idea or future consideration, not yet planned"
8827
+ },
8828
+ {
8829
+ name: "Todo",
8830
+ category: "planned",
8831
+ color: "BLUE",
8832
+ description: "Planned and ready to be worked on"
8833
+ },
8834
+ {
8835
+ name: "In Progress",
8836
+ category: "active",
8837
+ color: "YELLOW",
8838
+ description: "Currently being worked on"
8839
+ },
8840
+ {
8841
+ name: "Blocked",
8842
+ category: "blocked",
8843
+ color: "RED",
8844
+ description: "Waiting on another issue or an outside change"
8845
+ },
8846
+ {
8847
+ name: "Done",
8848
+ category: "done",
8849
+ color: "GREEN",
8850
+ description: "Completed"
8851
+ }
8852
+ ],
8853
+ fields: [{
8854
+ name: "Priority",
8855
+ type: "single_select",
8856
+ options: [
8857
+ "1 · Now",
8858
+ "2 · Next",
8859
+ "3 · Process"
8860
+ ]
8861
+ }, {
8862
+ name: "Milestone",
8863
+ type: "text"
8864
+ }],
8865
+ views: [
8866
+ {
8867
+ name: "Active",
8868
+ layout: "board",
8869
+ filter: "-status:Someday -status:Done",
8870
+ default: true
8871
+ },
8872
+ {
8873
+ name: "Backlog",
8874
+ layout: "board",
8875
+ filter: "status:Someday"
8876
+ },
8877
+ {
8878
+ name: "Done",
8879
+ layout: "table",
8880
+ filter: "status:Done"
8881
+ }
8882
+ ],
8883
+ rules: ["Auto-add sub-issues to project"]
8884
+ },
8885
+ sprint: {
8886
+ name: "sprint",
8887
+ statuses: [
8888
+ {
8889
+ name: "Todo",
8890
+ category: "planned",
8891
+ color: "BLUE"
8892
+ },
8893
+ {
8894
+ name: "In Progress",
8895
+ category: "active",
8896
+ color: "YELLOW"
8897
+ },
8898
+ {
8899
+ name: "Blocked",
8900
+ category: "blocked",
8901
+ color: "RED"
8902
+ },
8903
+ {
8904
+ name: "Done",
8905
+ category: "done",
8906
+ color: "GREEN"
8907
+ }
8908
+ ],
8909
+ fields: [{
8910
+ name: "Sprint",
8911
+ type: "text"
8912
+ }],
8913
+ views: [{
8914
+ name: "Active",
8915
+ layout: "table",
8916
+ filter: "-status:Done",
8917
+ default: true
8918
+ }, {
8919
+ name: "Done",
8920
+ layout: "table",
8921
+ filter: "status:Done"
8922
+ }]
8923
+ }
8924
+ };
8925
+ // src/commands/project/templates/resolve-template/resolve-template.ts
8926
+ /** `base` with `added` merged in by name: an entry with the same name replaces the inherited one in place. */
8927
+ function mergeByName(base, added) {
8928
+ const merged = [...base];
8929
+ for (const entry of added ?? []) {
8930
+ const at = merged.findIndex((existing) => existing.name === entry.name);
8931
+ if (at === -1) merged.push(entry);
8932
+ else merged[at] = entry;
8933
+ }
8934
+ return merged;
8935
+ }
8936
+ /**
8937
+ * Turn a template file into a whole {@link BoardTemplate}. With `extends` it starts from the named template (looked up
8938
+ * in `templates`, the built-ins and the repo's own) and merges the file's statuses, fields and views in by name, so an
8939
+ * entry the file repeats replaces the inherited one and the rest are kept; rules are added, and `source` is the file's
8940
+ * or the inherited one. Without `extends` the file must already be whole. `name` is the template's name when the file
8941
+ * does not say, which is its file name.
8942
+ */
8943
+ function resolveTemplate(name, file, templates) {
8944
+ if (file.extends !== void 0) {
8945
+ const base = templates[file.extends];
8946
+ if (!base) return {
8947
+ ok: false,
8948
+ problems: [`extends "${file.extends}": there is no template with that name`]
8949
+ };
8950
+ if (file.extends === (file.name ?? name)) return {
8951
+ ok: false,
8952
+ problems: [`"${file.extends}" cannot extend itself`]
8953
+ };
8954
+ return {
8955
+ ok: true,
8956
+ template: {
8957
+ name: file.name ?? name,
8958
+ statuses: mergeByName(base.statuses, file.statuses),
8959
+ fields: mergeByName(base.fields, file.fields),
8960
+ views: mergeByName(base.views, file.views),
8961
+ rules: [.../* @__PURE__ */ new Set([...base.rules ?? [], ...file.rules ?? []])],
8962
+ source: file.source ?? base.source
8963
+ }
8964
+ };
8965
+ }
8966
+ if (!file.statuses || !file.fields || !file.views) return {
8967
+ ok: false,
8968
+ problems: ["a template without extends must list its statuses, fields and views"]
8969
+ };
8970
+ return {
8971
+ ok: true,
8972
+ template: {
8973
+ name: file.name ?? name,
8974
+ statuses: file.statuses,
8975
+ fields: file.fields,
8976
+ views: file.views,
8977
+ rules: file.rules,
8978
+ source: file.source
8979
+ }
8980
+ };
8981
+ }
8982
+ // src/commands/project/templates/validate-template/validate-template.ts
8983
+ const CATEGORIES = [
8984
+ "backlog",
8985
+ "planned",
8986
+ "active",
8987
+ "blocked",
8988
+ "done"
8989
+ ];
8990
+ const FIELD_TYPES = [
8991
+ "single_select",
8992
+ "text",
8993
+ "number",
8994
+ "date",
8995
+ "iteration"
8996
+ ];
8997
+ const LAYOUTS = ["board", "table"];
8998
+ function isRecord$1(value) {
8999
+ return typeof value === "object" && value !== null && !Array.isArray(value);
9000
+ }
9001
+ function isText(value) {
9002
+ return typeof value === "string" && value.trim() !== "";
9003
+ }
9004
+ /** Problems with a list of named entries: not an array, not an object, no name, or a name used twice. */
9005
+ function namedList(label, value, check) {
9006
+ if (!Array.isArray(value)) return [`${label} must be a list`];
9007
+ const problems = [];
9008
+ const seen = /* @__PURE__ */ new Set();
9009
+ value.forEach((entry, i) => {
9010
+ const where = `${label}[${i}]`;
9011
+ if (!isRecord$1(entry)) {
9012
+ problems.push(`${where} must be an object`);
9013
+ return;
9014
+ }
9015
+ if (!isText(entry.name)) problems.push(`${where} needs a name`);
9016
+ else if (seen.has(entry.name)) problems.push(`${where}: the name "${entry.name}" is used twice`);
9017
+ else seen.add(entry.name);
9018
+ problems.push(...check(entry, where));
9019
+ });
9020
+ return problems;
9021
+ }
9022
+ /**
9023
+ * Check what a template file holds, without reading any file: the shape of the statuses, fields, views and rules, a
9024
+ * name used twice, a category or layout that does not exist. With no `extends` it must also hold a whole template (a
9025
+ * status, the fields and the views). Returns the file typed, or every problem found, so one run lists them all.
9026
+ */
9027
+ function validateTemplateFile(value) {
9028
+ if (!isRecord$1(value)) return {
9029
+ ok: false,
9030
+ problems: ["a template must be an object"]
9031
+ };
9032
+ const problems = [];
9033
+ if (value.name !== void 0 && !isText(value.name)) problems.push("name must be text");
9034
+ if (value.extends !== void 0 && !isText(value.extends)) problems.push("extends must be the name of a template");
9035
+ if (value.source !== void 0 && !isText(value.source)) problems.push("source must be the name of a board");
9036
+ if (value.rules !== void 0 && !(Array.isArray(value.rules) && value.rules.every(isText))) problems.push("rules must be a list of rule names");
9037
+ if (value.statuses !== void 0) problems.push(...namedList("statuses", value.statuses, (s, where) => typeof s.category === "string" && CATEGORIES.includes(s.category) ? [] : [`${where} needs a category: ${CATEGORIES.join(", ")}`]));
9038
+ if (value.fields !== void 0) problems.push(...namedList("fields", value.fields, (f, where) => {
9039
+ if (typeof f.type !== "string" || !FIELD_TYPES.includes(f.type)) return [`${where} needs a type: ${FIELD_TYPES.join(", ")}`];
9040
+ const options = f.options;
9041
+ if (f.type === "single_select") return Array.isArray(options) && options.length > 0 && options.every(isText) ? [] : [`${where} is a single_select and needs a list of options`];
9042
+ return options === void 0 ? [] : [`${where} has options but is not a single_select`];
9043
+ }));
9044
+ if (value.views !== void 0) problems.push(...namedList("views", value.views, (v, where) => typeof v.layout === "string" && LAYOUTS.includes(v.layout) ? [] : [`${where} needs a layout: ${LAYOUTS.join(", ")}`]));
9045
+ if (value.extends === void 0) {
9046
+ if (!Array.isArray(value.statuses) || value.statuses.length === 0) problems.push("a template without extends must list its statuses");
9047
+ else if (!value.statuses.some((s) => isRecord$1(s) && s.category === "done")) problems.push("statuses need one in the done category");
9048
+ if (value.fields === void 0) problems.push("a template without extends must list its fields (an empty list is fine)");
9049
+ if (!Array.isArray(value.views) || value.views.length === 0) problems.push("a template without extends must list its views");
9050
+ }
9051
+ return problems.length > 0 ? {
9052
+ ok: false,
9053
+ problems
9054
+ } : {
9055
+ ok: true,
9056
+ file: value
9057
+ };
9058
+ }
9059
+ // src/commands/project/load-templates/load-templates.ts
9060
+ /**
9061
+ * Read the repo's own template files (`<name>.json` in `dir`) and add them to the built-ins. A file's name is the
9062
+ * template's name unless the file says another. A template may extend another of the repo's, whatever the order the files
9063
+ * are read in. A file that is not JSON, not a valid template, or extends something that does not exist is reported
9064
+ * with its name and left out, and the rest still load.
9065
+ */
9066
+ async function loadTemplates(dir, io) {
9067
+ const templates = { ...BUILTIN_TEMPLATES };
9068
+ const problems = [];
9069
+ const pending = [];
9070
+ const names = (await io.listFiles(dir)).filter((f) => f.endsWith(".json")).sort();
9071
+ for (const file of names) {
9072
+ let value;
9073
+ try {
9074
+ value = JSON.parse(await io.readFile(`${dir}/${file}`));
9075
+ } catch {
9076
+ problems.push(`${file}: not valid JSON`);
9077
+ continue;
9078
+ }
9079
+ const parsed = validateTemplateFile(value);
9080
+ if (!parsed.ok) {
9081
+ problems.push(...parsed.problems.map((p) => `${file}: ${p}`));
9082
+ continue;
9083
+ }
9084
+ pending.push({
9085
+ file,
9086
+ name: file.slice(0, -5),
9087
+ parsed
9088
+ });
9089
+ }
9090
+ let waiting = pending;
9091
+ for (let progress = true; progress && waiting.length > 0;) {
9092
+ progress = false;
9093
+ const next = [];
9094
+ for (const item of waiting) {
9095
+ const base = item.parsed.file.extends;
9096
+ if (base !== void 0 && !templates[base] && waiting.some((w) => (w.parsed.file.name ?? w.name) === base)) {
9097
+ next.push(item);
9098
+ continue;
9099
+ }
9100
+ const result = resolveTemplate(item.name, item.parsed.file, templates);
9101
+ if (result.ok) {
9102
+ templates[result.template.name] = result.template;
9103
+ progress = true;
9104
+ } else {
9105
+ problems.push(...result.problems.map((p) => `${item.file}: ${p}`));
9106
+ progress = true;
9107
+ }
9108
+ }
9109
+ waiting = next;
9110
+ }
9111
+ for (const item of waiting) problems.push(`${item.file}: extends "${item.parsed.file.extends}", which never resolves (a cycle)`);
9112
+ return {
9113
+ templates,
9114
+ problems
9115
+ };
9116
+ }
9117
+ // src/commands/project/project-options/project-options.ts
9118
+ /** Where a repo's own template files live unless the `templates` option says otherwise. */
9119
+ const DEFAULT_TEMPLATES_DIR = ".holocron/projects";
9120
+ /**
9121
+ * Read the options of `providers.projects`: `org` (the owner, defaulting to `fallbackOwner`, the config's org), `boards`
9122
+ * (a list of `{ template, name }`, nothing else about a board is written in the config) and `templates` (the directory
9123
+ * of template files). Every problem is listed at once, and two boards with the same name are one.
9124
+ */
9125
+ function resolveProjectOptions(options, fallbackOwner) {
9126
+ const problems = [];
9127
+ const org = options.org;
9128
+ if (org !== void 0 && (typeof org !== "string" || org.trim() === "")) problems.push("org must be text");
9129
+ const owner = typeof org === "string" && org.trim() !== "" ? org : fallbackOwner;
9130
+ const dir = options.templates;
9131
+ if (dir !== void 0 && (typeof dir !== "string" || dir.trim() === "")) problems.push("templates must be the path of a directory");
9132
+ const boards = [];
9133
+ if (options.boards !== void 0) {
9134
+ if (!Array.isArray(options.boards)) problems.push("boards must be a list of { template, name }");
9135
+ else {
9136
+ const seen = /* @__PURE__ */ new Set();
9137
+ options.boards.forEach((entry, i) => {
9138
+ const where = `boards[${i}]`;
9139
+ if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
9140
+ problems.push(`${where} must be { template, name }`);
9141
+ return;
9142
+ }
9143
+ const { template, name } = entry;
9144
+ if (typeof template !== "string" || template.trim() === "") problems.push(`${where} needs a template`);
9145
+ if (typeof name !== "string" || name.trim() === "") problems.push(`${where} needs a name`);
9146
+ if (typeof template !== "string" || typeof name !== "string" || !template.trim() || !name.trim()) return;
9147
+ if (seen.has(name)) problems.push(`${where}: the board name "${name}" is used twice`);
9148
+ seen.add(name);
9149
+ boards.push({
9150
+ template,
9151
+ name
9152
+ });
9153
+ });
9154
+ }
9155
+ }
9156
+ if (problems.length > 0) return {
9157
+ ok: false,
9158
+ problems
9159
+ };
9160
+ return {
9161
+ ok: true,
9162
+ options: {
9163
+ owner,
9164
+ boards,
9165
+ templatesDir: typeof dir === "string" ? dir : DEFAULT_TEMPLATES_DIR
9166
+ }
9167
+ };
9168
+ }
9169
+ // src/commands/project/board-context/board-context.ts
9170
+ /**
9171
+ * The `projects` provider, the owner, the declared boards and the templates, in one place for `doctor project` and
9172
+ * `project move`. A missing provider is a `skip` with the reason (a provider that failed to load says why); options that
9173
+ * do not read are a `fail` with every problem.
9174
+ */
9175
+ async function openBoardContext(input) {
9176
+ const { loaded, context, loader } = input;
9177
+ if (!loader.has("projects")) {
9178
+ const failure = loader.loadFailures().find((f) => f.key === "projects");
9179
+ return {
9180
+ ok: false,
9181
+ kind: "skip",
9182
+ reason: failure ? `the \`${failure.provider}\` projects provider failed to load: ${describeProviderError(failure.error)}` : "no `projects` provider is configured",
9183
+ problems: []
9184
+ };
9185
+ }
9186
+ const entry = loaded.resolved.providers.projects;
9187
+ const parsed = resolveProjectOptions(entry && entry.cardinality === "single" ? entry.tuple.options : {}, loaded.resolved.org ?? context.org ?? "");
9188
+ if (!parsed.ok) return {
9189
+ ok: false,
9190
+ kind: "fail",
9191
+ reason: "providers.projects options are not valid",
9192
+ problems: parsed.problems
9193
+ };
9194
+ const { owner, boards, templatesDir } = parsed.options;
9195
+ const { templates, problems } = await loadTemplates(join(context.repoRoot, templatesDir), input.io ?? createFsTemplatesIo(context.repoRoot));
9196
+ return {
9197
+ ok: true,
9198
+ context: {
9199
+ projects: loader.get("projects"),
9200
+ owner,
9201
+ boards,
9202
+ templates,
9203
+ templateProblems: problems
9204
+ }
9205
+ };
9206
+ }
9207
+ // src/commands/doctor-project/board-rows.ts
9208
+ /** A row that is information only: it never fails the run and counts as skipped. */
9209
+ const info = (id, title, noun, extras) => ({
9210
+ id,
9211
+ title,
9212
+ status: "skip",
9213
+ detail: `info: ${extras.length} ${noun} not in the template (never deleted)`,
9214
+ problems: extras
9215
+ });
9216
+ const row$3 = (id, title, problems, ok) => ({
9217
+ id,
9218
+ title,
9219
+ status: problems.length > 0 ? "fail" : "ok",
9220
+ detail: problems.length > 0 ? `${problems.length} problem(s)` : ok,
9221
+ problems
9222
+ });
9223
+ /** The problems with an ordered list: what is missing, and, when nothing is, whether the declared ones are in order. */
9224
+ function listProblems(noun, plural, declared, actual) {
9225
+ const problems = declared.filter((d) => !actual.includes(d)).map((d) => `missing ${noun} ${d}`);
9226
+ if (problems.length > 0) return problems;
9227
+ const present = actual.filter((a) => declared.includes(a));
9228
+ return present.some((a, i) => a !== declared[i]) ? [`${plural} are in the order ${present.join(", ")}, declared ${declared.join(", ")}`] : [];
9229
+ }
9230
+ function fieldProblems(want, found) {
9231
+ if (!found) return [`missing field ${want.name}`];
9232
+ const problems = [];
9233
+ if (found.type !== want.type) problems.push(`type is ${found.type}, declared ${want.type}`);
9234
+ if (want.options) problems.push(...listProblems("option", "options", want.options, found.options ?? []));
9235
+ return problems;
9236
+ }
9237
+ function viewProblems(want, found) {
9238
+ if (!found) return [`missing view ${want.name}`];
9239
+ const problems = [];
9240
+ if (found.layout !== want.layout) problems.push(`layout is ${found.layout}, declared ${want.layout}`);
9241
+ if (want.filter !== void 0 && found.filter !== want.filter) problems.push(`filter is ${found.filter ?? "none"}, declared ${want.filter}`);
9242
+ return problems;
9243
+ }
9244
+ /**
9245
+ * The rows that compare a declared board's template with the live board, in the order the spec lists them: the
9246
+ * statuses (in order), each field with its options (in order), each view with its layout and filter, each automation
9247
+ * rule. What the board has beyond the template is an `info` row and never a failure.
9248
+ */
9249
+ function boardRows(boardName, template, state) {
9250
+ const id = `project:${boardName}`;
9251
+ const rows = [];
9252
+ rows.push(row$3(`${id}:statuses`, `${boardName}: statuses`, listProblems("status", "statuses", template.statuses.map((s) => s.name), state.statuses), `${template.statuses.length} in order`));
9253
+ const extraStatuses = state.statuses.filter((s) => !template.statuses.some((t) => t.name === s));
9254
+ if (extraStatuses.length > 0) rows.push(info(`${id}:extra-statuses`, `${boardName}: extra statuses`, "status(es)", extraStatuses));
9255
+ for (const want of template.fields) rows.push(row$3(`${id}:field:${want.name}`, `${boardName}: field ${want.name}`, fieldProblems(want, state.fields.find((f) => f.name === want.name)), want.options ? `${want.options.length} options in order` : want.type));
9256
+ const extraFields = state.fields.filter((f) => !template.fields.some((t) => t.name === f.name));
9257
+ if (extraFields.length > 0) rows.push(info(`${id}:extra-fields`, `${boardName}: extra fields`, "field(s)", extraFields.map((f) => f.name)));
9258
+ for (const want of template.views) rows.push(row$3(`${id}:view:${want.name}`, `${boardName}: view ${want.name}`, viewProblems(want, state.views.find((v) => v.name === want.name)), `${want.layout}${want.filter ? `, ${want.filter}` : ""}`));
9259
+ const extraViews = state.views.filter((v) => !template.views.some((t) => t.name === v.name));
9260
+ if (extraViews.length > 0) rows.push(info(`${id}:extra-views`, `${boardName}: extra views`, "view(s)", extraViews.map((v) => v.name)));
9261
+ for (const name of template.rules ?? []) {
9262
+ const found = state.rules.find((r) => r.name === name);
9263
+ const problems = !found ? [`missing rule ${name}`] : found.enabled ? [] : [`rule ${name} is off`];
9264
+ rows.push(row$3(`${id}:rule:${name}`, `${boardName}: rule ${name}`, problems, "on"));
9265
+ }
9266
+ return rows;
9267
+ }
9268
+ // src/commands/doctor-project/item-rows.ts
9269
+ const RULES = [
9270
+ {
9271
+ id: "no-status",
9272
+ label: "item without a status",
9273
+ test: (i) => i.status === void 0
9274
+ },
9275
+ {
9276
+ id: "closed-not-done",
9277
+ label: "closed item not in a done status",
9278
+ test: (i) => !i.open && i.status !== void 0 && i.category !== "done"
9279
+ },
9280
+ {
9281
+ id: "blocker-not-blocked",
9282
+ label: "open item with an open blocker but not in a blocked status",
9283
+ test: (i) => i.open && i.blockedBy.length > 0 && i.category !== "blocked"
9284
+ },
9285
+ {
9286
+ id: "blocked-no-blocker",
9287
+ label: "blocked item with no open blocker",
9288
+ test: (i) => i.open && i.category === "blocked" && i.blockedBy.length === 0
9289
+ }
9290
+ ];
9291
+ /**
9292
+ * One row per rule `project reconcile` fixes, over the board's items. The doctor only reports: a rule with items is an
9293
+ * `info` row (counted as skipped, never a failure) listing them, and a clean one is `ok`.
9294
+ */
9295
+ function itemRows(boardName, items) {
9296
+ return RULES.map(({ id, label, test }) => {
9297
+ const hits = items.filter(test);
9298
+ const title = `${boardName}: ${label}`;
9299
+ return hits.length === 0 ? {
9300
+ id: `project:${boardName}:${id}`,
9301
+ title,
9302
+ status: "ok",
9303
+ detail: "none",
9304
+ problems: []
9305
+ } : {
9306
+ id: `project:${boardName}:${id}`,
9307
+ title,
9308
+ status: "skip",
9309
+ detail: `info: ${hits.length} item(s); \`project reconcile\` fixes this`,
9310
+ problems: hits.map((i) => `${i.key} ${i.title}`)
9311
+ };
9312
+ });
9313
+ }
9314
+ // src/commands/doctor-project/doctor-project.ts
9315
+ /**
9316
+ * `holocron doctor project` — does each board `providers.projects.boards` declares exist, and does it match its template?
9317
+ *
9318
+ * Read-only. Per declared board, found by name among the open boards: one row for the board, then the rows of
9319
+ * `boardRows()` (statuses in order, each field and its options, each view, each automation rule) and the four item rows of
9320
+ * `itemRows()`. What the board has beyond the template, and the items `project reconcile` would fix, are `info` rows: they
9321
+ * never fail the run. A template file that does not read is a failure naming the file. `--post [channel]` shares the
9322
+ * failing rows through the `notifications` provider's bot, like `doctor notifications --post`.
9323
+ */
9324
+ const row$2 = (id, title, status, detail, problems = []) => ({
9325
+ id,
9326
+ title,
9327
+ status,
9328
+ detail,
9329
+ problems
9330
+ });
9331
+ async function runDoctorProject(input) {
9332
+ const print = input.print ?? ((line) => console.log(line));
9333
+ const logger = input.logger ?? getLogger();
9334
+ const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
9335
+ await loader.load();
9336
+ assertPluginsResolvable(loader, "doctor project");
9337
+ const rows = await checkBoards(input, loader);
9338
+ printCheckRows(rows, print);
9339
+ const summary = summariseChecks(rows);
9340
+ printCheckSummary(summary, print);
9341
+ const status = summary.fail > 0 ? "fail" : summary.ok === 0 ? "skip" : "ok";
9342
+ if (input.post !== void 0) print(` ${ui_exports.style.skip(await post(loader, input.post, rows, summary))}`);
9343
+ logger.info({
9344
+ ...summary,
9345
+ status
9346
+ }, "doctor project");
9347
+ return {
9348
+ status,
9349
+ rows,
9350
+ summary,
9351
+ ...status === "skip" ? { reason: [...new Set(rows.map((r) => r.detail))].join("; ") } : {}
9352
+ };
9353
+ }
9354
+ /** Shares the result as the first `notifications` provider that can post, or says why it could not. */
9355
+ async function post(loader, channel, rows, summary) {
9356
+ const providers = loader.has("notifications") ? loader.get("notifications") : [];
9357
+ const provider = providers.find((p) => p.postMessage) ?? providers[0];
9358
+ if (!provider) return "not posted: no `notifications` provider is configured";
9359
+ return postDoctorReport(provider, channel, {
9360
+ checks: rows.map((r) => ({
9361
+ ...r,
9362
+ status: r.status === "ok" ? "pass" : r.status
9363
+ })),
9364
+ summary: {
9365
+ pass: summary.ok,
9366
+ fail: summary.fail,
9367
+ skip: summary.skip
9368
+ }
9369
+ }, "project");
9370
+ }
9371
+ async function checkBoards(input, loader) {
9372
+ const opened = await openBoardContext({
9373
+ loaded: input.loaded,
9374
+ context: input.context,
9375
+ loader,
9376
+ ...input.io ? { io: input.io } : {}
9377
+ });
9378
+ if (!opened.ok) return [row$2("project", "project", opened.kind, opened.reason, opened.problems)];
9379
+ const { projects, owner, boards, templates, templateProblems } = opened.context;
9380
+ const rows = templateProblems.map((problem) => {
9381
+ /* v8 ignore next -- split always returns at least one element; the fallback only satisfies noUncheckedIndexedAccess */
9382
+ const file = problem.split(": ")[0] ?? problem;
9383
+ return row$2(`project:template:${file}`, `template file ${file}`, "fail", problem);
9384
+ });
9385
+ if (boards.length === 0) return [...rows, row$2("project", "project", "skip", "no boards are declared in `providers.projects.boards`")];
9386
+ for (const declared of boards) {
9387
+ const template = templates[declared.template];
9388
+ const title = `${declared.name}: board exists and is open`;
9389
+ try {
9390
+ const board = await projects.find(owner, declared.name);
9391
+ if (!board) {
9392
+ const closed = (await projects.list(owner)).some((b) => b.name === declared.name && b.closed);
9393
+ rows.push(row$2(`project:${declared.name}`, title, "fail", closed ? "the board is closed" : "no open board has this name", [closed ? "reopen it, or run `holocron project setup` to make a new one" : "run `holocron project setup`"]));
9394
+ continue;
9395
+ }
9396
+ rows.push(row$2(`project:${declared.name}`, title, "ok", board.url));
9397
+ if (!template) {
9398
+ rows.push(row$2(`project:${declared.name}:template`, `${declared.name}: template ${declared.template}`, "fail", "no built-in or file template has this name"));
9399
+ continue;
9400
+ }
9401
+ rows.push(...boardRows(declared.name, template, await projects.read(owner, board)));
9402
+ rows.push(...projects.items ? itemRows(declared.name, await projects.items(owner, board, template)) : [row$2(`project:${declared.name}:items`, `${declared.name}: items`, "skip", "the provider cannot list a board's items")]);
9403
+ } catch (err) {
9404
+ rows.push(row$2(`project:${declared.name}`, title, "fail", describeProviderError(err)));
9405
+ }
9406
+ }
9407
+ return rows;
9408
+ }
9409
+ // src/commands/doctor-project/doctor-project.command.ts
9410
+ const doctorProjectArgs = (y) => y.option("post", {
9411
+ type: "string",
9412
+ describe: "After the run, post the result to a channel as the bot: the failing rows, or only the summary when none failed (default channel: alerts)"
9413
+ });
9414
+ const doctorProjectCommand = {
9415
+ command: "project",
9416
+ describe: "Compare each declared project board with its template, and report items that need a status (read-only)",
9417
+ builder: doctorProjectArgs,
9418
+ handler: async (argv) => {
9419
+ const tokens = tokenContext$1(argv.token);
9420
+ if (!tokens) return;
9421
+ const loaded = await loadConfig(argv.cwd);
9422
+ applyResolvedConfig(argv, loaded.resolved);
9423
+ if ((await runDoctorProject({
9424
+ loaded,
9425
+ context: {
9426
+ repoRoot: argv.cwd,
9427
+ ...tokens,
9428
+ org: resolveOrg(argv, loaded.resolved)
9429
+ },
9430
+ ...argv.post !== void 0 ? { post: argv.post || "alerts" } : {}
9431
+ })).status === "fail") process.exitCode = 1;
9432
+ }
9433
+ };
8706
9434
  // src/commands/repo-files/hosted-reusables.ts
8707
9435
  /** The name of the private package that holds the reusable workflows and composite actions. */
8708
9436
  const CI_PACKAGE = "@theholocron/ci";
@@ -9964,6 +10692,19 @@ const DEEP_CHECKS = [
9964
10692
  summary: report.summary
9965
10693
  };
9966
10694
  }
10695
+ },
10696
+ {
10697
+ name: "project",
10698
+ capability: "projects",
10699
+ command: doctorProjectCommand,
10700
+ async run(input) {
10701
+ const report = await runDoctorProject(input);
10702
+ return {
10703
+ status: report.status,
10704
+ summary: report.summary,
10705
+ ...report.reason ? { reason: report.reason } : {}
10706
+ };
10707
+ }
9967
10708
  }
9968
10709
  ];
9969
10710
  // src/commands/doctor-all/doctor-all.ts
@@ -10446,7 +11187,7 @@ async function serveAppManifest(input) {
10446
11187
  * file is checked (git ignores it, it is not there already) before the browser opens. Nothing but names and paths is
10447
11188
  * ever printed.
10448
11189
  */
10449
- const COMMAND$1 = "github-app create";
11190
+ const COMMAND$5 = "github-app create";
10450
11191
  const DEFAULT_FILE = ".credentials";
10451
11192
  const DEFAULT_WEBHOOK_SECRET_VAR = "SENTINEL_WEBHOOK_SECRET";
10452
11193
  async function runGithubAppCreate(input) {
@@ -10457,7 +11198,7 @@ async function runGithubAppCreate(input) {
10457
11198
  logger.warn({
10458
11199
  status: "fail",
10459
11200
  reason
10460
- }, COMMAND$1);
11201
+ }, COMMAND$5);
10461
11202
  return { status: "fail" };
10462
11203
  };
10463
11204
  if ((input.platform ?? process.platform) === "win32") return refuse("windows", "cannot make the credentials file private on Windows: its mode bits are not enforced");
@@ -10517,7 +11258,7 @@ async function runGithubAppCreate(input) {
10517
11258
  status: "fail",
10518
11259
  reason: "write",
10519
11260
  slug: app.slug
10520
- }, COMMAND$1);
11261
+ }, COMMAND$5);
10521
11262
  for (const line of [`created ${app.slug}, but could not keep its credentials: ${errorMessage(err)}`, `they are shown once: delete the App (${settings}) and run this again`]) print(line);
10522
11263
  return {
10523
11264
  status: "fail",
@@ -10542,7 +11283,7 @@ async function runGithubAppCreate(input) {
10542
11283
  logger.info({
10543
11284
  status,
10544
11285
  slug: app.slug
10545
- }, COMMAND$1);
11286
+ }, COMMAND$5);
10546
11287
  return {
10547
11288
  status,
10548
11289
  slug: app.slug,
@@ -15628,7 +16369,7 @@ function hooksEnabled(input) {
15628
16369
  return config.repo?.protection === "strict";
15629
16370
  }
15630
16371
  // src/commands/repo-files/generate-config-files.ts
15631
- const { workflowHeader: workflowHeader$1 } = createHeader({
16372
+ const { workflowHeader: workflowHeader$2 } = createHeader({
15632
16373
  source: "cli/cli/src/commands/repo-files/generate-config-files.ts",
15633
16374
  tool: "holocron repo setup"
15634
16375
  });
@@ -15653,7 +16394,7 @@ async function generateConfigFiles(input) {
15653
16394
  const taskNames = (config.tasks ?? []).map((e) => typeof e === "string" ? e : e.name);
15654
16395
  const entries = [];
15655
16396
  if (taskNames.includes("bookkeeping")) entries.push(file(".github/labeler.yml", createLabeler()));
15656
- if (config.repo?.protection !== "none") entries.push(file(".github/dependabot.yml", createDependabot({ ignore: ownCatalogPackages(input.repoRoot) })), file(".github/dco.yml", `${workflowHeader$1()}${dco_default}`));
16397
+ if (config.repo?.protection !== "none") entries.push(file(".github/dependabot.yml", createDependabot({ ignore: ownCatalogPackages(input.repoRoot) })), file(".github/dco.yml", `${workflowHeader$2()}${dco_default}`));
15657
16398
  entries.push(file(".alexrc.json", createAlexrc()), file(".alexignore", createAlexignore()), file(".yamllint.yml", createYamllint()), file(".yamlignore", createYamlignore()), file(".editorconfig", createEditorconfig()), file(".editorconfig-checker.json", createEditorconfigChecker()), file("devmoji.config.cjs", createDevmoji()), file(".husky/prepare-commit-msg", createPrepareCommitMsg()), file(".husky/commit-msg", createCommitMsg(config.holocronScript)));
15658
16399
  if (hooksEnabled(input)) entries.push(file(".husky/pre-push", createPrePush(config.holocronScript), "runs `holocron run ci` before push — bypass with `git push --no-verify`"), file(".husky/pre-commit", createPreCommit(), "runs GitLeaks (staged-only) + lint-staged before commit"));
15659
16400
  else for (const hook of [".husky/pre-push", ".husky/pre-commit"]) entries.push({
@@ -15686,6 +16427,203 @@ async function generateConfigFiles(input) {
15686
16427
  }
15687
16428
  return entries;
15688
16429
  }
16430
+ // src/commands/workflow-source-marker/workflow-source-marker.ts
16431
+ /** `# Source package: <path>` line at the head of a generated thin-caller workflow — see {@link resolvePkgRelPath}. */
16432
+ const SOURCE_PACKAGE_MARKER = /^# Source package: (.+)$/m;
16433
+ /** Strip control characters (including ANSI escapes) before a value reaches a printed error message. */
16434
+ function sanitizeForDisplay(value) {
16435
+ return value.replace(/[\x00-\x1f\x7f]/g, "");
16436
+ }
16437
+ /**
16438
+ * Repo-root-relative path of the PACKAGE a workflow-writing command run is
16439
+ * scoped to — the directory holding the discovered `holocron.config.*`
16440
+ * (`configFilepath`), not necessarily `--cwd` itself. `loadConfig()` walks
16441
+ * up to find the config from any subdirectory ("every command is usable
16442
+ * from any subdirectory of a repo, not only its exact root"), so a `--cwd`
16443
+ * one level too deep would otherwise stamp a different marker than a later
16444
+ * run from the package's own root and misfire the collision check this
16445
+ * feeds (holocron#1026).
16446
+ *
16447
+ * "." for a root invocation, "apps/sentinel" for a subpackage. Normalized
16448
+ * to forward slashes so the same package produces the same marker on
16449
+ * Windows and POSIX. Throws if the result contains a line break — a path
16450
+ * containing one could otherwise break out of the `# Source package: `
16451
+ * comment line and inject arbitrary workflow YAML when the generated
16452
+ * content is later written. Not reachable through this CLI's own flows
16453
+ * (no code path writes a config file whose directory name contains a line
16454
+ * break), but cheap to reject outright rather than trust the filesystem.
16455
+ */
16456
+ function resolvePkgRelPath(gitRoot, configFilepath) {
16457
+ let root;
16458
+ try {
16459
+ root = realpathSync(gitRoot);
16460
+ } catch {
16461
+ root = gitRoot;
16462
+ }
16463
+ let configDir;
16464
+ try {
16465
+ configDir = realpathSync(dirname(configFilepath));
16466
+ } catch {
16467
+ configDir = dirname(configFilepath);
16468
+ }
16469
+ const pkgRelPath = (relative(root, configDir) || ".").split(sep).join("/");
16470
+ if (/[\r\n]/.test(pkgRelPath)) throw new Error(`refusing to use a package path containing a line break: ${JSON.stringify(pkgRelPath)}`);
16471
+ return pkgRelPath;
16472
+ }
16473
+ /**
16474
+ * Two different monorepo packages opting into the same generic task name
16475
+ * (e.g. both `apps/sentinel` and some future `apps/other` configuring
16476
+ * `delivery.previewDeploy`) would otherwise overwrite each other's
16477
+ * `.github/workflows/<task>.yml` on whichever package's write ran last —
16478
+ * only one package's behavior would ever actually run in CI, with no
16479
+ * signal that the other's was silently dropped (holocron#1026).
16480
+ *
16481
+ * Shared by both `holocron repo sync` (reads the file straight off local
16482
+ * disk) and `holocron repo setup` (reads it through the loaded `Source`
16483
+ * capability, which happens to be local disk too for the github plugin
16484
+ * today, but the interface doesn't promise that for every provider —
16485
+ * holocron#1068). The marker-parsing and error message are identical
16486
+ * either way; `readExisting` is how the two callers differ.
16487
+ *
16488
+ * A file with no marker at all predates this check (or was written before
16489
+ * #1026) and is never flagged — only a marker that's present AND disagrees
16490
+ * with the current run's own package is a real collision. `readExisting`
16491
+ * returning `null` means "nothing there," not "unreadable" — a caller
16492
+ * whose underlying read can fail for reasons other than "doesn't exist"
16493
+ * (e.g. local fs EISDIR) is expected to let that error propagate out of
16494
+ * `readExisting` itself rather than mapping it to `null`.
16495
+ */
16496
+ async function assertNoPackageCollision(taskName, pkgRelPath, filename, readExisting) {
16497
+ const existing = await readExisting();
16498
+ if (existing === null) return;
16499
+ const previousPkg = SOURCE_PACKAGE_MARKER.exec(existing)?.[1];
16500
+ if (previousPkg !== void 0 && previousPkg !== pkgRelPath) throw new Error(`task "${taskName}" would overwrite .github/workflows/${filename}, already generated for package "${sanitizeForDisplay(previousPkg)}" — the same task name can't be used by two different packages (holocron#1026). If "${sanitizeForDisplay(previousPkg)}" moved or was renamed to this path, delete .github/workflows/${filename} first and re-run this command; otherwise rename one or give it a different thin-caller filename.`);
16501
+ }
16502
+ // src/commands/repo-files/generate-project-workflow-files.ts
16503
+ /** Where the scheduled reconcile workflow is written. */
16504
+ const PROJECT_RECONCILE_WORKFLOW = ".github/workflows/platform.projectReconcile.yml";
16505
+ /**
16506
+ * The workflow's own name. `platform.notifications.yml` lists it under `workflow_run`, so a run that fails on the
16507
+ * default branch posts to #alerts with the gatekeepers ping.
16508
+ */
16509
+ const PROJECT_RECONCILE_NAME = "Project reconcile";
16510
+ /** The Actions secrets that hold the GitHub App's id and private key the run mints its installation token from. */
16511
+ const PROJECT_APP_SECRETS = {
16512
+ id: "SENTINEL_APP_ID",
16513
+ privateKey: "SENTINEL_APP_PRIVATE_KEY"
16514
+ };
16515
+ const { workflowHeader: workflowHeader$1 } = createHeader({
16516
+ source: "cli/cli/src/commands/repo-files/generate-project-workflow-files.ts",
16517
+ tool: "holocron repo sync"
16518
+ });
16519
+ /**
16520
+ * The workflow as YAML. Its nesting is written with tabs here, one tab for each two spaces of the file, and turned into spaces
16521
+ * when it is rendered: a source line that starts with spaces fails the editorconfig check, and the autofix that answers
16522
+ * it rewrites the YAML into tabs, which YAML does not allow.
16523
+ */
16524
+ function workflow(owner) {
16525
+ return `name: ${PROJECT_RECONCILE_NAME}
16526
+
16527
+ on: # yamllint disable-line rule:truthy
16528
+ schedule:
16529
+ - cron: "23 * * * *"
16530
+ workflow_dispatch:
16531
+ inputs:
16532
+ dry_run:
16533
+ description: "Only say what would change; set no status"
16534
+ type: boolean
16535
+ default: false
16536
+
16537
+ permissions:
16538
+ contents: read
16539
+
16540
+ # One run at a time: two could set the same item twice.
16541
+ concurrency:
16542
+ group: project-reconcile
16543
+ cancel-in-progress: false
16544
+
16545
+ jobs:
16546
+ reconcile:
16547
+ name: Reconcile and check the boards
16548
+ runs-on: ubuntu-latest
16549
+ timeout-minutes: 15
16550
+ steps:
16551
+ # \`GITHUB_TOKEN\` cannot write an organization project, so the run uses the GitHub App's installation token.
16552
+ # The App needs the organization Projects permission (read and write), which setup cannot grant: a person does.
16553
+ - name: Generate GitHub App token
16554
+ id: app-token
16555
+ uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
16556
+ with:
16557
+ app-id: \${{ secrets.${PROJECT_APP_SECRETS.id} }}
16558
+ private-key: \${{ secrets.${PROJECT_APP_SECRETS.privateKey} }}
16559
+ owner: ${owner}
16560
+ permission-organization-projects: write
16561
+ permission-issues: read
16562
+ permission-pull-requests: read
16563
+
16564
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
16565
+ name: Checkout repository
16566
+
16567
+ - uses: theholocron/.github/.github/actions/setup@main
16568
+ name: Setup
16569
+
16570
+ - uses: theholocron/.github/.github/actions/holocron@main
16571
+ name: Reconcile the boards
16572
+ id: reconcile
16573
+ with:
16574
+ command: project reconcile
16575
+ args: >-
16576
+ \${{ inputs.dry_run && '--dry-run' || '' }}
16577
+ --token github=\${{ steps.app-token.outputs.token }}
16578
+
16579
+ - name: List what changed
16580
+ if: \${{ !cancelled() && steps.reconcile.outputs.log-file != '' }}
16581
+ env:
16582
+ LOG_FILE: \${{ steps.reconcile.outputs.log-file }}
16583
+ run: |
16584
+ {
16585
+ echo "### Project reconcile"
16586
+ echo '\`\`\`'
16587
+ cat "$LOG_FILE"
16588
+ echo '\`\`\`'
16589
+ } >> "$GITHUB_STEP_SUMMARY"
16590
+
16591
+ # What reconcile cannot fix: an item with no status, a board that differs from its template, a rule that is off, a
16592
+ # missing App permission. A failure here fails the run, and the run's failure reaches #alerts.
16593
+ - uses: theholocron/.github/.github/actions/holocron@main
16594
+ name: Check the boards
16595
+ if: \${{ !cancelled() }}
16596
+ with:
16597
+ command: doctor project
16598
+ args: >-
16599
+ --token github=\${{ steps.app-token.outputs.token }}
16600
+ `.replaceAll(" ", " ");
16601
+ }
16602
+ /**
16603
+ * The scheduled workflow that keeps the declared boards true (spec `command-project`, "Keeping a board true"): hourly
16604
+ * and on demand it runs `holocron project reconcile`, then `holocron doctor project`, with a token minted from the
16605
+ * GitHub App. Written only when `providers.projects` declares boards, and for the owner the boards belong to, so a repo
16606
+ * without boards gets no file. A generated file, so `probe generated check` compares it with the committed copy.
16607
+ */
16608
+ function generateProjectWorkflowFiles(input) {
16609
+ const config = input.loaded.resolved;
16610
+ const entry = config.providers.projects;
16611
+ const tuple = entry?.cardinality === "single" ? entry.tuple : entry?.tuples[0];
16612
+ if (!tuple) return [];
16613
+ const resolved = resolveProjectOptions(tuple.options, config.org ?? "");
16614
+ if (!resolved.ok || resolved.options.boards.length === 0 || resolved.options.owner === "") return [];
16615
+ const pkgRelPath = resolvePkgRelPath(findRootSync(input.repoRoot, ".git", {
16616
+ fallback: "start",
16617
+ realpath: true
16618
+ }), input.loaded.filepath);
16619
+ return [{
16620
+ kind: "file",
16621
+ path: PROJECT_RECONCILE_WORKFLOW,
16622
+ content: `${workflowHeader$1()}# Source package: ${pkgRelPath}\n\n${workflow(resolved.options.owner)}`,
16623
+ step: "write workflow project reconcile",
16624
+ syncStep: "sync workflow project reconcile"
16625
+ }];
16626
+ }
15689
16627
  // src/commands/repo-files/generate-turbo-files.ts
15690
16628
  /**
15691
16629
  * `turbo.json`, and the two edits that go with it: `turbo.json` alone is inert unless the root is a workspace member
@@ -15806,78 +16744,6 @@ const { workflowHeader } = createHeader({
15806
16744
  function thinCallerFile(pkgRelPath, content) {
15807
16745
  return `${workflowHeader()}# Source package: ${pkgRelPath}\n\n${content}`;
15808
16746
  }
15809
- // src/commands/workflow-source-marker/workflow-source-marker.ts
15810
- /** `# Source package: <path>` line at the head of a generated thin-caller workflow — see {@link resolvePkgRelPath}. */
15811
- const SOURCE_PACKAGE_MARKER = /^# Source package: (.+)$/m;
15812
- /** Strip control characters (including ANSI escapes) before a value reaches a printed error message. */
15813
- function sanitizeForDisplay(value) {
15814
- return value.replace(/[\x00-\x1f\x7f]/g, "");
15815
- }
15816
- /**
15817
- * Repo-root-relative path of the PACKAGE a workflow-writing command run is
15818
- * scoped to — the directory holding the discovered `holocron.config.*`
15819
- * (`configFilepath`), not necessarily `--cwd` itself. `loadConfig()` walks
15820
- * up to find the config from any subdirectory ("every command is usable
15821
- * from any subdirectory of a repo, not only its exact root"), so a `--cwd`
15822
- * one level too deep would otherwise stamp a different marker than a later
15823
- * run from the package's own root and misfire the collision check this
15824
- * feeds (holocron#1026).
15825
- *
15826
- * "." for a root invocation, "apps/sentinel" for a subpackage. Normalized
15827
- * to forward slashes so the same package produces the same marker on
15828
- * Windows and POSIX. Throws if the result contains a line break — a path
15829
- * containing one could otherwise break out of the `# Source package: `
15830
- * comment line and inject arbitrary workflow YAML when the generated
15831
- * content is later written. Not reachable through this CLI's own flows
15832
- * (no code path writes a config file whose directory name contains a line
15833
- * break), but cheap to reject outright rather than trust the filesystem.
15834
- */
15835
- function resolvePkgRelPath(gitRoot, configFilepath) {
15836
- let root;
15837
- try {
15838
- root = realpathSync(gitRoot);
15839
- } catch {
15840
- root = gitRoot;
15841
- }
15842
- let configDir;
15843
- try {
15844
- configDir = realpathSync(dirname(configFilepath));
15845
- } catch {
15846
- configDir = dirname(configFilepath);
15847
- }
15848
- const pkgRelPath = (relative(root, configDir) || ".").split(sep).join("/");
15849
- if (/[\r\n]/.test(pkgRelPath)) throw new Error(`refusing to use a package path containing a line break: ${JSON.stringify(pkgRelPath)}`);
15850
- return pkgRelPath;
15851
- }
15852
- /**
15853
- * Two different monorepo packages opting into the same generic task name
15854
- * (e.g. both `apps/sentinel` and some future `apps/other` configuring
15855
- * `delivery.previewDeploy`) would otherwise overwrite each other's
15856
- * `.github/workflows/<task>.yml` on whichever package's write ran last —
15857
- * only one package's behavior would ever actually run in CI, with no
15858
- * signal that the other's was silently dropped (holocron#1026).
15859
- *
15860
- * Shared by both `holocron repo sync` (reads the file straight off local
15861
- * disk) and `holocron repo setup` (reads it through the loaded `Source`
15862
- * capability, which happens to be local disk too for the github plugin
15863
- * today, but the interface doesn't promise that for every provider —
15864
- * holocron#1068). The marker-parsing and error message are identical
15865
- * either way; `readExisting` is how the two callers differ.
15866
- *
15867
- * A file with no marker at all predates this check (or was written before
15868
- * #1026) and is never flagged — only a marker that's present AND disagrees
15869
- * with the current run's own package is a real collision. `readExisting`
15870
- * returning `null` means "nothing there," not "unreadable" — a caller
15871
- * whose underlying read can fail for reasons other than "doesn't exist"
15872
- * (e.g. local fs EISDIR) is expected to let that error propagate out of
15873
- * `readExisting` itself rather than mapping it to `null`.
15874
- */
15875
- async function assertNoPackageCollision(taskName, pkgRelPath, filename, readExisting) {
15876
- const existing = await readExisting();
15877
- if (existing === null) return;
15878
- const previousPkg = SOURCE_PACKAGE_MARKER.exec(existing)?.[1];
15879
- if (previousPkg !== void 0 && previousPkg !== pkgRelPath) throw new Error(`task "${taskName}" would overwrite .github/workflows/${filename}, already generated for package "${sanitizeForDisplay(previousPkg)}" — the same task name can't be used by two different packages (holocron#1026). If "${sanitizeForDisplay(previousPkg)}" moved or was renamed to this path, delete .github/workflows/${filename} first and re-run this command; otherwise rename one or give it a different thin-caller filename.`);
15880
- }
15881
16747
  // src/commands/repo-files/generate-workflow-files.ts
15882
16748
  /**
15883
16749
  * The thin-caller workflow for each task in the manifest, in the manifest's order. A task with no template is a
@@ -15997,6 +16863,7 @@ function generateWorkflowFiles(input) {
15997
16863
  async function generateRepoFiles(input) {
15998
16864
  return [
15999
16865
  ...generateWorkflowFiles(input),
16866
+ ...generateProjectWorkflowFiles(input),
16000
16867
  ...await generateConfigFiles(input),
16001
16868
  ...await generateAgentFiles(input),
16002
16869
  ...await generateTurboFiles(input)
@@ -16585,7 +17452,7 @@ function findReserved(file) {
16585
17452
  }
16586
17453
  // src/commands/probe/tasks/find-leftovers.ts
16587
17454
  /** The commands that take a task name as their next word: `holocron run`, `turbo run`, `pnpm run`, `pnpm`, ... */
16588
- const COMMAND = String.raw`(?:holocron run|turbo run|pnpm run|npm run|pnpm|yarn)\s+`;
17455
+ const COMMAND$4 = String.raw`(?:holocron run|turbo run|pnpm run|npm run|pnpm|yarn)\s+`;
16589
17456
  /** A regex alternation of `names`, escaped; matches nothing for an empty list. */
16590
17457
  function alternation(names) {
16591
17458
  return names.length === 0 ? "(?!)" : names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
@@ -16612,7 +17479,7 @@ function findLeftovers(files, names, options = {}) {
16612
17479
  const bare = Object.keys(names).filter((n) => !n.includes("."));
16613
17480
  const tail = options.files ? String.raw`(?![\w-])` : String.raw`(?![\w-]|\.ya?ml\b)`;
16614
17481
  const dottedPattern = new RegExp(`(?<![\\w.-])(${alternation(dotted)})${tail}`, "g");
16615
- const barePattern = new RegExp(`(?<![\\w.-])${COMMAND}(${alternation(bare)})(?![\\w:-]|\\.\\w)`, "g");
17482
+ const barePattern = new RegExp(`(?<![\\w.-])${COMMAND$4}(${alternation(bare)})(?![\\w:-]|\\.\\w)`, "g");
16616
17483
  return files.flatMap((file) => {
16617
17484
  const lines = file.text.split("\n");
16618
17485
  const field = taskField(file.path);
@@ -16829,6 +17696,774 @@ const probeCommand = {
16829
17696
  })).status === "fail") process.exitCode = 1;
16830
17697
  }
16831
17698
  };
17699
+ // src/commands/project/move/move.ts
17700
+ /**
17701
+ * `holocron project move <from> <to>` — carry the open items of one board to another by rule.
17702
+ *
17703
+ * Every open item goes with its status and priority; a closed or merged one stays behind, and the provider sets it to
17704
+ * a done status on the old board when it shows another. An item already on the target keeps its target values. It
17705
+ * writes, so it asks first (`--yes` skips the question; without a terminal it refuses instead of hanging) and `--dry-run`
17706
+ * only reads both boards' items and prints what would happen. A provider without the optional `move` is skipped with a
17707
+ * message.
17708
+ */
17709
+ async function runProjectMove(input) {
17710
+ const print = input.print ?? ((line) => console.log(line));
17711
+ const stop = (status, reason) => {
17712
+ print((0, ui_exports.statusRow)(status, ["project move", reason]));
17713
+ return {
17714
+ status,
17715
+ reason
17716
+ };
17717
+ };
17718
+ const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
17719
+ await loader.load();
17720
+ assertPluginsResolvable(loader, "project move");
17721
+ const opened = await openBoardContext({
17722
+ loaded: input.loaded,
17723
+ context: input.context,
17724
+ loader,
17725
+ ...input.io ? { io: input.io } : {}
17726
+ });
17727
+ if (!opened.ok) return stop(opened.kind, [opened.reason, ...opened.problems].join("; "));
17728
+ const { projects, owner, boards, templates } = opened.context;
17729
+ if (!projects.move) return stop("skip", `the \`${projects.providerName}\` provider cannot move items between boards`);
17730
+ const templateName = input.template ?? boards.find((b) => b.name === input.to)?.template ?? boards.find((b) => b.name === input.from)?.template ?? "roadmap";
17731
+ const template = templates[templateName];
17732
+ if (!template) return stop("fail", `no template named "${templateName}"`);
17733
+ let from;
17734
+ let to;
17735
+ try {
17736
+ from = await projects.find(owner, input.from) ?? (await projects.list(owner)).find((b) => b.name === input.from);
17737
+ to = await projects.find(owner, input.to);
17738
+ } catch (err) {
17739
+ return stop("fail", describeProviderError(err));
17740
+ }
17741
+ if (!from) return stop("fail", `no board named "${input.from}"`);
17742
+ if (!to) return stop("fail", `no open board named "${input.to}"`);
17743
+ if (input.context.dryRun) {
17744
+ if (!projects.items) return stop("skip", `the \`${projects.providerName}\` provider cannot list items to preview`);
17745
+ try {
17746
+ const preview = previewMove(await projects.items(owner, from, template), await projects.items(owner, to, template));
17747
+ print((0, ui_exports.statusRow)("skip", ["project move", "dry run: nothing was moved"]));
17748
+ printReport(preview, print, true);
17749
+ return {
17750
+ status: "ok",
17751
+ moved: preview
17752
+ };
17753
+ } catch (err) {
17754
+ return stop("fail", describeProviderError(err));
17755
+ }
17756
+ }
17757
+ if (!input.yes) {
17758
+ if (!(input.interactive ?? Boolean(process.stdin.isTTY))) throw new ui_exports.NonInteractiveError(`\`project move\` changes boards on ${projects.providerName}; pass --yes to run it without asking`);
17759
+ if (!await (input.confirm ?? ((message) => confirm({
17760
+ message,
17761
+ default: false
17762
+ })))(`Move the open items of "${from.name}" to "${to.name}"?`)) {
17763
+ print((0, ui_exports.statusRow)("skip", ["project move", "cancelled; nothing was changed"]));
17764
+ return { status: "cancelled" };
17765
+ }
17766
+ }
17767
+ try {
17768
+ const moved = await projects.move(owner, from, to, template);
17769
+ print((0, ui_exports.statusRow)("ok", ["project move", `"${from.name}" to "${to.name}"`]));
17770
+ printReport(moved, print, false);
17771
+ return {
17772
+ status: "ok",
17773
+ moved
17774
+ };
17775
+ } catch (err) {
17776
+ return stop("fail", describeProviderError(err));
17777
+ }
17778
+ }
17779
+ /** What a move would do: the open items not yet on the target move, the ones already there are kept, closed ones stay. */
17780
+ function previewMove(fromItems, toItems) {
17781
+ const onTarget = new Set(toItems.map((i) => i.key));
17782
+ return {
17783
+ moved: fromItems.filter((i) => i.open && !onTarget.has(i.key)).map((i) => i.key),
17784
+ kept: fromItems.filter((i) => i.open && onTarget.has(i.key)).map((i) => i.key),
17785
+ left: fromItems.filter((i) => !i.open).map((i) => i.key)
17786
+ };
17787
+ }
17788
+ function printReport(report, print, dry) {
17789
+ const line = (label, keys) => {
17790
+ print(` ${label}: ${keys.length}${keys.length > 0 ? ` (${keys.join(", ")})` : ""}`);
17791
+ };
17792
+ line(dry ? "would move" : "moved", report.moved);
17793
+ line(dry ? "would keep (already on the target)" : "kept (already on the target)", report.kept);
17794
+ line("left (closed, stay on the old board)", report.left);
17795
+ }
17796
+ // src/commands/project/move/move.command.ts
17797
+ const projectMoveArgs = (y) => y.positional("from", {
17798
+ type: "string",
17799
+ demandOption: true,
17800
+ describe: "The board the open items leave (by name)"
17801
+ }).positional("to", {
17802
+ type: "string",
17803
+ demandOption: true,
17804
+ describe: "The open board they go to (by name)"
17805
+ }).option("template", {
17806
+ type: "string",
17807
+ describe: "The template that reads the boards' statuses (default: the one the target board is declared with)"
17808
+ }).option("yes", {
17809
+ type: "boolean",
17810
+ describe: "Move without asking"
17811
+ });
17812
+ const projectMoveCommand = {
17813
+ command: "move <from> <to>",
17814
+ describe: "Move the open items of one board to another, with their status and priority; closed ones stay behind",
17815
+ builder: projectMoveArgs,
17816
+ handler: async (argv) => {
17817
+ const tokens = tokenContext$1(argv.token);
17818
+ if (!tokens) return;
17819
+ const loaded = await loadConfig(argv.cwd);
17820
+ applyResolvedConfig(argv, loaded.resolved);
17821
+ if ((await runProjectMove({
17822
+ loaded,
17823
+ context: {
17824
+ repoRoot: argv.cwd,
17825
+ dryRun: argv.dryRun,
17826
+ ...tokens,
17827
+ org: resolveOrg(argv, loaded.resolved)
17828
+ },
17829
+ from: argv.from,
17830
+ to: argv.to,
17831
+ ...argv.template ? { template: argv.template } : {},
17832
+ ...argv.yes ? { yes: true } : {}
17833
+ })).status === "fail") process.exitCode = 1;
17834
+ }
17835
+ };
17836
+ // src/commands/project/open-projects/open-projects.ts
17837
+ /**
17838
+ * Load the `projects` provider and read its options. A config without `providers.projects`, a provider that did not
17839
+ * load and options that are wrong are each a {@link ConfigError} whose message says what to write.
17840
+ */
17841
+ async function openProjects(input, command) {
17842
+ const entry = input.loaded.resolved.providers.projects;
17843
+ if (entry?.cardinality !== "single") throw new ConfigError(`${command}: needs a \`projects\` provider in holocron.config.ts, e.g. providers: { projects: "github" }`);
17844
+ const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
17845
+ await (0, ui_exports.withSpinner)("Loading plugins…", () => loader.load());
17846
+ assertPluginsResolvable(loader, command);
17847
+ if (!loader.has("projects")) {
17848
+ const failure = loader.loadFailures().find((f) => f.key === "projects");
17849
+ throw new ConfigError(`${command}: the \`projects\` provider is not available${failure ? ` (\`${failure.provider}\` failed to load: ${describeProviderError(failure.error)})` : ""}`);
17850
+ }
17851
+ const resolved = resolveProjectOptions(entry.tuple.options, input.owner ?? input.context.org ?? "");
17852
+ if (!resolved.ok) throw new ConfigError(`${command}: providers.projects is wrong: ${resolved.problems.join("; ")}`);
17853
+ if (resolved.options.owner === "") throw new ConfigError(`${command}: needs an owner: set \`org\` in holocron.config.ts, the provider's \`org\` option, or pass --org`);
17854
+ return {
17855
+ projects: loader.get("projects"),
17856
+ options: resolved.options
17857
+ };
17858
+ }
17859
+ // src/commands/project/project-rows/project-rows.ts
17860
+ /** Rows in the repo's `ok / fail / skip` style; the report is `fail` when any row failed. */
17861
+ function createProjectRows(print, logger) {
17862
+ const summary = {
17863
+ ok: 0,
17864
+ fail: 0,
17865
+ skip: 0
17866
+ };
17867
+ const text = (label, detail) => detail ? `${label} ${ui_exports.style.dim(`(${detail})`)}` : label;
17868
+ return {
17869
+ ok(label, detail) {
17870
+ summary.ok += 1;
17871
+ print(` ${ui_exports.style.success(text(label, detail))}`);
17872
+ },
17873
+ fail(label, detail) {
17874
+ summary.fail += 1;
17875
+ print(` ${ui_exports.style.fail(text(label, detail))}`);
17876
+ },
17877
+ skip(label, detail) {
17878
+ summary.skip += 1;
17879
+ print(` ${ui_exports.style.skip(text(label, detail))}`);
17880
+ },
17881
+ line: (line) => print(line),
17882
+ finish(command) {
17883
+ print("");
17884
+ const line = `${summary.ok} ok, ${summary.fail} failed, ${summary.skip} skipped`;
17885
+ print(summary.fail > 0 ? ui_exports.style.fail(line) : ui_exports.style.success(line));
17886
+ const status = summary.fail > 0 ? "fail" : "ok";
17887
+ logger?.[status === "ok" ? "info" : "warn"]({
17888
+ status,
17889
+ ...summary
17890
+ }, command);
17891
+ return {
17892
+ status,
17893
+ summary
17894
+ };
17895
+ }
17896
+ };
17897
+ }
17898
+ // src/commands/project/terminal-prompt/terminal-prompt.ts
17899
+ /** The prompt backed by `@inquirer/prompts`, interactive only when stdin is a terminal. */
17900
+ function terminalPrompt() {
17901
+ return {
17902
+ interactive: Boolean(process.stdin.isTTY),
17903
+ confirm: (message, defaultValue) => confirm({
17904
+ message,
17905
+ default: defaultValue
17906
+ }),
17907
+ select: (message, choices) => select({
17908
+ message,
17909
+ choices: choices.map((value) => ({ value }))
17910
+ })
17911
+ };
17912
+ }
17913
+ // src/commands/project/project-close/project-close.ts
17914
+ /**
17915
+ * `holocron project close <number-or-name> [--yes]` — close an open board. Reversible (the provider can reopen it).
17916
+ * Asks first in a terminal; without one it needs `--yes` and is a {@link NonInteractiveError} otherwise.
17917
+ */
17918
+ const COMMAND$3 = "project close";
17919
+ async function runProjectClose(input) {
17920
+ const print = input.print ?? ((line) => console.log(line));
17921
+ const rows = createProjectRows(print, input.logger ?? getLogger());
17922
+ const prompt = input.prompt ?? terminalPrompt();
17923
+ const dryRun = input.context.dryRun ?? false;
17924
+ const done = (closed) => ({
17925
+ ...rows.finish(COMMAND$3),
17926
+ closed
17927
+ });
17928
+ const { projects, options } = await openProjects(input, COMMAND$3);
17929
+ print(ui_exports.style.header(`Holocron project close — ${options.owner}${dryRun ? " (dry-run)" : ""}`));
17930
+ print("");
17931
+ try {
17932
+ const wanted = input.board.trim();
17933
+ const open = (await projects.list(options.owner)).filter((b) => !b.closed);
17934
+ const board = /^\d+$/.test(wanted) ? open.find((b) => b.number === Number(wanted)) : open.find((b) => b.name === wanted);
17935
+ if (!board) {
17936
+ rows.fail(`board ${wanted}`, "no open board with that number or name");
17937
+ return done(false);
17938
+ }
17939
+ const label = `board ${board.number === void 0 ? "" : `#${board.number} `}"${board.name}"`;
17940
+ if (dryRun) {
17941
+ rows.ok(label, "would close");
17942
+ return done(false);
17943
+ }
17944
+ if (!input.yes) {
17945
+ if (!prompt.interactive) throw new ui_exports.NonInteractiveError(`project close: closing ${label} needs a confirmation; pass --yes`);
17946
+ if (!await prompt.confirm(`Close ${label}?`, false)) {
17947
+ rows.skip(label, "kept open");
17948
+ return done(false);
17949
+ }
17950
+ }
17951
+ await projects.close(options.owner, board);
17952
+ rows.ok(label, "closed");
17953
+ return done(true);
17954
+ } catch (err) {
17955
+ if (err instanceof ui_exports.NonInteractiveError) throw err;
17956
+ rows.fail("close", errorMessage(err));
17957
+ return done(false);
17958
+ }
17959
+ }
17960
+ // src/commands/project/project-close/project-close.command.ts
17961
+ const projectCloseArgs = (yy) => yy.positional("board", {
17962
+ type: "string",
17963
+ demandOption: true,
17964
+ describe: "The board's number or name"
17965
+ }).option("yes", {
17966
+ type: "boolean",
17967
+ default: false,
17968
+ describe: "Close without asking"
17969
+ });
17970
+ const projectCloseCommand = {
17971
+ command: "close <board>",
17972
+ describe: "Close a board (reversible)",
17973
+ builder: projectCloseArgs,
17974
+ handler: async (argv) => {
17975
+ const tokens = tokenContext$1(argv.token);
17976
+ if (!tokens) return;
17977
+ const loaded = await loadConfig(argv.cwd);
17978
+ applyResolvedConfig(argv, loaded.resolved);
17979
+ if ((await runProjectClose({
17980
+ loaded,
17981
+ context: {
17982
+ repoRoot: argv.cwd,
17983
+ dryRun: argv.dryRun,
17984
+ ...tokens,
17985
+ org: resolveOrg(argv, loaded.resolved)
17986
+ },
17987
+ owner: argv.org,
17988
+ board: String(argv.board),
17989
+ yes: argv.yes
17990
+ })).status === "fail") process.exitCode = 1;
17991
+ }
17992
+ };
17993
+ // src/commands/project/project-create/project-create.ts
17994
+ /**
17995
+ * `holocron project create [template] [--title]` — make a board from a template (a built-in, or a file in the repo's
17996
+ * templates directory). Idempotent on the title: an open board that has it is not made again; a terminal is asked
17997
+ * whether to open the existing one, `--yes` prints its address, and anything else is a {@link NonInteractiveError}.
17998
+ */
17999
+ const COMMAND$2 = "project create";
18000
+ async function runProjectCreate(input) {
18001
+ const print = input.print ?? ((line) => console.log(line));
18002
+ const rows = createProjectRows(print, input.logger ?? getLogger());
18003
+ const prompt = input.prompt ?? terminalPrompt();
18004
+ const dryRun = input.context.dryRun ?? false;
18005
+ const done = (extra = {}) => ({
18006
+ ...rows.finish(COMMAND$2),
18007
+ created: false,
18008
+ ...extra
18009
+ });
18010
+ const { projects, options } = await openProjects(input, COMMAND$2);
18011
+ const loaded = await loadTemplates(options.templatesDir, input.io ?? createFsTemplatesIo(input.context.repoRoot));
18012
+ print(ui_exports.style.header(`Holocron project create — ${options.owner}${dryRun ? " (dry-run)" : ""}`));
18013
+ print("");
18014
+ for (const problem of loaded.problems) rows.fail("template", problem);
18015
+ const names = Object.keys(loaded.templates).sort();
18016
+ let name = input.template;
18017
+ if (name === void 0) {
18018
+ if (!prompt.interactive) throw new ui_exports.NonInteractiveError(`project create: name a template (${names.join(", ")}); there is no terminal to ask in`);
18019
+ name = await prompt.select("Template:", names);
18020
+ }
18021
+ const template = loaded.templates[name];
18022
+ if (!template) {
18023
+ rows.fail(`template ${name}`, `unknown; available: ${names.join(", ")}`);
18024
+ return done();
18025
+ }
18026
+ const title = input.title ?? template.name;
18027
+ try {
18028
+ const existing = await projects.find(options.owner, title);
18029
+ if (existing) {
18030
+ const label = `board "${title}"${existing.number === void 0 ? "" : ` (#${existing.number})`}`;
18031
+ if (input.yes) {
18032
+ rows.skip(`${label} already exists`, existing.url);
18033
+ return done({ board: existing });
18034
+ }
18035
+ if (!prompt.interactive) throw new ui_exports.NonInteractiveError(`project create: ${label} already exists (${existing.url}); pass --yes to keep it, or another --title`);
18036
+ const open = await prompt.confirm(`${label} already exists. Open it instead of creating another?`, true);
18037
+ rows.skip(open ? `${label} already exists` : `${label} kept, nothing created`, existing.url);
18038
+ return done({ board: existing });
18039
+ }
18040
+ if (dryRun) {
18041
+ rows.ok(`board "${title}"`, `would create from template ${template.name}`);
18042
+ return done();
18043
+ }
18044
+ const board = await projects.create(options.owner, title, template);
18045
+ rows.ok(`board "${title}"`, board.url);
18046
+ print("");
18047
+ print(` Title: ${title}`);
18048
+ print(` Template: ${template.name}`);
18049
+ print(` Fields: ${["Status", ...template.fields.map((f) => f.name)].join(", ")}`);
18050
+ print(` Views: ${template.views.map((v) => `${v.name} (${v.layout})`).join(", ")}`);
18051
+ return done({
18052
+ board,
18053
+ created: true
18054
+ });
18055
+ } catch (err) {
18056
+ if (err instanceof ui_exports.NonInteractiveError) throw err;
18057
+ rows.fail(`board "${title}"`, errorMessage(err));
18058
+ return done();
18059
+ }
18060
+ }
18061
+ // src/commands/project/project-create/project-create.command.ts
18062
+ const projectCreateArgs = (yy) => yy.positional("template", {
18063
+ type: "string",
18064
+ describe: "The template to make the board from: a built-in or a file in the templates directory"
18065
+ }).option("title", {
18066
+ type: "string",
18067
+ describe: "The board's title (defaults to the template's name)"
18068
+ }).option("yes", {
18069
+ type: "boolean",
18070
+ default: false,
18071
+ describe: "When an open board has that title, print its address instead of asking"
18072
+ });
18073
+ const projectCreateCommand = {
18074
+ command: "create [template]",
18075
+ describe: "Make a board from a template",
18076
+ builder: projectCreateArgs,
18077
+ handler: async (argv) => {
18078
+ const tokens = tokenContext$1(argv.token);
18079
+ if (!tokens) return;
18080
+ const loaded = await loadConfig(argv.cwd);
18081
+ applyResolvedConfig(argv, loaded.resolved);
18082
+ if ((await runProjectCreate({
18083
+ loaded,
18084
+ context: {
18085
+ repoRoot: argv.cwd,
18086
+ dryRun: argv.dryRun,
18087
+ ...tokens,
18088
+ org: resolveOrg(argv, loaded.resolved)
18089
+ },
18090
+ owner: argv.org,
18091
+ template: argv.template,
18092
+ title: argv.title,
18093
+ yes: argv.yes
18094
+ })).status === "fail") process.exitCode = 1;
18095
+ }
18096
+ };
18097
+ // src/commands/project/project-list/project-list.ts
18098
+ /**
18099
+ * `holocron project list` — the owner's boards, newest first, with their number, name and state. Read-only, so
18100
+ * `--dry-run` changes nothing here.
18101
+ */
18102
+ const COMMAND$1 = "project list";
18103
+ async function runProjectList(input) {
18104
+ const print = input.print ?? ((line) => console.log(line));
18105
+ const rows = createProjectRows(print, input.logger ?? getLogger());
18106
+ const { projects, options } = await openProjects(input, COMMAND$1);
18107
+ print(ui_exports.style.header(`Holocron project list — ${options.owner}`));
18108
+ print("");
18109
+ try {
18110
+ const boards = (await projects.list(options.owner)).toSorted((a, b) => (b.number ?? 0) - (a.number ?? 0));
18111
+ if (boards.length === 0) {
18112
+ rows.skip("no boards", options.owner);
18113
+ return rows.finish(COMMAND$1);
18114
+ }
18115
+ const width = Math.max(1, ...boards.map((b) => String(b.number ?? "").length));
18116
+ print(ui_exports.style.dim(` ${"#".padEnd(width)} ${"Name".padEnd(32)} State`));
18117
+ for (const b of boards) print(` ${String(b.number ?? "-").padEnd(width)} ${b.name.padEnd(32)} ${b.closed ? "closed" : "open"}`);
18118
+ print("");
18119
+ rows.ok(`${boards.length} board${boards.length === 1 ? "" : "s"}`, options.owner);
18120
+ } catch (err) {
18121
+ rows.fail("list", errorMessage(err));
18122
+ }
18123
+ return rows.finish(COMMAND$1);
18124
+ }
18125
+ // src/commands/project/project-list/project-list.command.ts
18126
+ const projectListCommand = {
18127
+ command: "list",
18128
+ describe: "List the boards of the organization, with their number, name and state",
18129
+ handler: async (argv) => {
18130
+ const tokens = tokenContext$1(argv.token);
18131
+ if (!tokens) return;
18132
+ const loaded = await loadConfig(argv.cwd);
18133
+ applyResolvedConfig(argv, loaded.resolved);
18134
+ const org = resolveOrg(argv, loaded.resolved);
18135
+ if ((await runProjectList({
18136
+ loaded,
18137
+ context: {
18138
+ repoRoot: argv.cwd,
18139
+ dryRun: argv.dryRun,
18140
+ ...tokens,
18141
+ org
18142
+ },
18143
+ owner: argv.org
18144
+ })).status === "fail") process.exitCode = 1;
18145
+ }
18146
+ };
18147
+ // src/commands/project/project-setup/project-setup.ts
18148
+ /**
18149
+ * `holocron project setup` — make each board `providers.projects.boards` declares match its template: find it by name
18150
+ * among the open boards, make it from its template when it is missing, then `ensure()` it. What the provider cannot do
18151
+ * itself comes back as a `todo`, and every todo fails the run until a person has done it. A board that fails does not
18152
+ * stop the next one.
18153
+ */
18154
+ const COMMAND = "project setup";
18155
+ async function runProjectSetup(input) {
18156
+ const print = input.print ?? ((line) => console.log(line));
18157
+ const rows = createProjectRows(print, input.logger ?? getLogger());
18158
+ const dryRun = input.context.dryRun ?? false;
18159
+ const { projects, options } = await openProjects(input, COMMAND);
18160
+ print(ui_exports.style.header(`Holocron project setup — ${options.owner}${dryRun ? " (dry-run)" : ""}`));
18161
+ print("");
18162
+ if (options.boards.length === 0) {
18163
+ rows.skip("no boards", "declare them in providers.projects: boards: [{ template, name }]");
18164
+ return rows.finish(COMMAND);
18165
+ }
18166
+ const loaded = await loadTemplates(options.templatesDir, input.io ?? createFsTemplatesIo(input.context.repoRoot));
18167
+ for (const problem of loaded.problems) rows.fail("template", problem);
18168
+ for (const declared of options.boards) {
18169
+ const label = `board ${declared.name}`;
18170
+ const template = loaded.templates[declared.template];
18171
+ if (!template) {
18172
+ rows.fail(label, `template "${declared.template}" is not a built-in or a file in ${options.templatesDir}`);
18173
+ continue;
18174
+ }
18175
+ try {
18176
+ let board = await projects.find(options.owner, declared.name);
18177
+ let created = false;
18178
+ if (!board) {
18179
+ if (dryRun) {
18180
+ rows.ok(label, `would create from template ${template.name}, then bring it in line`);
18181
+ continue;
18182
+ }
18183
+ board = await projects.create(options.owner, declared.name, template);
18184
+ created = true;
18185
+ rows.ok(label, `created from template ${template.name}: ${board.url}`);
18186
+ }
18187
+ if (!projects.ensure) {
18188
+ rows.skip(label, "the provider cannot compare a board with a template");
18189
+ continue;
18190
+ }
18191
+ if (dryRun) {
18192
+ rows.ok(label, `would bring ${board.url} in line with template ${template.name}`);
18193
+ continue;
18194
+ }
18195
+ const report = await projects.ensure(options.owner, board, template);
18196
+ for (const change of report.changes) rows.ok(`${label}: ${change}`);
18197
+ for (const todo of report.todos) rows.fail(`${label}: ${todo}`, "a person has to do this");
18198
+ if (report.changes.length === 0 && report.todos.length === 0) rows.ok(label, created ? "matches its template" : "already matches its template");
18199
+ } catch (err) {
18200
+ rows.fail(label, errorMessage(err));
18201
+ }
18202
+ }
18203
+ return rows.finish(COMMAND);
18204
+ }
18205
+ // src/commands/project/project-setup/project-setup.command.ts
18206
+ const projectSetupCommand = {
18207
+ command: "setup",
18208
+ describe: "Make each board providers.projects declares match its template, creating the ones that are missing",
18209
+ handler: async (argv) => {
18210
+ const tokens = tokenContext$1(argv.token);
18211
+ if (!tokens) return;
18212
+ const loaded = await loadConfig(argv.cwd);
18213
+ applyResolvedConfig(argv, loaded.resolved);
18214
+ if ((await runProjectSetup({
18215
+ loaded,
18216
+ context: {
18217
+ repoRoot: argv.cwd,
18218
+ dryRun: argv.dryRun,
18219
+ ...tokens,
18220
+ org: resolveOrg(argv, loaded.resolved)
18221
+ },
18222
+ owner: argv.org
18223
+ })).status === "fail") process.exitCode = 1;
18224
+ }
18225
+ };
18226
+ // src/commands/project/plan-reconcile/plan-reconcile.ts
18227
+ /**
18228
+ * Decide the status changes that keep a board true (spec `command-project`, "Keeping a board true"). Pure: it reads
18229
+ * the items and the template and touches nothing. Status only, never priority or any other field.
18230
+ *
18231
+ * - closed or merged, not in a `done` status: set to `done` (whatever the blockers say);
18232
+ * - open with no status: not changed, listed in `unset` (it needs a decision, not a rule; this holds even when it has a
18233
+ * blocker);
18234
+ * - open with an open blocker, not in a `blocked` status: set to `blocked`;
18235
+ * - open, in a `blocked` status, with no open blocker: set to `planned` (the status it held before is unknown).
18236
+ *
18237
+ * Where a category has several statuses the first in template order is used; where it has none the item is listed in
18238
+ * `unresolved` and nothing is guessed. An item's category is read from the template by its status name, falling back
18239
+ * to the one the provider reports. Applying the changes and planning again gives no change.
18240
+ */
18241
+ function planReconcile(items, template) {
18242
+ const target = (category) => template.statuses.find((s) => s.category === category)?.name;
18243
+ const plan = {
18244
+ changes: [],
18245
+ unset: [],
18246
+ unresolved: []
18247
+ };
18248
+ for (const item of items) {
18249
+ const category = item.status === void 0 ? void 0 : template.statuses.find((s) => s.name === item.status)?.category ?? item.category;
18250
+ let want;
18251
+ let reason;
18252
+ if (!item.open) {
18253
+ if (category !== "done") [want, reason] = ["done", "closed"];
18254
+ } else if (item.status === void 0) {
18255
+ plan.unset.push(item);
18256
+ continue;
18257
+ } else if (item.blockedBy.length > 0) {
18258
+ if (category !== "blocked") [want, reason] = ["blocked", "blocked"];
18259
+ } else if (category === "blocked") [want, reason] = ["planned", "unblocked"];
18260
+ if (want === void 0 || reason === void 0) continue;
18261
+ const to = target(want);
18262
+ if (to === void 0) {
18263
+ plan.unresolved.push({
18264
+ key: item.key,
18265
+ title: item.title,
18266
+ category: want,
18267
+ reason
18268
+ });
18269
+ continue;
18270
+ }
18271
+ plan.changes.push({
18272
+ key: item.key,
18273
+ title: item.title,
18274
+ ...item.status !== void 0 ? { from: item.status } : {},
18275
+ to,
18276
+ category: want,
18277
+ reason
18278
+ });
18279
+ }
18280
+ return plan;
18281
+ }
18282
+ // src/commands/project/reconcile/reconcile.ts
18283
+ /**
18284
+ * `holocron project reconcile [board]` — set the status of board items where a rule says so (spec `command-project`,
18285
+ * "Keeping a board true"): an open item with an open blocker goes to the `blocked` status, an open blocked one with no
18286
+ * blocker returns to `planned`, a closed or merged one goes to `done`. Status only, never priority or any other field.
18287
+ *
18288
+ * The rules are `planReconcile()`, pure; this reads the items through the `projects` capability, applies each change
18289
+ * through `setStatus` and prints one line per item. A refusal is a reported failure and the run continues; the exit is
18290
+ * non-zero if any failed. Idempotent, and `--dry-run` prints the plan and calls no mutator. A provider that cannot list
18291
+ * items or set a status is skipped cleanly. An open item with no status is reported, not set: the doctor tells a person.
18292
+ */
18293
+ /** The sentence after a change's arrow: why the rule applied. */
18294
+ const WHY = {
18295
+ blocked: "has an open blocker",
18296
+ unblocked: "no open blocker left",
18297
+ closed: "closed"
18298
+ };
18299
+ const line = (c) => `${c.key} ${c.from ?? "no status"} → ${c.to} (${WHY[c.reason]})`;
18300
+ async function runProjectReconcile(input) {
18301
+ const print = input.print ?? ((text) => console.log(text));
18302
+ const logger = input.logger ?? getLogger();
18303
+ /* v8 ignore next -- the real loader is only built outside tests, which always inject one */
18304
+ const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
18305
+ await loader.load();
18306
+ assertPluginsResolvable(loader, "project reconcile");
18307
+ const dryRun = input.context.dryRun ?? false;
18308
+ const report = {
18309
+ status: "ok",
18310
+ boards: [],
18311
+ failures: []
18312
+ };
18313
+ const refuse = (message, reason = message) => {
18314
+ print(` ${ui_exports.style.fail(message)}`);
18315
+ print("");
18316
+ print(ui_exports.style.header("0 ok, 1 fail, 0 skipped"));
18317
+ logger.warn({ reason }, "project reconcile");
18318
+ return {
18319
+ ...report,
18320
+ status: "fail",
18321
+ message
18322
+ };
18323
+ };
18324
+ const failStep = (step, message) => {
18325
+ report.failures.push({
18326
+ step,
18327
+ message
18328
+ });
18329
+ print(` ${ui_exports.style.fail(`${step}: ${message}`)}`);
18330
+ };
18331
+ const entry = input.loaded.resolved.providers.projects;
18332
+ if (!entry || !loader.has("projects")) return refuse("no `projects` provider is configured — add `projects: [\"github\", { boards: [...] }]` to holocron.config.ts");
18333
+ const projects = loader.get("projects");
18334
+ if (typeof projects.items !== "function" || typeof projects.setStatus !== "function") {
18335
+ print(` ${ui_exports.style.skip(`the \`${projects.providerName}\` provider cannot list items or set a status: nothing to reconcile`)}`);
18336
+ return {
18337
+ ...report,
18338
+ message: "skipped"
18339
+ };
18340
+ }
18341
+ /* v8 ignore stop */
18342
+ const resolved = resolveProjectOptions((entry.cardinality === "single" ? entry.tuple : entry.tuples[0])?.options ?? {}, input.context.org ?? input.loaded.resolved.org ?? "");
18343
+ if (!resolved.ok) return refuse(`providers.projects: ${resolved.problems.join("; ")}`);
18344
+ const { owner, boards, templatesDir } = resolved.options;
18345
+ if (boards.length === 0) return refuse("`providers.projects` declares no boards — add `boards: [{ template, name }]`");
18346
+ const wanted = input.board === void 0 ? boards : boards.filter((b) => b.name === input.board);
18347
+ if (wanted.length === 0) return refuse(`no declared board is named "${input.board}" (declared: ${boards.map((b) => b.name).join(", ")})`);
18348
+ const loadedTemplates = await loadTemplates(join(input.context.repoRoot, templatesDir), input.templatesIo ?? createFsTemplatesIo(input.context.repoRoot));
18349
+ for (const problem of loadedTemplates.problems) print(` ${ui_exports.style.warn(problem)}`);
18350
+ let ok = 0;
18351
+ let skipped = 0;
18352
+ for (const declared of wanted) {
18353
+ print(ui_exports.style.header(`${declared.name} (${declared.template})`));
18354
+ const template = loadedTemplates.templates[declared.template];
18355
+ if (!template) {
18356
+ failStep(declared.name, `there is no template named "${declared.template}"`);
18357
+ continue;
18358
+ }
18359
+ let board;
18360
+ let plan;
18361
+ try {
18362
+ board = await projects.find(owner, declared.name);
18363
+ if (!board) {
18364
+ failStep(declared.name, "the board does not exist or is closed; run `holocron project setup`");
18365
+ continue;
18366
+ }
18367
+ plan = planReconcile(await projects.items(owner, board, template), template);
18368
+ } catch (err) {
18369
+ failStep(declared.name, describeProviderError(err));
18370
+ logger.warn({
18371
+ board: declared.name,
18372
+ reason: logReason(err)
18373
+ }, "project reconcile");
18374
+ continue;
18375
+ }
18376
+ const outcome = {
18377
+ name: declared.name,
18378
+ changes: plan.changes,
18379
+ applied: [],
18380
+ unset: plan.unset.map((i) => i.key),
18381
+ unresolved: plan.unresolved
18382
+ };
18383
+ report.boards.push(outcome);
18384
+ for (const change of plan.changes) {
18385
+ if (dryRun) {
18386
+ print(` ${ui_exports.style.skip(`would set ${line(change)}`)}`);
18387
+ skipped++;
18388
+ continue;
18389
+ }
18390
+ try {
18391
+ const result = await projects.setStatus(owner, board, change.key, change.to);
18392
+ if (result.status !== change.to) {
18393
+ failStep(change.key, `refused: still ${result.status}${result.via ? ` (${result.via})` : ""}`);
18394
+ continue;
18395
+ }
18396
+ outcome.applied.push(change.key);
18397
+ ok++;
18398
+ print(` ${ui_exports.style.success(`${result.transitioned ? "set" : "already"} ${line(change)}`)}`);
18399
+ } catch (err) {
18400
+ failStep(change.key, describeProviderError(err));
18401
+ logger.warn({
18402
+ board: declared.name,
18403
+ key: change.key,
18404
+ reason: logReason(err)
18405
+ }, "project reconcile");
18406
+ }
18407
+ }
18408
+ for (const item of plan.unset) {
18409
+ print(` ${ui_exports.style.warn(`${item.key} has no status: needs a decision, left as it is`)}`);
18410
+ skipped++;
18411
+ }
18412
+ for (const u of plan.unresolved) {
18413
+ print(` ${ui_exports.style.warn(`${u.key} ${WHY[u.reason]} but the template has no ${u.category} status: left as it is`)}`);
18414
+ skipped++;
18415
+ }
18416
+ if (plan.changes.length === 0 && plan.unset.length === 0 && plan.unresolved.length === 0) {
18417
+ print(` ${ui_exports.style.skip("already true")}`);
18418
+ skipped++;
18419
+ }
18420
+ }
18421
+ if (report.failures.length > 0) report.status = "fail";
18422
+ else if (dryRun) report.status = "dry-run";
18423
+ print("");
18424
+ print(ui_exports.style.header(`${ok} ok, ${report.failures.length} fail, ${skipped} skipped`));
18425
+ logger.info({
18426
+ boards: report.boards.length,
18427
+ changes: report.boards.reduce((n, b) => n + b.changes.length, 0),
18428
+ failures: report.failures.length,
18429
+ status: report.status
18430
+ }, "project reconcile");
18431
+ return report;
18432
+ }
18433
+ // src/commands/project/reconcile/reconcile.args.ts
18434
+ const projectReconcileArgs = (y) => y.positional("board", {
18435
+ type: "string",
18436
+ describe: "The declared board to reconcile, by name (every declared board when left out)"
18437
+ });
18438
+ // src/commands/project/reconcile/reconcile.command.ts
18439
+ const projectReconcileCommand = {
18440
+ command: "reconcile [board]",
18441
+ describe: "Set item statuses where a rule says so: blocked, unblocked, closed (status only)",
18442
+ builder: projectReconcileArgs,
18443
+ handler: async (argv) => {
18444
+ const tokens = tokenContext$1(argv.token);
18445
+ if (!tokens) return;
18446
+ const loaded = await loadConfig(argv.cwd);
18447
+ applyResolvedConfig(argv, loaded.resolved);
18448
+ if ((await runProjectReconcile({
18449
+ loaded,
18450
+ context: {
18451
+ repoRoot: argv.cwd,
18452
+ dryRun: argv.dryRun,
18453
+ ...tokens,
18454
+ org: resolveOrg(argv, loaded.resolved)
18455
+ },
18456
+ ...argv.board ? { board: argv.board } : {}
18457
+ })).status === "fail") process.exitCode = 1;
18458
+ }
18459
+ };
18460
+ // src/commands/project/project.command.ts
18461
+ const projectCommand = {
18462
+ command: "project <subcommand>",
18463
+ describe: "Project boards: list, create, close and set them up from templates",
18464
+ builder: (y) => y.command(projectListCommand).command(projectCreateCommand).command(projectCloseCommand).command(projectSetupCommand).command(projectMoveCommand).command(projectReconcileCommand).command(groupMenu$1("project")),
18465
+ handler: () => {}
18466
+ };
16832
18467
  // src/commands/setup/agent-prompts-data.ts
16833
18468
  /**
16834
18469
  * Canonical AI engineering workflow role prompts.
@@ -21830,7 +23465,7 @@ try {
21830
23465
  org: argv.org
21831
23466
  });
21832
23467
  finishCommand = startCommand(name);
21833
- }).command(cloneCommand).command(doctorCommand).command(skillsCommand).command(runCommand).command(configShowCommand).command(authCommand).command(menuCommand(CLI_VERSION)).command(repoCommand).command(newCommand).command(probeCommand).command(secretsCommand).command(notificationsCommand).command(githubAppCommand).command(specsCommand).command(tunnelCommand).command(devCommand).command(syncCommand).command(packageCommand).command(deployCommand).command(monitoringCommand).strict().help().epilogue(`Execution contexts:
23468
+ }).command(cloneCommand).command(doctorCommand).command(skillsCommand).command(runCommand).command(configShowCommand).command(authCommand).command(menuCommand(CLI_VERSION)).command(repoCommand).command(newCommand).command(probeCommand).command(secretsCommand).command(notificationsCommand).command(githubAppCommand).command(specsCommand).command(tunnelCommand).command(projectCommand).command(devCommand).command(syncCommand).command(packageCommand).command(deployCommand).command(monitoringCommand).command(projectCommand).strict().help().epilogue(`Execution contexts:
21834
23469
  global works from a bare 'npm i -g': ${commandsInContext("global").join(", ")}\n repo-aware needs ./holocron.config in cwd: ${commandsInContext("repo-aware").join(", ")}\n workspace also needs the plugin packages: ${commandsInContext("workspace").join(", ")}\n https://docs.theholocron.dev/holocron/execution-contexts`).fail((msg, err) => {
21835
23470
  if (err instanceof Error && USER_FACING_ERRORS.has(err.name)) {
21836
23471
  captureException(err);