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

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`.
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 = {};
11230
+ const read = (selector) => input.limit === void 0 ? 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
@@ -11469,11 +11535,15 @@ async function runMigrate(input) {
11469
11535
  const collected = await collectRecords({
11470
11536
  source,
11471
11537
  scope: input.scope,
11472
- openOnly: input.openOnly
11538
+ openOnly: input.openOnly,
11539
+ limit: input.limit,
11540
+ order: input.order
11473
11541
  });
11474
11542
  if (!collected.ok) return stop(collected.reason.startsWith("the `") ? "skip" : "fail", collected.reason);
11475
11543
  const { records, notes } = collected;
11476
11544
  for (const note of notes) print(statusRow("skip", ["migrate", note]));
11545
+ const limited = collected.limit === void 0 ? void 0 : describeLimit(records.length, collected.matched, input.order);
11546
+ if (limited) print(statusRow("skip", ["migrate", limited]));
11477
11547
  if (records.length === 0) return stop("skip", "nothing to migrate");
11478
11548
  const dryRun = Boolean(input.context.dryRun);
11479
11549
  const milestone = input.milestone ?? (projectScope && !plan ? projectScope.name : void 0);
@@ -11526,7 +11596,8 @@ async function runMigrate(input) {
11526
11596
  status: "ok",
11527
11597
  results,
11528
11598
  notCarried,
11529
- ...placement ? { board: placement } : {}
11599
+ ...placement ? { board: placement } : {},
11600
+ ...limited ? { limited } : {}
11530
11601
  };
11531
11602
  } catch (err) {
11532
11603
  return stop("fail", `${describeError(err)} (a second run continues where this stopped)`);
@@ -11535,6 +11606,7 @@ async function runMigrate(input) {
11535
11606
  // src/commands/migrate/migrate-handler/migrate-handler.ts
11536
11607
  /** What each subcommand does after yargs: load the config and tokens, build its scope from the org, run, set the exit code. */
11537
11608
  async function handleMigrate(argv, scope) {
11609
+ const limit = parseLimit(argv.limit, "migrate");
11538
11610
  const tokens = tokenContext$1(argv.token);
11539
11611
  if (!tokens) return;
11540
11612
  const loaded = await loadConfig(argv.cwd);
@@ -11552,6 +11624,10 @@ async function handleMigrate(argv, scope) {
11552
11624
  to: argv.to,
11553
11625
  scope: scope(org ?? ""),
11554
11626
  ...argv.openOnly ? { openOnly: true } : {},
11627
+ ...limit === void 0 ? {} : {
11628
+ limit,
11629
+ order: argv.order
11630
+ },
11555
11631
  ...argv.milestone ? { milestone: argv.milestone } : {},
11556
11632
  ...argv.template ? { template: argv.template } : {},
11557
11633
  ...argv.yes ? { yes: true } : {}
@@ -11591,11 +11667,25 @@ const migrateIssueCommand = {
11591
11667
  key: argv.key
11592
11668
  }))
11593
11669
  };
11670
+ // src/commands/migrate/limit-options/limit-options.ts
11671
+ /**
11672
+ * The options that cap how many issues are read from the source: `--limit` and `--order`. Shared by `migrate issues`,
11673
+ * `migrate project` and `sync issues`; `migrate issue` names one issue and has neither.
11674
+ */
11675
+ const limitOptions = (y) => y.option("limit", {
11676
+ type: "string",
11677
+ describe: "Read at most this many issues from the source (a positive whole number), for a trial run"
11678
+ }).option("order", {
11679
+ type: "string",
11680
+ choices: ["oldest", "newest"],
11681
+ default: "oldest",
11682
+ describe: "With --limit, which end of the creation order to read: the first created or the last created"
11683
+ });
11594
11684
  // src/commands/migrate/migrate-issues/migrate-issues.command.ts
11595
11685
  const migrateIssuesCommand = {
11596
11686
  command: "issues",
11597
11687
  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", {
11688
+ builder: (y) => limitOptions(migrateOptions(y)).option("all", {
11599
11689
  type: "boolean",
11600
11690
  describe: "Every issue the source is configured for"
11601
11691
  }).option("source-milestone", {
@@ -11622,7 +11712,7 @@ const migrateIssuesCommand = {
11622
11712
  const migrateProjectCommand = {
11623
11713
  command: "project <name>",
11624
11714
  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", {
11715
+ builder: (y) => limitOptions(migrateOptions(y)).positional("name", {
11626
11716
  type: "string",
11627
11717
  demandOption: true,
11628
11718
  describe: "The board in the source tracker, by name"
@@ -23984,10 +24074,14 @@ async function runSyncIssues(input) {
23984
24074
  all: true,
23985
24075
  ...input.since ? { since: input.since } : {}
23986
24076
  }
23987
- }
24077
+ },
24078
+ limit: input.limit,
24079
+ order: input.order
23988
24080
  });
23989
24081
  if (!collected.ok) return stop(collected.reason.startsWith("the `") ? "skip" : "fail", collected.reason);
23990
24082
  const { records } = collected;
24083
+ const limited = collected.limit === void 0 ? void 0 : describeLimit(records.length, collected.matched, input.order);
24084
+ if (limited) row("skip", limited);
23991
24085
  if (records.length === 0) return stop("skip", "nothing to sync");
23992
24086
  const guarded = records.filter((r) => r.migratedFrom !== void 0);
23993
24087
  const toSync = records.filter((r) => r.migratedFrom === void 0);
@@ -24033,14 +24127,15 @@ async function runSyncIssues(input) {
24033
24127
  status: "ok",
24034
24128
  results,
24035
24129
  counts,
24036
- notCarried
24130
+ notCarried,
24131
+ ...limited ? { limited } : {}
24037
24132
  };
24038
24133
  }
24039
24134
  // src/commands/sync-issues/sync-issues.command.ts
24040
24135
  const syncIssuesCommand = {
24041
24136
  command: "issues",
24042
24137
  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", {
24138
+ builder: (y) => limitOptions(y).option("from", {
24044
24139
  type: "string",
24045
24140
  demandOption: true,
24046
24141
  describe: "Where the issues are read from (never written): `provider` or `provider:key=value,...`"
@@ -24057,6 +24152,7 @@ const syncIssuesCommand = {
24057
24152
  }),
24058
24153
  handler: async (argv) => {
24059
24154
  const since = argv.since ? parseSince(argv.since) : void 0;
24155
+ const limit = parseLimit(argv.limit, "sync issues");
24060
24156
  const tokens = tokenContext$1(argv.token);
24061
24157
  if (!tokens) return;
24062
24158
  const loaded = await loadConfig(argv.cwd);
@@ -24073,6 +24169,10 @@ const syncIssuesCommand = {
24073
24169
  from: argv.from,
24074
24170
  to: argv.to,
24075
24171
  ...since ? { since } : {},
24172
+ ...limit === void 0 ? {} : {
24173
+ limit,
24174
+ order: argv.order
24175
+ },
24076
24176
  ...argv.yes ? { yes: true } : {}
24077
24177
  })).status === "fail") process.exitCode = 1;
24078
24178
  }