@theholocron/cli 5.0.0-alpha.380 → 5.0.0-alpha.382

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -699,7 +699,10 @@ See the [command pages](https://theholocron.dev/holocron/commands/notifications-
699
699
  a target issue only when a migrate or sync made it (the recorded `holocron:migrated-from` marker or attachment). A source
700
700
  issue that itself carries such an address is skipped, which stops the two directions echoing each other. The report
701
701
  counts created, updated, unchanged, skipped (guard) and left, and ends with the `not carried across` list. A rate limit
702
- stops the run with a `left` count. A target needs the optional `Issues.sync`; GitHub and Linear have it.
702
+ stops the run with a `left` count. A target needs the optional `Issues.sync`; GitHub and Linear have it. `--limit <n>` and
703
+ `--order <oldest|newest>` (also on `migrate issues` and `migrate project`) read only that many issues from the source,
704
+ from the first-created or the last-created end, for a trial run; the source's `Issues.export` honours
705
+ `IssueSelector.limit` and `order`, and the run prints `limited to N of M`. On a terminal, `migrate` and `sync issues` show a spinner with a counter for the read and the write (`Reading issues from github… 12 of 40`, `Writing to linear… 3 of 20`); piped, in CI or with `--quiet` they print nothing extra. A provider feeds it through the optional `onProgress(done, total)` of `ExportInfo` and `ImportOptions`.
703
706
 
704
707
  ## Cleaning up
705
708
 
@@ -774,6 +777,7 @@ holocron github-app create --name "My App - dev" --webhook-url https://<tunnel>/
774
777
  holocron tunnel up --name sentinel-dev --hostname sentinel-dev.example.dev --port 3000 --run # a named tunnel with a stable hostname to a local port
775
778
  holocron project list # the org's project boards (also: create [template], close <number-or-name>, setup)
776
779
  holocron migrate project v5 --from github --to github:repo=acme/new --dry-run # preview putting a board's issues on a board of the same name in the target (GitHub; --template picks the template a missing board is made from, default roadmap); a target without boards (Linear) gets a project of that name instead
780
+ holocron migrate issues --all --from github --to linear:team=ENG --limit 20 --order newest --dry-run # a trial run: read only the 20 last-created issues (--order oldest, the default, reads the first created); prints `limited to 20 of M`, and a second run with the same limit selects the same issues (`migrate issues` and `migrate project`, and `sync issues`; not `migrate issue`)
777
781
  holocron project move v4 v5 --dry-run # preview carrying the open items of one project board to another; without --dry-run it asks first (--yes skips)
778
782
  holocron doctor project # does each declared board match its template? (read-only; --post shares the failures)
779
783
  holocron dev # the app, its vault variables and the tunnel, in one command (settings: `dev` in holocron.config)
package/dist/cli.mjs CHANGED
@@ -2226,6 +2226,20 @@ const migrateIssuesEntry = {
2226
2226
  flag: "--keys",
2227
2227
  type: "input",
2228
2228
  message: "Only these keys (#1,#2):"
2229
+ },
2230
+ {
2231
+ key: "limit",
2232
+ flag: "--limit",
2233
+ type: "input",
2234
+ message: "Read at most this many issues (a trial run):"
2235
+ },
2236
+ {
2237
+ key: "order",
2238
+ flag: "--order",
2239
+ type: "select",
2240
+ choices: ["oldest", "newest"],
2241
+ default: "oldest",
2242
+ message: "Which end of the creation order:"
2229
2243
  }
2230
2244
  ],
2231
2245
  skipOptions: [
@@ -2264,6 +2278,20 @@ const migrateProjectEntry = {
2264
2278
  flag: "--template",
2265
2279
  type: "input",
2266
2280
  message: "Board template to make a missing board from (default roadmap):"
2281
+ },
2282
+ {
2283
+ key: "limit",
2284
+ flag: "--limit",
2285
+ type: "input",
2286
+ message: "Read at most this many issues (a trial run):"
2287
+ },
2288
+ {
2289
+ key: "order",
2290
+ flag: "--order",
2291
+ type: "select",
2292
+ choices: ["oldest", "newest"],
2293
+ default: "oldest",
2294
+ message: "Which end of the creation order:"
2267
2295
  }
2268
2296
  ],
