@theholocron/cli 5.0.0-alpha.403 → 5.0.0-alpha.405

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
@@ -307,6 +307,10 @@ these functions unchanged, gathering the same inputs over the GitHub API
307
307
  instead (D8 — one derivation, two input sources, not two
308
308
  implementations).
309
309
 
310
+ A provider's `Errors.describe()` returns `envKeys` (always pushed to repo secrets by `holocron repo setup`) and an optional
311
+ `frameworkEnvKeys` (`{ next: ["NEXT_PUBLIC_SENTRY_DSN"] }`), keyed by a `StackName` from `deriveStack()` and pushed only when
312
+ the root or a workspace package depends on that framework.
313
+
310
314
  `missingCapabilities(capabilities)` is `deriveCompliance()`'s sibling —
311
315
  same `REQUIRED_BASELINE` table, but returns _which_ required capabilities
312
316
  are absent rather than whether any are. `@theholocron/sentinel`'s
package/dist/cli.mjs CHANGED
@@ -9794,6 +9794,7 @@ function deriveProfile(input) {
9794
9794
  if (pkg?.private) return "app";
9795
9795
  return "library";
9796
9796
  }
9797
+ /** The framework and build-tool names `deriveStack()` can detect, in the order it lists them; `StackName` is derived from it. */
9797
9798
  const KNOWN_STACK_DEPS = [
9798
9799
  "next",
9799
9800
  "vite",
@@ -11228,7 +11229,8 @@ async function runSmokeCheck(key, provider, impl) {
11228
11229
  const who = errors.whoami ? await errors.whoami() : null;
11229
11230
  if (who) return mk(key, provider, "ok", `org: ${who.org}`);
11230
11231
  const desc = await errors.describe();
11231
- return mk(key, provider, "ok", `provider: ${desc.provider}; env keys: ${desc.envKeys.join(", ")}`);
11232
+ const keys = [...desc.envKeys, ...Object.entries(desc.frameworkEnvKeys ?? {}).flatMap(([framework, extra]) => extra?.length ? [`${extra.join(", ")} (with ${framework})`] : [])];
11233
+ return mk(key, provider, "ok", `provider: ${desc.provider}; env keys: ${keys.join(", ")}`);
11232
11234
  }
11233
11235
  case "logs": {
11234
11236
  const logs = impl;
@@ -11728,6 +11730,99 @@ function resolveIdeasProvider(resolved, env) {
11728
11730
  }
11729
11731
  };
11730
11732
  }
