@bensandee/tooling 0.103.0 → 0.104.0

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
@@ -119,6 +119,28 @@ Custom blocks are anchored to the nearest preceding non-blank line. When `repo:s
119
119
 
120
120
  To skip a workflow file entirely, add `# @bensandee/tooling:ignore` as the first line -- `repo:sync` will leave the file untouched.
121
121
 
122
+ ### Trusted runner label
123
+
124
+ By default every generated job runs on `ubuntu-latest`. Set `trustedRunner` in `.tooling.json` to a self-hosted runner label and the default-branch-only jobs move to it:
125
+
126
+ ```json
127
+ { "trustedRunner": "trusted" }
128
+ ```
129
+
130
+ | Job | File | Moves to the label |
131
+ | ------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
132
+ | `check` | `check.yml` (`simple`, `release-it`) / `ci.yml` (`changesets`) | Yes -- the push run on the default branch; pull request runs stay on `ubuntu-latest` |
133
+ | `release` | `release.yml` | Yes -- it only ever runs on the default branch |
134
+ | `post-release-hook` | `ci.yml` (`changesets`) / `release.yml` (`simple`) | Yes -- it only ever runs on the default branch |
135
+
136
+ Pull request jobs stay on `ubuntu-latest` even with the key set. The label itself is the boundary: the forge picks the runner before any step runs, so a job that reaches the shared pool never does so on the trusted runner's machine.
137
+
138
+ Three things to know before setting it:
139
+
140
+ - **Scope the runner.** A job runs on any runner whose label it can name, so the runner must be scoped so no other repository on the forge can name its label. Until it is, setting the key moves your secrets onto a machine other repos can claim.
141
+ - **A missing label hangs the job.** A job aimed at a label no runner serves waits forever. Set the key only once the runner exists and is serving that label.
142
+ - **The move is a workflow edit.** Generated workflows are rewritten on `repo:sync`; setting or removing the key changes nothing until the workflow is regenerated, and removing it likewise does nothing until then. An agent's edit to a generated workflow is held for an operator before it is pushed.
143
+
122
144
  ### pnpm-workspace.yaml
123
145
 
124
146
  `repo:sync` manages `pnpm-workspace.yaml` with a narrow contract -- mandated keys, a few seeded-on-creation keys, and everything else passed through verbatim.