2269
2297
  skipOptions: [
@@ -2782,6 +2810,20 @@ const registry = createCommandRegistry([
2782
2810
  flag: "--since",
2783
2811
  type: "input",
2784
2812
  message: "Only issues changed since (7d, 2026-03-01):"
2813
+ },
2814
+ {
2815
+ key: "limit",
2816
+ flag: "--limit",
2817
+ type: "input",
2818
+ message: "Read at most this many issues (a trial run):"
2819
+ },
2820
+ {
2821
+ key: "order",
2822
+ flag: "--order",
2823
+ type: "select",
2824
+ choices: ["oldest", "newest"],
2825
+ default: "oldest",
2826
+ message: "Which end of the creation order:"
2785
2827
  }
2786
2828
  ],
2787
2829
  skipOptions: ["yes"],
@@ -11146,6 +11188,17 @@ const menuCommand = (version) => ({
11146
11188
  await launchMenu([...COMMAND_REGISTRY, ...runEntries], argv);
11147
11189
  }
11148
11190
  });
11191
+ // src/commands/migrate/parse-limit/parse-limit.ts
11192
+ /**
11193
+ * Reads `--limit`: a positive whole number, or undefined when the flag was not given. Anything else (zero, a negative
11194
+ * number, a fraction, text) is a `ConfigError` that names the command and the value, so a typo never reads as "no limit".
11195
+ */
11196
+ function parseLimit(value, command) {
11197
+ if (value === void 0) return void 0;
11198
+ const text = String(value).trim();
11199
+ if (!/^[1-9]\d*$/.test(text) || !Number.isSafeInteger(Number(text))) throw new ConfigError$1(`${command}: --limit "${text}" is not a positive whole number`);
11200
+ return Number(text);
11201
+ }
11149
11202
  // src/commands/migrate/collect-records/collect-records.ts
11150
11203
  /** An empty template: a board's items are read for their keys, status and priority, not judged against statuses. */