11733
+ // src/commands/ideas-sync/run-ideas-sync/oldest-issue-key/oldest-issue-key.ts
11734
+ /**
11735
+ * The key of the oldest issue among `keys`, which is the one that wins when overlapping runs filed the same idea.
11736
+ * The `Issue` type carries no creation time, so the order is the key's number (its last run of digits: `#12`, `ENG-7`
11737
+ * and `owner/repo#12` give 12, 7 and 12), which rises with creation in one repository or team; a key with no number
11738
+ * sorts last. Two keys with the same number (different repositories) fall back to a plain string compare so every run
11739
+ * picks the same winner from the same set. Returns `undefined` for an empty list.
11740
+ */
11741
+ function oldestIssueKey(keys) {
11742
+ const numberOf = (key) => {
11743
+ const digits = /(\d+)\D*$/.exec(key);
11744
+ return digits ? Number(digits[1]) : Number.POSITIVE_INFINITY;
11745
+ };
11746
+ let oldest;
11747
+ for (const key of keys) {
11748
+ if (oldest === void 0) {
11749
+ oldest = key;
11750
+ continue;
11751
+ }
11752
+ const a = numberOf(key);
11753
+ const b = numberOf(oldest);
11754
+ if (a < b || a === b && key < oldest) oldest = key;
11755
+ }
11756
+ return oldest;
11757
+ }
11758
+ // src/commands/ideas-sync/run-ideas-sync/pick-canonical-issue/pick-canonical-issue.ts
11759
+ /**
11760
+ * The issue that stands for an idea among the issues that carry its marker: the oldest open one (by
11761
+ * {@link oldestIssueKey}), or, when every one is closed, the oldest of all, because an issue closed on purpose still
11762
+ * means the idea was filed. A closed duplicate that a search lists first therefore never replaces the open issue.
11763
+ * Returns `undefined` for an empty list.
11764
+ */
11765
+ function pickCanonicalIssue(hits) {
11766
+ const open = hits.filter((issue) => issue.statusCategory !== "done");
11767
+ const pool = open.length > 0 ? open : hits;
11768
+ const key = oldestIssueKey(pool.map((issue) => issue.key));
11769
+ return pool.find((issue) => issue.key === key);
11770
+ }
11771
+ // src/commands/ideas-sync/run-ideas-sync/converge-created-issue/converge-created-issue.ts
11772
+ /**
11773
+ * Makes the creation of an issue converge when two runs file the same idea at the same time. Both runs searched for
11774
+ * the marker before either created, so both created; each now searches again, and the oldest issue carrying the exact
11775
+ * `marker` (by {@link pickCanonicalIssue}: the oldest open one) is the winner. Both runs see the same issues, so they pick the same winner: the
11776
+ * run whose issue is the oldest keeps it, and the other comments on its own issue and closes it (`transition` to
11777
+ * `done`; the `Issues` capability has no closed-as-duplicate state), then reports the winner's key. Nothing here throws.
11778
+ * When a winner other than `created` is known, its key is always the one returned, so the note points at the canonical
11779
+ * issue even if commenting or closing the duplicate does not go through (then `warning` is set and the detail names
11780
+ * both keys). When the search itself does not go through no winner is known, so `created` is returned with a warning,
11781
+ * because a created issue is never left out of the note.
11782
+ *
11783
+ * @param issues - The tracker; only `search`, `comment` and `transition` are used.
11784
+ * @param marker - The exact hidden marker line of the idea, as written in the issue body.
11785
+ * @param created - The key of the issue this run has just created.
11786
+ */
11787
+ async function convergeCreatedIssue(issues, marker, created) {
11788
+ let candidates;
11789
+ try {
11790
+ candidates = (await issues.search({
11791
+ text: marker,
11792
+ limit: 100
11793
+ })).filter((issue) => issue.body?.includes(marker) && issue.key !== created);
11794
+ } catch (err) {
11795
+ return {
11796
+ key: created,
11797
+ warning: true,
11798
+ detail: `filed as ${created}; could not check for a duplicate from an overlapping run (${describeError(err)}), so look for another issue with the same marker and close one by hand`
11799
+ };
11800
+ }
11801
+ const winner = pickCanonicalIssue([...candidates, {
11802
+ key: created,
11803
+ statusCategory: "open"
11804
+ }]).key;
11805
+ if (winner === created) return {
11806
+ key: created,
11807
+ warning: false,
11808
+ detail: `filed as ${created}`
11809
+ };
11810
+ try {
11811
+ await issues.comment(created, `Duplicate of ${winner}: the same idea was filed by two overlapping runs.`);
11812
+ await issues.transition(created, "done");
11813
+ } catch (err) {
11814
+ return {
11815
+ key: winner,
11816
+ warning: true,
11817
+ detail: `filed as ${winner}, the older issue for the idea, but the duplicate ${created} could not be closed (${describeError(err)}); close ${created} by hand`
11818
+ };
11819
+ }
11820
+ return {
11821
+ key: winner,
11822
+ warning: false,
11823
+ detail: `filed as ${winner} (closed duplicate ${created} from an overlapping run)`
11824
+ };
11825
+ }
11731
11826
  // src/commands/ideas-sync/run-ideas-sync/run-ideas-sync.ts
11732
11827
  /**
11733
11828
  * `holocron ideas sync` — files the idea notes that are ready.
@@ -11741,7 +11836,9 @@ function resolveIdeasProvider(resolved, env) {
11741
11836
  * with a hidden `<!-- holocron:idea <key> -->` line, and an issue that carries it is reused instead of making a second
11742
11837
  * one (found with one `Issues.search({ text })` per note about to be filed, confirmed by the exact marker in the body;
11743
11838
  * GitHub searches its 2000 most recently updated issues, so an older one is still missed, and each search uses rate
11744
- * limit). It never deletes anything, and an idea it cannot file is a
11839
+ * limit). Two runs that overlap can both miss the marker and both create; each then searches once more after its
11840
+ * create (`convergeCreatedIssue()`), the older issue wins and the other run closes its own with a comment, so both
11841
+ * notes end with one key. It never deletes anything, and an idea it cannot file is a
11745
11842
  * failing row (the run goes on). It writes, so it asks first unless `--dry-run` or `--yes` (without a terminal it refuses instead).
11746
11843
  */