package/dist/bin.mjs CHANGED
@@ -173,7 +173,7 @@ function loadEnvFileForBin(rawArgs, bin, io = processIo) {
173
173
  // src/env-file-preload.ts
174
174
  const envFileLoad = loadEnvFileForBin(process.argv.slice(2), {
175
175
  name: "bst",
176
- version: "0.103.0"
176
+ version: "0.104.0"
177
177
  });
178
178
  // ../cli-kit/src/logger.ts
179
179
  const RANK = {
@@ -846,6 +846,7 @@ const TolerantDockerCheckConfigSchema = z.object({
846
846
  });
847
847
  const DEFAULT_BRANCH_NAME_PATTERN = /^(?!refs\/)(?!.*\/\/)(?!.*\.\.)(?!.*\/$)(?!.*\.lock$)[A-Za-z0-9][A-Za-z0-9._/-]*$/;
848
848
  const DefaultBranchNameSchema = z.string().regex(DEFAULT_BRANCH_NAME_PATTERN, "must be a plain branch name: ASCII letters, digits, '.', '_', '-' and '/', starting with a letter or digit, with no leading 'refs/', no '//', '..', trailing '/', or '.lock' suffix");
849
+ const TrustedRunnerLabelSchema = z.string().regex(/^(?!ubuntu-latest$)[A-Za-z0-9][A-Za-z0-9._-]*$/, "must be a plain runner label: ASCII letters, digits, '.', '_' and '-', starting with a letter or digit, non-empty, and not 'ubuntu-latest' (the shared label this setting moves work off)");
849
850
  const AgentEnabledSliceSchema = z.looseObject({ agent: z.looseObject({ enabled: z.boolean().optional() }).optional() });
850
851
  function agentEnabledIn(raw) {
851
852
  try {
@@ -1802,6 +1803,7 @@ const ToolingConfigSchema = z.strictObject({
1802
1803
  deploy: DeployConfigSchema.optional().meta({ description: "Generate a deploy-dispatch step in the release workflow that triggers a workflow_dispatch event in another repo after a successful release. The resolved release token must have rights on `dispatchRepo`." }),
1803
1804
  pnpmWorkspace: z.literal(false).optional().meta({ description: "Set to false to opt out of pnpm-workspace.yaml management (skips both generation and the repo:sync --check validation)." }),
1804
1805
  defaultBranch: DefaultBranchNameSchema.optional().meta({ description: "Repository default branch name. Drives the generated CI `on.push` trigger and every default-branch gate in `ci.yml` and `release.yml`, the release path (`release:changesets`, the version PR, `release:trigger`) and `checks:run`'s coverage gate. Generated output uses 'main' when unset; `checks:run` still falls back to `origin/HEAD`. Must be a plain branch name: ASCII letters, digits, '.', '_', '-' and '/', with no leading 'refs/'." }),
1806
+ trustedRunner: TrustedRunnerLabelSchema.optional().meta({ description: "Self-hosted runner label for default-branch CI jobs: they run on this label while pull request jobs stay on 'ubuntu-latest'. Only a workflow edit moves a job, so the runner must be scoped so no other repository can name this label. A job aimed at a label no runner serves waits forever, so set this key only once the runner exists." }),
1805
1807
  unmanagedDevDependencies: UnmanagedDevDependenciesSchema.optional().meta({ description: "devDependency names repo:sync must never add or re-pin. Escape hatch for holding a tooling-managed dep (oxlint, vitest, knip, ...) at a deliberately off-canonical version; without it, repo:sync raises any managed devDep whose version has drifted below the canonical pin." }),
1806
1808
  stack: StackSchema.optional().meta({ description: "Whether the repo has TS/JS source. Detected from source evidence; TypeScript is never inferred from absence. Setting this key pins its value, even one that equals detection, and repo:sync keeps it until the key is deleted." }),
1807
1809
  builder: z.enum([
@@ -4820,6 +4822,10 @@ function branchNameLiteral(name) {
4820
4822
  if (DEFAULT_BRANCH_NAME_PATTERN.test(name)) return name;
4821
4823
  return name.replace(/'/g, "''");
4822
4824
  }
4825
+ const TrustedRunnerSliceSchema = z.object({ trustedRunner: TrustedRunnerLabelSchema.optional() });
4826
+ function configuredTrustedRunner(raw) {
4827
+ return parseToolingConfigSlice(raw, TrustedRunnerSliceSchema, { block: "trustedRunner" })?.trustedRunner;
4828
+ }
4823
4829
  function isDefaultBranch(name) {
4824
4830
  return `github.ref == 'refs/heads/${branchNameLiteral(name)}'`;
4825
4831
  }
@@ -5800,7 +5806,7 @@ function buildManagedDevDeps(ctx) {
5800
5806
  const devDeps = { ...rootDevDeps(ctx.config) };
5801
5807
  if (!isMonorepo) Object.assign(devDeps, perPackageDevDeps(ctx.config));
5802
5808
  if (ctx.config.stack !== "none") devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.15.1";
5803
- if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.103.0";
5809
+ if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.104.0";
5804
5810
  if (ctx.config.useEslintPlugin && ctx.config.stack !== "none") devDeps["@bensandee/eslint-plugin"] = isWorkspacePackage(ctx, "@bensandee/eslint-plugin") ? "workspace:*" : "0.18.0";
5805
5811
  if (wantsAgentCli(ctx)) devDeps[AGENT_CLI_PACKAGE] = "0.3.1";
5806
5812
  if (ctx.config.formatter === "oxfmt") devDeps["oxfmt"] = {
@@ -7844,6 +7850,7 @@ function postReleaseHookJob(opts) {
7844
7850
  return {
7845
7851
  needs: opts.needsJob,
7846
7852
  if: onlyOnDefaultBranch(opts.defaultBranch, opts.publishCondition),
7853
+ ...opts.runsOn && { runsOn: opts.runsOn },
7847
7854
  "continue-on-error": true,
7848
7855
  steps: [...commonSteps(opts.ci), { step: {
7849
7856
  name: "Post-release hook",
@@ -7988,6 +7995,7 @@ async function generateReleaseCi(ctx) {
7988
7995
  const filePath = "release-ci";
7989
7996
  const isGitHub = ctx.config.ci === "github";
7990
7997
  const defaultBranch = configuredDefaultBranch(ctx.read(".tooling.json"));
7998
+ const trustedRunner = configuredTrustedRunner(ctx.read(".tooling.json"));
7991
7999
  if (ctx.config.ci === "none" || ctx.config.releaseStrategy === "none") return {
7992
8000
  filePath,
7993
8001
  action: "skipped",
@@ -8044,6 +8052,7 @@ async function generateReleaseCi(ctx) {
8044
8052
  defaultBranch,
8045
8053
  ci: ctx.config.ci,
8046
8054
  needsJob: "release",
8055
+ ...trustedRunner && { runsOn: trustedRunner },
8047
8056
  publishCondition: "needs.release.outputs.pushed == 'true'",
8048
8057
  releaseTagExpr: actionsExpr("needs.release.outputs.tag"),
8049
8058
  command: getPostReleaseHookCommand(ctx),
@@ -8058,6 +8067,7 @@ async function generateReleaseCi(ctx) {
8058
8067
  ...isGitHub && { permissions: { contents: "write" } },
8059
8068
  jobName: "release",
8060
8069
  jobIf: isDefaultBranch(defaultBranch),
8070
+ ...trustedRunner && { runsOn: trustedRunner },
8061
8071
  ...jobOutputs && { jobOutputs },
8062
8072
  steps,
8063
8073
  ...extraJobs && { extraJobs }
@@ -8164,6 +8174,10 @@ function ciConcurrency(ci, defaultBranch) {
8164
8174
  "cancel-in-progress": actionsExpr(isNotDefaultBranch(defaultBranch))
8165
8175
  };
8166
8176
  }
8177
+ function checkJobRunsOn(defaultBranch, trustedRunner) {
8178
+ if (trustedRunner === void 0) return void 0;
8179
+ return actionsExpr(`${isDefaultBranch(defaultBranch)} && '${trustedRunner}' || 'ubuntu-latest'`);
8180
+ }
8167
8181
  function checkSteps(ci, coverageEnabled, emitDockerSweepStep) {
8168
8182
  const checkCommand = coverageEnabled ? "pnpm ci:check" : "pnpm ci:check --no-coverage";
8169
8183
  return [
@@ -8193,6 +8207,8 @@ async function generateCi(ctx) {
8193
8207
  description: "CI workflow not requested"
8194
8208
  };
8195
8209
  const defaultBranch = configuredDefaultBranch(ctx.read(".tooling.json"));
8210
+ const trustedRunner = configuredTrustedRunner(ctx.read(".tooling.json"));
8211
+ const checkRunsOn = checkJobRunsOn(defaultBranch, trustedRunner);
8196
8212
  const isGitHub = ctx.config.ci === "github";
8197
8213
  const isForgejo = !isGitHub;
8198
8214
  const isChangesets = ctx.config.releaseStrategy === "changesets";
@@ -8261,6 +8277,7 @@ async function generateCi(ctx) {
8261
8277
  defaultBranch,
8262
8278
  ci: ctx.config.ci,
8263
8279
  needsJob: "check",
8280
+ ...trustedRunner && { runsOn: trustedRunner },
8264
8281
  publishCondition: "needs.check.outputs.published == 'true'",
8265
8282
  releaseTagExpr: actionsExpr("needs.check.outputs.tag"),
8266
8283
  command: hookCommand,
@@ -8284,6 +8301,7 @@ async function generateCi(ctx) {
8284
8301
  enableEmailNotifications: isForgejo,
8285
8302
  ...isChangesets && { concurrency: ciConcurrency(ctx.config.ci, defaultBranch) },
8286
8303
  jobName: "check",
8304
+ ...checkRunsOn && { runsOn: checkRunsOn },
8287
8305
  ...skipOnVersionPr && { jobIf: `github.head_ref != '${versionPrBranch(defaultBranch)}'` },
8288
8306
  ...Object.keys(checkJobEnv).length > 0 && { jobEnv: checkJobEnv },
8289
8307
  ...jobOutputs && { jobOutputs },
@@ -9745,7 +9763,7 @@ const PLANNING_GUIDE_BODY = [
9745
9763
  "",
9746
9764
  "## The spec",
9747
9765
  "",
9748
- "Say why and what, not how: the problem, who it is for, the constraints, what done looks like, and the alternatives you rejected, each with its reason. Work with several independent parts gets one spec per part. Save it as `docs/specs/<YYYY-MM-DD>-<topic>-design.md`.",
9766
+ "Say why and what, not how: the problem, who it is for, the constraints, what done looks like, and the alternatives you rejected, each with its reason -- an established tool you chose not to use among them, by name. Work with several independent parts gets one spec per part. Save it as `docs/specs/<YYYY-MM-DD>-<topic>-design.md`.",
9749
9767
  "",
9750
9768
  "## The plan",
9751
9769
  "",
@@ -9827,6 +9845,23 @@ const DEBUGGING_GUIDE_BODY = [
9827
9845
  "- Three failed fixes mean the approach is wrong. Stop, question the design, and say what you do not understand, instead of trying a fourth.",
9828
9846
  "- A fixed bug gets a regression test that you have seen fail against the unfixed code."
9829
9847
  ].join("\n");
9848
+ const TOOLS_GUIDE_BODY = [
9849
+ "# Established tools",
9850
+ "",
9851
+ "**Before you design or write a general-purpose mechanism, look for the tool that already does it, and use it.** That covers a grammar or expression language, a parser, a scheduler or schedule format, and a date, retry, queue or validation helper.",
9852
+ "",
9853
+ "1. The platform or the language's standard library first.",
9854
+ "2. If it does not do the job, an established package.",
9855
+ "3. Your own code only when neither fits.",
9856
+ "",
9857
+ "An established package is maintained and widely used, has a license compatible with this repo's, ideally has few dependencies of its own, and has safety limits where its input is untrusted. Check these facts before you recommend a package -- its registry page, repository and license -- rather than recalling them.",
9858
+ "",
9859
+ "Keep only the domain part as your own code. In a design for scheduled prompts, the catalog of facts a condition reads is ours; the expression language (CEL) and the schedule format (cron) come from libraries.",
9860
+ "",
9861
+ "Adding an established dependency is not a cost to avoid. A homemade copy of what it does is the cost: code you own, test and secure for no gain.",
9862
+ "",
9863
+ "When you decide against an established tool, name it and the reason: in the spec's rejected alternatives, or in the commit body when there is no spec."
9864
+ ].join("\n");
9830
9865
  function webUiGuideBody() {
9831
9866
  const mwg = `pnpm dlx modern-web-guidance@${{
9832
9867
  "@changesets/cli": "3.0.3",
@@ -10042,6 +10077,12 @@ function agentGuides(config, coverageEnabled, healthEnabled, webUiEnabled) {
10042
10077
  body: DEBUGGING_GUIDE_BODY,
10043
10078
  enabled: true
10044
10079
  },
10080
+ {
10081
+ name: "tools.md",
10082
+ trigger: "design or write a general-purpose mechanism -- a grammar or expression language, a parser, a scheduler or schedule format, or a date, retry, queue or validation helper",
10083
+ body: TOOLS_GUIDE_BODY,
10084
+ enabled: true
10085
+ },
10045
10086
  {
10046
10087
  name: "web-ui.md",
10047
10088
  trigger: "build or change a web UI -- markup, styles, components, or client-side behaviour",
@@ -10402,7 +10443,7 @@ function reportFailures(failed, command) {
10402
10443
  function generateMigratePrompt(results, config, detected) {
10403
10444
  const sections = [];
10404
10445
  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
10405
- sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.103.0 repo:sync\` on ${timestamp}_\n`);
10446
+ sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.104.0 repo:sync\` on ${timestamp}_\n`);
10406
10447
  const changed = results.filter((r) => r.action === "created" || r.action === "updated" || r.action === "archived");
10407
10448
  if (changed.length > 0) {
10408
10449
  const items = changed.map((r) => {
@@ -24849,7 +24890,7 @@ function slackRecords(input) {
24849
24890
  });
24850
24891
  }
24851
24892
  }
24852
- for (const outlier of [...attribution.baseOutliers, ...attribution.unattributedOutliers]) {
24893
+ for (const outlier of attribution.baseOutliers) {
24853
24894
  if (!graphMeasured && isGraphMetric(outlier.key)) continue;
24854
24895
  records.push({
24855
24896
  kind: "uncapped",
@@ -24953,6 +24994,14 @@ function planHealthTighten(input) {
24953
24994
  caps
24954
24995
  };
24955
24996
  }
24997
+ function baselineUpdateRefusal(attribution) {
24998
+ if (attribution.newOutliers.length > 0) return "Skipped baseline update: an outlier crossed a limit for the first time this run. Record it with \"health:raise\", which writes the ceiling beside the reason it was earned.";
24999
+ if (attribution.unattributedOutliers.length > 0) {
25000
+ const base = attribution.outlierBase;
25001
+ return `Skipped baseline update: an outlier has no recorded ceiling and no merge-base measurement to clear it.${base.status === "unavailable" ? ` The merge base could not be measured: ${base.reason}.` : ""} Record it with "health:raise", which writes the ceiling beside the reason it was earned.`;
25002
+ }
25003
+ return null;
25004
+ }
24956
25005
  // src/codebase-health/base-checkout.ts
24957
25006
  const TEMP_PREFIX = "bst-health-base-";
24958
25007
  function withMergeBaseCheckout(executor, targetDir, mergeBase, use) {
@@ -25421,7 +25470,8 @@ function applyBaselineUpdate(state, existing, reset) {
25421
25470
  });
25422
25471
  out.notice(`Reset ${BASELINE_FILE$1} to the current run.`);
25423
25472
  } else if (isFlatOrBetter(baseline, current, ceilings, sizes)) {
25424
- if (attribution.newOutliers.length > 0) out.notice("Skipped baseline update: an outlier crossed a limit for the first time this run. Record it with \"health:raise\", which writes the ceiling beside the reason it was earned.");
25473
+ const refusal = baselineUpdateRefusal(attribution);
25474
+ if (refusal !== null) out.notice(refusal);
25425
25475
  else {
25426
25476
  const plan = planHealthTighten({
25427
25477
  comparison: result,
@@ -30077,7 +30127,7 @@ async function runCli(config) {
30077
30127
  // src/cli-main.ts
30078
30128
  setLogLevel(resolveLogLevel({}));
30079
30129
  setForgejoLogger(log$1);
30080
- const displayVersion = "0.103.0";
30130
+ const displayVersion = "0.104.0";
30081
30131
  const bstSubCommands = {
30082
30132
  "repo:sync": syncCommand,
30083
30133
  "checks:run": runChecksCommand,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bensandee/tooling",
3
- "version": "0.103.0",
3
+ "version": "0.104.0",
4
4
  "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -644,6 +644,11 @@
644
644
  "type": "string",
645
645
  "pattern": "^(?!refs\\/)(?!.*\\/\\/)(?!.*\\.\\.)(?!.*\\/$)(?!.*\\.lock$)[A-Za-z0-9][A-Za-z0-9._/-]*$"
646
646
  },
647
+ "trustedRunner": {
648
+ "description": "Self-hosted runner label for default-branch CI jobs: they run on this label while pull request jobs stay on 'ubuntu-latest'. Only a workflow edit moves a job, so the runner must be scoped so no other repository can name this label. A job aimed at a label no runner serves waits forever, so set this key only once the runner exists.",
649
+ "type": "string",
650
+ "pattern": "^(?!ubuntu-latest$)[A-Za-z0-9][A-Za-z0-9._-]*$"
651
+ },
647
652
  "unmanagedDevDependencies": {
648
653
  "description": "devDependency names repo:sync must never add or re-pin. Escape hatch for holding a tooling-managed dep (oxlint, vitest, knip, ...) at a deliberately off-canonical version; without it, repo:sync raises any managed devDep whose version has drifted below the canonical pin.",
649
654
  "type": "array",