11151
11204
  const NO_TEMPLATE = {
@@ -11173,20 +11226,29 @@ async function collectRecords(input) {
11173
11226
  ok: false,
11174
11227
  reason: `the \`${source.provider}\` provider cannot export issues`
11175
11228
  };
11229
+ const info = input.onProgress ? { onProgress: input.onProgress } : {};
11230
+ const read = (selector) => input.limit === void 0 ? input.onProgress ? issues.export(selector, info) : issues.export(selector) : issues.export({
11231
+ ...selector,
11232
+ limit: input.limit,
11233
+ order: input.order ?? "oldest"
11234
+ }, info);
11235
+ const limited = (records, notes, matched = info.matched) => ({
11236
+ ok: true,
11237
+ records,
11238
+ notes,
11239
+ ...input.limit === void 0 ? {} : { limit: input.limit },
11240
+ ...input.limit !== void 0 && matched !== void 0 ? { matched } : {}
11241
+ });
11176
11242
  try {
11177
11243
  if (scope.kind === "issue") return {
11178
11244
  ok: true,
11179
11245
  records: await issues.export({ keys: [scope.key] }),
11180
11246
  notes: []
11181
11247
  };
11182
- if (scope.kind === "issues") return {
11183
- ok: true,
11184
- records: await issues.export({
11185
- ...scope.selector,
11186
- ...input.openOnly ? { openOnly: true } : {}
11187
- }),
11188
- notes: []
11189
- };
11248
+ if (scope.kind === "issues") return limited(await read({
11249
+ ...scope.selector,
11250
+ ...input.openOnly ? { openOnly: true } : {}
11251
+ }), []);
11190
11252
  const projects = source.projects;
11191
11253
  if (!projects?.items) return {
11192
11254
  ok: false,
@@ -11201,11 +11263,7 @@ async function collectRecords(input) {
11201
11263
  const local = items.filter((i) => !i.key.includes("/"));
11202
11264
  const notes = items.length > local.length ? [`${items.length - local.length} item(s) from other repositories were skipped`] : [];
11203
11265
  const byKey = new Map(local.map((i) => [i.key, i]));
11204
- return {
11205
- ok: true,
11206
- records: (await issues.export({ keys: local.map((i) => i.key) })).map((r) => overlay(r, byKey.get(r.key))),
11207
- notes
11208
- };
11266
+ return limited((await read({ keys: local.map((i) => i.key) })).map((r) => overlay(r, byKey.get(r.key))), notes, info.matched ?? local.length);
11209
11267
  } catch (err) {
11210
11268
  return {
11211
11269
  ok: false,
@@ -11222,6 +11280,14 @@ function overlay(record, item) {
11222
11280
  ...!record.priority && item.priority ? { priority: item.priority } : {}
11223
11281
  };
11224
11282
  }
11283
+ // src/commands/migrate/describe-limit/describe-limit.ts
11284
+ /**
11285
+ * The line a limited read prints, in a dry run and a real one: `limited to 2 of 7 (oldest created)`, or without the
11286
+ * total when the provider could not say how many the selection matched. `read` is how many records came back.
11287
+ */
11288
+ function describeLimit(read, matched, order = "oldest") {
11289
+ return `limited to ${read}${matched === void 0 ? "" : ` of ${matched}`} (${order} created)`;
11290
+ }
11225
11291
  // src/commands/migrate/open-side/open-side.ts
11226
11292
  /**
11227
11293
  * Loads one provider for a migration. `issues` is a single provider in a config, so each side gets its own loader over
@@ -11418,6 +11484,7 @@ function tallyDropped(results) {
11418
11484
  */
11419
11485
  async function runMigrate(input) {
11420
11486
  const print = input.print ?? ((line) => console.log(line));
11487
+ const progress = input.progress ?? createProgress(print);
11421
11488
  const stop = (status, reason) => {
11422
11489
  print(statusRow(status, ["migrate", reason]));
11423
11490
  return {
@@ -11466,14 +11533,20 @@ async function runMigrate(input) {
11466
11533
  template: resolved.template
11467
11534
  };
11468
11535
  }
11469
- const collected = await collectRecords({
11536
+ const reading = `Reading issues from ${source.provider}…`;
11537
+ const collected = await progress.run(reading, (update) => collectRecords({
11470
11538
  source,
11471
11539
  scope: input.scope,
11472
- openOnly: input.openOnly
11473
- });
11540
+ openOnly: input.openOnly,
11541
+ limit: input.limit,
11542
+ order: input.order,
11543
+ onProgress: (done, total) => update(`${reading} ${done} of ${total}`)
11544
+ }));
11474
11545
  if (!collected.ok) return stop(collected.reason.startsWith("the `") ? "skip" : "fail", collected.reason);
11475
11546
  const { records, notes } = collected;
11476
11547
  for (const note of notes) print(statusRow("skip", ["migrate", note]));
11548
+ const limited = collected.limit === void 0 ? void 0 : describeLimit(records.length, collected.matched, input.order);
11549
+ if (limited) print(statusRow("skip", ["migrate", limited]));
11477
11550
  if (records.length === 0) return stop("skip", "nothing to migrate");
11478
11551
  const dryRun = Boolean(input.context.dryRun);
11479
11552
  const milestone = input.milestone ?? (projectScope && !plan ? projectScope.name : void 0);
@@ -11489,10 +11562,12 @@ async function runMigrate(input) {
11489
11562
  }
11490
11563
  }
11491
11564
  try {
11492
- const results = await importer.import(records, {
11565
+ const writing = dryRun ? `Checking ${target.provider}…` : `Writing to ${target.provider}…`;
11566
+ const results = await progress.run(writing, (update) => importer.import(records, {
11493
11567
  ...milestone ? { milestone } : {},
11494
- dryRun
11495
- });
11568
+ dryRun,
11569
+ onProgress: (done, total) => update(`${writing} ${done} of ${total}`)
11570
+ }));
11496
11571
  for (const r of results) {
11497
11572
  const state = !r.created ? "already migrated" : dryRun ? "would create" : "created";
11498
11573
  print(statusRow(r.created ? "ok" : "skip", ["migrate", `${r.source} → ${r.key ?? "(new)"} (${state})`]));
@@ -11501,12 +11576,12 @@ async function runMigrate(input) {
11501
11576
  print(statusRow(dryRun ? "skip" : "ok", ["migrate", `${where}: ${dryRun ? "dry run, nothing written; would create" : "created"} ${created}, skipped ${results.length - created}`]));
11502
11577
  let placement;
11503
11578
  if (plan) {
11504
- placement = await placeOnBoard({
11579
+ placement = await progress.run(`Placing issues on the ${plan.name} board…`, () => placeOnBoard({
11505
11580
  ...plan,
11506
11581
  records,
11507
11582
  results,
11508
11583
  dryRun
11509
- });
11584
+ }));
11510
11585
  printBoard({
11511
11586
  print,
11512
11587
  name: plan.name,
@@ -11526,7 +11601,8 @@ async function runMigrate(input) {
11526
11601
  status: "ok",
11527
11602
  results,
11528
11603
  notCarried,
11529
- ...placement ? { board: placement } : {}
11604
+ ...placement ? { board: placement } : {},
11605
+ ...limited ? { limited } : {}
11530
11606
  };
11531
11607
  } catch (err) {
11532
11608
  return stop("fail", `${describeError(err)} (a second run continues where this stopped)`);
@@ -11535,6 +11611,7 @@ async function runMigrate(input) {
11535
11611
  // src/commands/migrate/migrate-handler/migrate-handler.ts
11536
11612
  /** What each subcommand does after yargs: load the config and tokens, build its scope from the org, run, set the exit code. */
11537
11613
  async function handleMigrate(argv, scope) {
11614
+ const limit = parseLimit(argv.limit, "migrate");
11538
11615
  const tokens = tokenContext$1(argv.token);
11539
11616
  if (!tokens) return;
11540
11617
  const loaded = await loadConfig(argv.cwd);
@@ -11552,6 +11629,10 @@ async function handleMigrate(argv, scope) {
11552
11629
  to: argv.to,
11553
11630
  scope: scope(org ?? ""),
11554
11631
  ...argv.openOnly ? { openOnly: true } : {},
11632
+ ...limit === void 0 ? {} : {
11633
+ limit,
11634
+ order: argv.order
11635
+ },
11555
11636
  ...argv.milestone ? { milestone: argv.milestone } : {},
11556
11637
  ...argv.template ? { template: argv.template } : {},
11557
11638
  ...argv.yes ? { yes: true } : {}
@@ -11591,11 +11672,25 @@ const migrateIssueCommand = {
11591
11672
  key: argv.key
11592
11673
  }))
11593
11674
  };
11675
+ // src/commands/migrate/limit-options/limit-options.ts
11676
+ /**
11677
+ * The options that cap how many issues are read from the source: `--limit` and `--order`. Shared by `migrate issues`,
11678
+ * `migrate project` and `sync issues`; `migrate issue` names one issue and has neither.
11679
+ */
11680
+ const limitOptions = (y) => y.option("limit", {
11681
+ type: "string",
11682
+ describe: "Read at most this many issues from the source (a positive whole number), for a trial run"
11683
+ }).option("order", {
11684
+ type: "string",
11685
+ choices: ["oldest", "newest"],
11686
+ default: "oldest",
11687
+ describe: "With --limit, which end of the creation order to read: the first created or the last created"
11688
+ });
11594
11689
  // src/commands/migrate/migrate-issues/migrate-issues.command.ts
11595
11690
  const migrateIssuesCommand = {
11596
11691
  command: "issues",
11597
11692
  describe: "Move several issues: every issue (--all), the issues of a milestone or project, or a list of keys",
11598
- builder: (y) => migrateOptions(y).option("all", {
11693
+ builder: (y) => limitOptions(migrateOptions(y)).option("all", {
11599
11694
  type: "boolean",
11600
11695
  describe: "Every issue the source is configured for"
11601
11696
  }).option("source-milestone", {
@@ -11622,7 +11717,7 @@ const migrateIssuesCommand = {
11622
11717
  const migrateProjectCommand = {
11623
11718
  command: "project <name>",
11624
11719
  describe: "Move a board's issues to another tracker, with the board's status and priority; they land on a board of the same name (GitHub) or in a project of that name (Linear)",
11625
- builder: (y) => migrateOptions(y).positional("name", {
11720
+ builder: (y) => limitOptions(migrateOptions(y)).positional("name", {
11626
11721
  type: "string",
11627
11722
  demandOption: true,
11628
11723
  describe: "The board in the source tracker, by name"
@@ -23945,6 +24040,7 @@ function parseSince(value, now = Date.now()) {
23945
24040
  */
23946
24041
  async function runSyncIssues(input) {
23947
24042
  const print = input.print ?? ((line) => console.log(line));
24043
+ const progress = input.progress ?? createProgress(print);
23948
24044
  const row = (status, text) => print(statusRow(status, ["sync issues", text]));
23949
24045
  const stop = (status, reason) => {
23950
24046
  row(status, reason);
@@ -23976,7 +24072,8 @@ async function runSyncIssues(input) {
23976
24072
  if (!target.ok) return stop("fail", `target: ${target.reason}`);
23977
24073
  const syncer = target.issues;
23978
24074
  if (!syncer?.sync) return stop("skip", `the \`${target.provider}\` provider cannot be a sync target`);
23979
- const collected = await collectRecords({
24075
+ const reading = `Reading issues from ${source.provider}…`;
24076
+ const collected = await progress.run(reading, (update) => collectRecords({
23980
24077
  source,
23981
24078
  scope: {
23982
24079
  kind: "issues",
@@ -23984,10 +24081,15 @@ async function runSyncIssues(input) {
23984
24081
  all: true,
23985
24082
  ...input.since ? { since: input.since } : {}
23986
24083
  }
23987
- }
23988
- });
24084
+ },
24085
+ limit: input.limit,
24086
+ order: input.order,
24087
+ onProgress: (done, total) => update(`${reading} ${done} of ${total}`)
24088
+ }));
23989
24089
  if (!collected.ok) return stop(collected.reason.startsWith("the `") ? "skip" : "fail", collected.reason);
23990
24090
  const { records } = collected;
24091
+ const limited = collected.limit === void 0 ? void 0 : describeLimit(records.length, collected.matched, input.order);
24092
+ if (limited) row("skip", limited);
23991
24093
  if (records.length === 0) return stop("skip", "nothing to sync");
23992
24094
  const guarded = records.filter((r) => r.migratedFrom !== void 0);
23993
24095
  const toSync = records.filter((r) => r.migratedFrom === void 0);
@@ -24006,7 +24108,11 @@ async function runSyncIssues(input) {
24006
24108
  }
24007
24109
  }
24008
24110
  try {
24009
- results = await syncer.sync(toSync, { dryRun });
24111
+ const writing = dryRun ? `Checking ${target.provider}…` : `Writing to ${target.provider}…`;
24112
+ results = await progress.run(writing, (update) => syncer.sync(toSync, {
24113
+ dryRun,
24114
+ onProgress: (done, total) => update(`${writing} ${done} of ${total}`)
24115
+ }));
24010
24116
  } catch (err) {
24011
24117
  return stop("fail", `${describeError(err)} (a second run continues where this stopped)`);
24012
24118
  }
@@ -24033,14 +24139,15 @@ async function runSyncIssues(input) {
24033
24139
  status: "ok",
24034
24140
  results,
24035
24141
  counts,
24036
- notCarried
24142
+ notCarried,
24143
+ ...limited ? { limited } : {}
24037
24144
  };
24038
24145
  }
24039
24146
  // src/commands/sync-issues/sync-issues.command.ts
24040
24147
  const syncIssuesCommand = {
24041
24148
  command: "issues",
24042
24149
  describe: "Keep issues on one tracker up to date from another, one direction: create what is missing, update what a sync made, add comments",
24043
- builder: (y) => y.option("from", {
24150
+ builder: (y) => limitOptions(y).option("from", {
24044
24151
  type: "string",
24045
24152
  demandOption: true,
24046
24153
  describe: "Where the issues are read from (never written): `provider` or `provider:key=value,...`"
@@ -24057,6 +24164,7 @@ const syncIssuesCommand = {
24057
24164
  }),
24058
24165
  handler: async (argv) => {
24059
24166
  const since = argv.since ? parseSince(argv.since) : void 0;
24167
+ const limit = parseLimit(argv.limit, "sync issues");
24060
24168
  const tokens = tokenContext$1(argv.token);
24061
24169
  if (!tokens) return;
24062
24170
  const loaded = await loadConfig(argv.cwd);
@@ -24073,6 +24181,10 @@ const syncIssuesCommand = {
24073
24181
  from: argv.from,
24074
24182
  to: argv.to,
24075
24183
  ...since ? { since } : {},
24184
+ ...limit === void 0 ? {} : {
24185
+ limit,
24186
+ order: argv.order
24187
+ },
24076
24188
  ...argv.yes ? { yes: true } : {}
24077
24189
  })).status === "fail") process.exitCode = 1;
24078
24190
  }