11747
11844
  /** The state that files a note when the config names none. */
@@ -11760,12 +11857,6 @@ const row = (id, status, detail) => ({
11760
11857
  const marker = (key) => `<!-- holocron:idea ${key} -->`;
11761
11858
  /** The issue's body: the idea's text, the line that traces the issue to its idea, and the hidden marker. */
11762
11859
  const issueBody = (idea) => `${idea.body.trim()}\n\nFiled from idea: ${idea.title}\n${marker(idea.key)}`;
11763
- /**
11764
- * How many text matches are read back per note; the exact marker is then checked in each body. The search itself is
11765
- * bounded by the provider: GitHub pages up to 2000 recent issues (20 pages of 100) and filters them client-side, so an
11766
- * issue older than that is still missed, and each search spends rate limit. Linear filters on the server.
11767
- */
11768
- const SEARCH_LIMIT = 20;
11769
11860
  async function runIdeasSync(input) {
11770
11861
  /* v8 ignore next -- the console is only used outside tests, which inject `print` */
11771
11862
  const print = input.print ?? ((line) => console.log(line));
@@ -11842,28 +11933,37 @@ async function runIdeasSync(input) {
11842
11933
  }
11843
11934
  let existing;
11844
11935
  try {
11845
- existing = (await issues.search({
11936
+ existing = pickCanonicalIssue((await issues.search({
11846
11937
  text: marker(path),
11847
- limit: SEARCH_LIMIT
11848
- })).find((issue) => issue.body?.includes(marker(path)));
11938
+ limit: 100
11939
+ })).filter((issue) => issue.body?.includes(marker(path))));
11849
11940
  } catch (err) {
11850
11941
  rows.push(row(path, "fail", `could not check for an existing issue, so none was created: ${describeError(err)}`));
11851
11942
  continue;
11852
11943
  }
11853
11944
  let key;
11945
+ let detail = `already filed as ${existing?.key}`;
11946
+ let warning = false;
11854
11947
  if (existing) key = existing.key;
11855
- else try {
11856
- ({key} = await issues.create({
11857
- summary: idea.title,
11858
- body: issueBody(idea)
11859
- }));
11860
- } catch (err) {
11861
- rows.push(row(path, "fail", `could not create the issue: ${describeError(err)}`));
11862
- continue;
11948
+ else {
11949
+ let created;
11950
+ try {
11951
+ ({key: created} = await issues.create({
11952
+ summary: idea.title,
11953
+ body: issueBody(idea)
11954
+ }));
11955
+ } catch (err) {
11956
+ rows.push(row(path, "fail", `could not create the issue: ${describeError(err)}`));
11957
+ continue;
11958
+ }
11959
+ ({key, detail, warning} = await convergeCreatedIssue(issues, marker(path), created));
11863
11960
  }
11864
11961
  try {
11865
11962
  await ideas.markFiled(path, key);
11866
- rows.push(row(path, "ok", `${existing ? "already filed" : "filed"} as ${key}`));
11963
+ rows.push({
11964
+ ...row(path, "ok", detail),
11965
+ problems: warning ? ["a duplicate issue for this idea may be open: close the extra one by hand"] : []
11966
+ });
11867
11967
  } catch (err) {
11868
11968
  rows.push({
11869
11969
  ...row(path, "fail", `issue ${key} was created but \`issue:\` was not written: ${describeError(err)}`),
@@ -20305,6 +20405,16 @@ async function installAgentPrompts({ repoRoot }) {
20305
20405
  });
20306
20406
  return `wrote ${Object.keys(AGENT_PROMPTS).length} prompt files to ${AGENTS_PROMPTS_ROOT}/`;
20307
20407
  }
20408
+ // src/commands/setup/derive-repo-stack/derive-repo-stack.ts
20409
+ /**
20410
+ * The stack of a whole repo: `deriveStack()` of the root `package.json` and of
20411
+ * every workspace package's, unioned (in `KNOWN_STACK_DEPS` order, no repeats).
20412
+ * A repo with no readable `package.json` has no stack.
20413
+ */
20414
+ function deriveRepoStack(rootPackageJson, workspacePackageJsons) {
20415
+ const found = new Set([rootPackageJson, ...workspacePackageJsons].flatMap((pkg) => deriveStack(pkg)));
20416
+ return KNOWN_STACK_DEPS.filter((name) => found.has(name));
20417
+ }
20308
20418
  // src/commands/setup/engineering.ts
20309
20419
  async function writeIfAbsent(filePath, content) {
20310
20420
  try {
@@ -20326,6 +20436,23 @@ async function installEngineeringStructure({ repoRoot }) {
20326
20436
  for (const [path, content] of writes) if (await writeIfAbsent(path, content)) results.push(path.replace(repoRoot + "/", ""));
20327
20437
  return results.length > 0 ? `created: ${results.join(", ")}` : "all files already exist — nothing to write";
20328
20438
  }
20439
+ // src/commands/setup/errors-env-keys/errors-env-keys.ts
20440
+ /**
20441
+ * The env keys `holocron repo setup` pushes a tracker's DSN under: the
20442
+ * provider's `envKeys` (always), then the `frameworkEnvKeys` of every
20443
+ * framework in the repo's detected `stack`; a repeated key is pushed once.
20444
+ * `unknown` lists the `frameworkEnvKeys` names that are not a known stack name
20445
+ * (a typo in a plugin), whose keys are never pushed, so the caller can say so.
20446
+ */
20447
+ function errorsEnvKeys(described, stack) {
20448
+ const extra = stack.flatMap((framework) => described.frameworkEnvKeys?.[framework] ?? []);
20449
+ const known = KNOWN_STACK_DEPS;
20450
+ const unknown = Object.keys(described.frameworkEnvKeys ?? {}).filter((name) => !known.includes(name));
20451
+ return {
20452
+ keys: [.../* @__PURE__ */ new Set([...described.envKeys, ...extra])],
20453
+ unknown
20454
+ };
20455
+ }
20329
20456
  // src/commands/setup/run-step/run-step.ts
20330
20457
  async function runStep(capability, step, dryRun, body, opts = {}) {
20331
20458
  const result = await execStep(capability, step, dryRun, body, opts);
@@ -21020,8 +21147,31 @@ async function runSetup(input) {
21020
21147
  print(formatStep(steps[steps.length - 1]));
21021
21148
  if (dsn && loader.has("secrets")) {
21022
21149
  const secrets = loader.get("secrets");
21023
- const { envKeys } = await errors.describe();
21024
- for (const key of envKeys) {
21150
+ const rootPackageJson = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
21151
+ let workspacePackageJsons = [];
21152
+ try {
21153
+ workspacePackageJsons = await readWorkspacePackageJsons(input.context.repoRoot, readWorkspacePackages(input.context.repoRoot));
21154
+ } catch (err) {
21155
+ steps.push({
21156
+ capability: "errors",
21157
+ step: "detect stack",
21158
+ status: "skip",
21159
+ message: `workspace packages not read (${errorMessage(err)}); using the root package.json only`
21160
+ });
21161
+ print(formatStep(steps[steps.length - 1]));
21162
+ }
21163
+ const stack = deriveRepoStack(rootPackageJson, workspacePackageJsons);
21164
+ const { keys, unknown } = errorsEnvKeys(await errors.describe(), stack);
21165
+ for (const name of unknown) {
21166
+ steps.push({
21167
+ capability: "errors",
21168
+ step: `frameworkEnvKeys ${name}`,
21169
+ status: "skip",
21170
+ message: `"${name}" is not a known framework name (${KNOWN_STACK_DEPS.join(", ")}); its keys are not pushed`
21171
+ });
21172
+ print(formatStep(steps[steps.length - 1]));
21173
+ }
21174
+ for (const key of keys) {
21025
21175
  steps.push(await runStep("errors", `secrets set ${key}`, dryRun, async () => {
21026
21176
  await secrets.setSecret({ kind: "repo" }, key, dsn);
21027
21177
  }));