@homeflare/config 0.4.0 → 0.5.1

package/README.md

@@ -104,6 +104,44 @@ if (problems.length > 0) throw new Error(problems.join('\n'));
 presets, that `.oxfmtrc.json` keeps house style plus at least the house ignores, and that
 `bunfig.toml` still matches.
 
+## App releases (no npm)
+
+A HomeFlare app that does **not** publish a tarball still versions itself with Changesets
+and cuts a GitHub Release. It does not call `npm publish`.
+
+```ts
+import { runAppRelease } from '@homeflare/config/release';
+
+await runAppRelease(process.cwd());
+```
+
+`shouldRelease` proceeds only when `CHANGELOG.md` has `## <version>` (proof
+`changeset version` ran) AND no git tag `<name>@<version>` exists yet. A custom
+`publish-script` on changesets/action otherwise tags every changeset-less push to `main`
+(measured 2026-09-16/17; changesets/action#9).
+
+```ts
+import { runRequireReleaseConfig } from '@homeflare/config/require-release-config';
+
+await runRequireReleaseConfig();
+```
+
+⛔ A private `package.json` without `privatePackages.version: true` makes
+`changeset version` silently no-op. The guard fails that combination before the version
+command consumes the changeset file.
+
+⛔ A leftover `pnpm-workspace.yaml` that lists only nested packages hides the root.
+Measured 2026-09-17 on `homeflare-secrets`: `changeset version` exited 1 ("package
+homeflare-secrets which is not in the workspace") and no Version Packages PR opened.
+The workspace file must include `.` if it exists at all.
+
+⛔ Both helpers take the **app** cwd / paths. Defaulting from `import.meta.url` after
+publish would inspect `@homeflare/config` itself.
+
+Alchemy still owns `GitHub.Repository` (visibility, `deleteBranchOnMerge`, `hasWiki`) and
+`Cloudflare.state()`. The kit `main` ruleset is `scripts/apply-main-ruleset.ts`, not an
+Alchemy resource — see `docs/github-hygiene.md`.
+
 ## License
 
 MIT © Timothy Schneider

package/dist/changeset-workspace.d.ts

@@ -0,0 +1,5 @@
+export declare function workspacePackageNames(cwd: string): Promise<readonly string[]>;
+/** Package names in a changeset file's YAML frontmatter. */
+export declare function packagesNamedInChangeset(text: string): readonly string[];
+export declare function problemsFromPendingChangesets(cwd: string): Promise<readonly string[]>;
+//# sourceMappingURL=changeset-workspace.d.ts.map

package/dist/changeset-workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changeset-workspace.d.ts","sourceRoot":"","sources":["../src/changeset-workspace.ts"],"names":[],"mappings":"AA0BA,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAcnF;AAkBD,4DAA4D;AAC5D,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAMxE;AAED,wBAAsB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CA2B3F"}

package/dist/release.d.ts

@@ -0,0 +1,54 @@
+/**
+ * No npm publish. Tag a GitHub Release — but ONLY when this version genuinely just
+ * came out of `changeset version`, never on an arbitrary changeset-less push to main.
+ *
+ * 🔴 MEASURED 2026-09-16/17 on homeflare-openbao, and documented upstream
+ *   (changesets/action's own README, changesets/action#9): a custom publish-script runs
+ *   on EVERY push to `main` that has zero pending changesets — not just the one push
+ *   right after a Version Packages PR merges. The README says so directly: "a commit
+ *   without any new changesets can always land on your base branch after a successful
+ *   publish... you need to figure out on your own how to skip." Unguarded, this would
+ *   tag `<name>@<version>` on every unrelated push to main once CHANGELOG.md exists.
+ *
+ * ★ THE CONDITION: proceed only if `CHANGELOG.md` has an entry for the current version
+ *   (proof `changeset version` really ran and wrote it) AND no git tag `<name>@<version>`
+ *   exists yet (proof this exact release was not already cut). Both checks are local —
+ *   no network, no GitHub API — and both work from the checkout `release.yml` already
+ *   has (`fetch-depth: 0`).
+ *
+ * ⛔ TELL changesets/action WHAT TO TAG. With a custom publish-script it learns what
+ *   shipped only from `CHANGESETS_OUTPUT`. Without it, the action warns "GitHub releases
+ *   and git tags cannot be created without this output" and creates neither.
+ */
+type Pkg = {
+    readonly name: string;
+    readonly version: string;
+};
+/**
+ * Does CHANGELOG.md have a heading for this exact version?
+ * @changesets/changelog-github writes `## <version>` for a single, non-monorepo package.
+ */
+export declare function changelogHasEntry(cwd: string, version: string): Promise<boolean>;
+/** Does this exact tag already exist? Local `git tag -l`, no network. */
+export declare function tagExists(cwd: string, tag: string): boolean;
+export type ReleaseDecision = {
+    readonly ok: boolean;
+    readonly reason: string;
+};
+export declare function shouldRelease(cwd: string, pkg: Pkg): Promise<ReleaseDecision>;
+/** One ndjson line changesets/action turns into a git tag and a GitHub Release. */
+export declare function tagEvent(pkg: Pkg): {
+    type: 'git-tag';
+    tag: string;
+    packageName: string;
+};
+/**
+ * App-repo publish-script. Reads `package.json` at `cwd`, gates on `shouldRelease`,
+ * and writes the tag event to `$CHANGESETS_OUTPUT` when this version is new.
+ *
+ * ⛔ `cwd` is the APP, never this package. Defaulting from `import.meta.url` after
+ *   publish would inspect `@homeflare/config` itself.
+ */
+export declare function runAppRelease(cwd: string): Promise<ReleaseDecision>;
+export {};
+//# sourceMappingURL=release.d.ts.map

package/dist/release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../src/release.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,KAAK,GAAG,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMtF;AAgBD,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAG3D;AAED,MAAM,MAAM,eAAe,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC,CAanF;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAExF;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAiBzE"}

package/dist/release.js

@@ -0,0 +1,66 @@
+// @bun
+// src/release.ts
+async function changelogHasEntry(cwd, version) {
+  const file = Bun.file(`${cwd}/CHANGELOG.md`);
+  if (!await file.exists())
+    return false;
+  const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^## ${escaped}$`, "m").test(await file.text());
+}
+var gitEnv = () => {
+  const env = { ...process.env };
+  delete env.GIT_DIR;
+  delete env.GIT_WORK_TREE;
+  delete env.GIT_INDEX_FILE;
+  return env;
+};
+function tagExists(cwd, tag) {
+  const result = Bun.spawnSync(["git", "tag", "-l", tag], { cwd, env: gitEnv() });
+  return result.stdout.toString().trim() === tag;
+}
+async function shouldRelease(cwd, pkg) {
+  const tag = `${pkg.name}@${pkg.version}`;
+  if (!await changelogHasEntry(cwd, pkg.version)) {
+    return {
+      ok: false,
+      reason: `CHANGELOG.md has no "## ${pkg.version}" entry \u2014 changeset version has not run for this version`
+    };
+  }
+  if (tagExists(cwd, tag)) {
+    return { ok: false, reason: `${tag} already exists \u2014 this version was already released` };
+  }
+  return { ok: true, reason: `CHANGELOG.md has the entry and ${tag} does not exist yet` };
+}
+function tagEvent(pkg) {
+  return { type: "git-tag", tag: `${pkg.name}@${pkg.version}`, packageName: pkg.name };
+}
+async function runAppRelease(cwd) {
+  const pkg = await Bun.file(`${cwd}/package.json`).json();
+  const decision = await shouldRelease(cwd, pkg);
+  if (!decision.ok) {
+    process.stdout.write(`skip: ${decision.reason}
+`);
+    return decision;
+  }
+  const outputFile = process.env["CHANGESETS_OUTPUT"];
+  if (outputFile !== undefined) {
+    await Bun.write(outputFile, `${JSON.stringify(tagEvent(pkg))}
+`);
+  }
+  process.stdout.write(`${pkg.name}@${pkg.version} \u2014 no npm publish; tagged (${decision.reason}).
+`);
+  return decision;
+}
+if (import.meta.main) {
+  await runAppRelease(process.cwd());
+}
+export {
+  changelogHasEntry,
+  runAppRelease,
+  shouldRelease,
+  tagEvent,
+  tagExists
+};
+
+//# debugId=6C6369E02082921C64756E2164756E21
+//# sourceMappingURL=release.js.map

package/dist/release.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/release.ts"],
+  "sourcesContent": [
+    "/**\n * No npm publish. Tag a GitHub Release — but ONLY when this version genuinely just\n * came out of `changeset version`, never on an arbitrary changeset-less push to main.\n *\n * 🔴 MEASURED 2026-09-16/17 on homeflare-openbao, and documented upstream\n *   (changesets/action's own README, changesets/action#9): a custom publish-script runs\n *   on EVERY push to `main` that has zero pending changesets — not just the one push\n *   right after a Version Packages PR merges. The README says so directly: \"a commit\n *   without any new changesets can always land on your base branch after a successful\n *   publish... you need to figure out on your own how to skip.\" Unguarded, this would\n *   tag `<name>@<version>` on every unrelated push to main once CHANGELOG.md exists.\n *\n * ★ THE CONDITION: proceed only if `CHANGELOG.md` has an entry for the current version\n *   (proof `changeset version` really ran and wrote it) AND no git tag `<name>@<version>`\n *   exists yet (proof this exact release was not already cut). Both checks are local —\n *   no network, no GitHub API — and both work from the checkout `release.yml` already\n *   has (`fetch-depth: 0`).\n *\n * ⛔ TELL changesets/action WHAT TO TAG. With a custom publish-script it learns what\n *   shipped only from `CHANGESETS_OUTPUT`. Without it, the action warns \"GitHub releases\n *   and git tags cannot be created without this output\" and creates neither.\n */\ntype Pkg = { readonly name: string; readonly version: string };\n\n/**\n * Does CHANGELOG.md have a heading for this exact version?\n * @changesets/changelog-github writes `## <version>` for a single, non-monorepo package.\n */\nexport async function changelogHasEntry(cwd: string, version: string): Promise<boolean> {\n  const file = Bun.file(`${cwd}/CHANGELOG.md`);\n  if (!(await file.exists())) return false;\n\n  const escaped = version.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n  return new RegExp(`^## ${escaped}$`, 'm').test(await file.text());\n}\n\n/**\n * ⛔ DROP HUSKY GIT_DIR. `cwd` is not enough — pre-push exports GIT_DIR\n *   and `git tag -l` then reads this checkout, not the throwaway repo.\n *   Symptom: shouldRelease is false during verify and a test commits `init`\n *   onto the branch being pushed.\n */\nconst gitEnv = (): NodeJS.ProcessEnv => {\n  const env = { ...process.env };\n  delete env.GIT_DIR;\n  delete env.GIT_WORK_TREE;\n  delete env.GIT_INDEX_FILE;\n  return env;\n};\n\n/** Does this exact tag already exist? Local `git tag -l`, no network. */\nexport function tagExists(cwd: string, tag: string): boolean {\n  const result = Bun.spawnSync(['git', 'tag', '-l', tag], { cwd, env: gitEnv() });\n  return result.stdout.toString().trim() === tag;\n}\n\nexport type ReleaseDecision = { readonly ok: boolean; readonly reason: string };\n\nexport async function shouldRelease(cwd: string, pkg: Pkg): Promise<ReleaseDecision> {\n  const tag = `${pkg.name}@${pkg.version}`;\n\n  if (!(await changelogHasEntry(cwd, pkg.version))) {\n    return {\n      ok: false,\n      reason: `CHANGELOG.md has no \"## ${pkg.version}\" entry — changeset version has not run for this version`,\n    };\n  }\n  if (tagExists(cwd, tag)) {\n    return { ok: false, reason: `${tag} already exists — this version was already released` };\n  }\n  return { ok: true, reason: `CHANGELOG.md has the entry and ${tag} does not exist yet` };\n}\n\n/** One ndjson line changesets/action turns into a git tag and a GitHub Release. */\nexport function tagEvent(pkg: Pkg): { type: 'git-tag'; tag: string; packageName: string } {\n  return { type: 'git-tag', tag: `${pkg.name}@${pkg.version}`, packageName: pkg.name };\n}\n\n/**\n * App-repo publish-script. Reads `package.json` at `cwd`, gates on `shouldRelease`,\n * and writes the tag event to `$CHANGESETS_OUTPUT` when this version is new.\n *\n * ⛔ `cwd` is the APP, never this package. Defaulting from `import.meta.url` after\n *   publish would inspect `@homeflare/config` itself.\n */\nexport async function runAppRelease(cwd: string): Promise<ReleaseDecision> {\n  const pkg = (await Bun.file(`${cwd}/package.json`).json()) as Pkg;\n  const decision = await shouldRelease(cwd, pkg);\n\n  if (!decision.ok) {\n    process.stdout.write(`skip: ${decision.reason}\\n`);\n    return decision;\n  }\n\n  const outputFile = process.env['CHANGESETS_OUTPUT'];\n  if (outputFile !== undefined) {\n    await Bun.write(outputFile, `${JSON.stringify(tagEvent(pkg))}\\n`);\n  }\n  process.stdout.write(\n    `${pkg.name}@${pkg.version} — no npm publish; tagged (${decision.reason}).\\n`,\n  );\n  return decision;\n}\n\nif (import.meta.main) {\n  await runAppRelease(process.cwd());\n}\n"
+  ],
+  "mappings": ";;AA4BA,eAAsB,iBAAiB,CAAC,KAAa,SAAmC;AAAA,EACtF,MAAM,OAAO,IAAI,KAAK,GAAG,kBAAkB;AAAA,EAC3C,IAAI,CAAE,MAAM,KAAK,OAAO;AAAA,IAAI,OAAO;AAAA,EAEnC,MAAM,UAAU,QAAQ,QAAQ,uBAAuB,MAAM;AAAA,EAC7D,OAAO,IAAI,OAAO,OAAO,YAAY,GAAG,EAAE,KAAK,MAAM,KAAK,KAAK,CAAC;AAAA;AASlE,IAAM,SAAS,MAAyB;AAAA,EACtC,MAAM,MAAM,KAAK,QAAQ,IAAI;AAAA,EAC7B,OAAO,IAAI;AAAA,EACX,OAAO,IAAI;AAAA,EACX,OAAO,IAAI;AAAA,EACX,OAAO;AAAA;AAIF,SAAS,SAAS,CAAC,KAAa,KAAsB;AAAA,EAC3D,MAAM,SAAS,IAAI,UAAU,CAAC,OAAO,OAAO,MAAM,GAAG,GAAG,EAAE,KAAK,KAAK,OAAO,EAAE,CAAC;AAAA,EAC9E,OAAO,OAAO,OAAO,SAAS,EAAE,KAAK,MAAM;AAAA;AAK7C,eAAsB,aAAa,CAAC,KAAa,KAAoC;AAAA,EACnF,MAAM,MAAM,GAAG,IAAI,QAAQ,IAAI;AAAA,EAE/B,IAAI,CAAE,MAAM,kBAAkB,KAAK,IAAI,OAAO,GAAI;AAAA,IAChD,OAAO;AAAA,MACL,IAAI;AAAA,MACJ,QAAQ,2BAA2B,IAAI;AAAA,IACzC;AAAA,EACF;AAAA,EACA,IAAI,UAAU,KAAK,GAAG,GAAG;AAAA,IACvB,OAAO,EAAE,IAAI,OAAO,QAAQ,GAAG,8DAAyD;AAAA,EAC1F;AAAA,EACA,OAAO,EAAE,IAAI,MAAM,QAAQ,kCAAkC,yBAAyB;AAAA;AAIjF,SAAS,QAAQ,CAAC,KAAiE;AAAA,EACxF,OAAO,EAAE,MAAM,WAAW,KAAK,GAAG,IAAI,QAAQ,IAAI,WAAW,aAAa,IAAI,KAAK;AAAA;AAUrF,eAAsB,aAAa,CAAC,KAAuC;AAAA,EACzE,MAAM,MAAO,MAAM,IAAI,KAAK,GAAG,kBAAkB,EAAE,KAAK;AAAA,EACxD,MAAM,WAAW,MAAM,cAAc,KAAK,GAAG;AAAA,EAE7C,IAAI,CAAC,SAAS,IAAI;AAAA,IAChB,QAAQ,OAAO,MAAM,SAAS,SAAS;AAAA,CAAU;AAAA,IACjD,OAAO;AAAA,EACT;AAAA,EAEA,MAAM,aAAa,QAAQ,IAAI;AAAA,EAC/B,IAAI,eAAe,WAAW;AAAA,IAC5B,MAAM,IAAI,MAAM,YAAY,GAAG,KAAK,UAAU,SAAS,GAAG,CAAC;AAAA,CAAK;AAAA,EAClE;AAAA,EACA,QAAQ,OAAO,MACb,GAAG,IAAI,QAAQ,IAAI,0CAAqC,SAAS;AAAA,CACnE;AAAA,EACA,OAAO;AAAA;AAGT,IAAI,kBAAkB;AAAA,EACpB,MAAM,cAAc,QAAQ,IAAI,CAAC;AACnC;",
+  "debugId": "6C6369E02082921C64756E2164756E21",
+  "names": []
+}

package/dist/require-release-config.d.ts

@@ -0,0 +1,11 @@
+export type ReleaseConfigPaths = {
+    readonly pkgPath: string;
+    readonly changesetConfigPath: string;
+};
+/** Resolve the two files a version command must see. Override in tests. */
+export declare function releaseConfigPaths(cwd?: string): ReleaseConfigPaths;
+/** One thing a project should fix, in the imperative. */
+export declare function problemsInReleaseConfig(paths: ReleaseConfigPaths): Promise<string[]>;
+/** Print and exit. App `version` scripts call this before `changeset version`. */
+export declare function runRequireReleaseConfig(paths?: Partial<ReleaseConfigPaths>): Promise<void>;
+//# sourceMappingURL=require-release-config.d.ts.map

package/dist/require-release-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-release-config.d.ts","sourceRoot":"","sources":["../src/require-release-config.ts"],"names":[],"mappings":"AA8BA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC,CAAC;AAEF,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAsB,GAAG,kBAAkB,CAKlF;AAED,yDAAyD;AACzD,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsB1F;AAED,kFAAkF;AAClF,wBAAsB,uBAAuB,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhG"}

package/dist/require-release-config.js

@@ -0,0 +1,127 @@
+// @bun
+// src/changeset-workspace.ts
+import { readdir } from "fs/promises";
+function rootName(pkg) {
+  return typeof pkg.name === "string" ? [pkg.name] : [];
+}
+async function workspacePackageNames(cwd) {
+  const pnpm = Bun.file(`${cwd}/pnpm-workspace.yaml`);
+  if (await pnpm.exists()) {
+    const parsed = Bun.YAML.parse(await pnpm.text());
+    return namesFromPatterns(cwd, parsed.packages ?? []);
+  }
+  const pkg = await Bun.file(`${cwd}/package.json`).json();
+  if (pkg.workspaces !== undefined && pkg.workspaces.length > 0) {
+    return namesFromPatterns(cwd, pkg.workspaces);
+  }
+  return rootName(pkg);
+}
+async function namesFromPatterns(cwd, patterns) {
+  const names = [];
+  for (const pattern of patterns) {
+    if (pattern.includes("*"))
+      continue;
+    const pkgPath = pattern === "." ? `${cwd}/package.json` : `${cwd}/${pattern}/package.json`;
+    const file = Bun.file(pkgPath);
+    if (!await file.exists())
+      continue;
+    const name = (await file.json()).name;
+    if (typeof name === "string")
+      names.push(name);
+  }
+  return names;
+}
+function packagesNamedInChangeset(text) {
+  const match = /^---\n([\s\S]*?)\n---/m.exec(text);
+  if (match?.[1] === undefined)
+    return [];
+  const parsed = Bun.YAML.parse(match[1]);
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+    return [];
+  return Object.keys(parsed);
+}
+async function problemsFromPendingChangesets(cwd) {
+  let files;
+  try {
+    files = (await readdir(`${cwd}/.changeset`)).filter((name) => name.endsWith(".md") && name !== "README.md");
+  } catch {
+    return [];
+  }
+  if (files.length === 0)
+    return [];
+  const workspace = new Set(await workspacePackageNames(cwd));
+  const problems = [];
+  for (const name of files) {
+    const rel = `.changeset/${name}`;
+    for (const pkg of packagesNamedInChangeset(await Bun.file(`${cwd}/${rel}`).text())) {
+      if (!workspace.has(pkg)) {
+        problems.push(`${rel} names "${pkg}" which is not in the workspace \u2014 changeset version ` + "exits 1 (measured 2026-09-17: leftover pnpm-workspace.yaml listed nested " + "packages and hid the root)");
+      }
+    }
+  }
+  return problems;
+}
+
+// src/require-release-config.ts
+function releaseConfigPaths(cwd = process.cwd()) {
+  return {
+    pkgPath: `${cwd}/package.json`,
+    changesetConfigPath: `${cwd}/.changeset/config.json`
+  };
+}
+async function problemsInReleaseConfig(paths) {
+  const pkg = await Bun.file(paths.pkgPath).json();
+  const problems = [];
+  if (typeof pkg.version !== "string" || pkg.version.length === 0) {
+    problems.push(`${paths.pkgPath} has no "version" \u2014 changeset version would silently no-op`);
+  }
+  if (pkg.private === true) {
+    const changesetConfig = await Bun.file(paths.changesetConfigPath).json();
+    if (changesetConfig.privatePackages?.version !== true) {
+      problems.push(`${paths.changesetConfigPath} has no privatePackages.version: true \u2014 a private package ` + 'is excluded from versioning entirely, which reads as "nothing to release"');
+    }
+  }
+  const cwd = paths.pkgPath.replace(/\/package\.json$/, "");
+  problems.push(...await problemsFromPendingChangesets(cwd));
+  return problems;
+}
+async function runRequireReleaseConfig(paths) {
+  const defaults = releaseConfigPaths();
+  const resolved = {
+    pkgPath: paths?.pkgPath ?? defaults.pkgPath,
+    changesetConfigPath: paths?.changesetConfigPath ?? defaults.changesetConfigPath
+  };
+  const problems = await problemsInReleaseConfig(resolved);
+  if (problems.length > 0) {
+    process.stderr.write(`
+\u2717 changeset version would silently no-op:
+`);
+    for (const problem of problems)
+      process.stderr.write(`  - ${problem}
+`);
+    process.stderr.write(`
+  Fix the file(s) above in a reviewed commit, then re-run this.
+
+`);
+    process.exit(1);
+  }
+  const pkg = await Bun.file(resolved.pkgPath).json();
+  process.stdout.write(`ok: ${resolved.pkgPath} version is ${pkg.version}, privatePackages.version is set
+`);
+}
+if (import.meta.main) {
+  const pkgPath = process.argv[2];
+  const changesetConfigPath = process.argv[3];
+  await runRequireReleaseConfig({
+    ...pkgPath === undefined ? {} : { pkgPath },
+    ...changesetConfigPath === undefined ? {} : { changesetConfigPath }
+  });
+}
+export {
+  problemsInReleaseConfig,
+  releaseConfigPaths,
+  runRequireReleaseConfig
+};
+
+//# debugId=5B77C8600B7D3E7B64756E2164756E21
+//# sourceMappingURL=require-release-config.js.map

package/dist/require-release-config.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/changeset-workspace.ts", "../src/require-release-config.ts"],
+  "sourcesContent": [
+    "/**\n * Pending changesets must name a package Changesets actually considers a workspace\n * member. Otherwise `changeset version` exits 1 and no Version Packages PR opens.\n *\n * 🔴 MEASURED 2026-09-17 on homeflare-secrets. A leftover `pnpm-workspace.yaml`\n *   listed only `hfs` and `secret-vault`. `@changesets/cli` treats that file as the\n *   workspace, so the root package (`homeflare-secrets` — the GitHub Release) was\n *   \"not in the workspace\". The hygiene changeset named the root. Release on main\n *   failed; no Version PR, no tag.\n *\n * ★ Root is a member only when the workspace file says so (`.` or a package.json\n *   `workspaces` entry). Nested leftover packages keep their own package.json for\n *   their own tools; they are not this repo's release.\n */\nimport { readdir } from 'node:fs/promises';\n\ntype WorkspaceFile = { readonly packages?: readonly string[] };\ntype RootPkg = {\n  readonly name?: unknown;\n  readonly workspaces?: readonly string[];\n};\n\nfunction rootName(pkg: RootPkg): readonly string[] {\n  return typeof pkg.name === 'string' ? [pkg.name] : [];\n}\n\nexport async function workspacePackageNames(cwd: string): Promise<readonly string[]> {\n  const pnpm = Bun.file(`${cwd}/pnpm-workspace.yaml`);\n  if (await pnpm.exists()) {\n    const parsed = Bun.YAML.parse(await pnpm.text()) as WorkspaceFile;\n    return namesFromPatterns(cwd, parsed.packages ?? []);\n  }\n\n  const pkg = (await Bun.file(`${cwd}/package.json`).json()) as RootPkg;\n  // ★ Array form only. The yarn `{ packages: [] }` object is unused in this estate,\n  //   and `Array.isArray` does not narrow that union under exactOptionalPropertyTypes.\n  if (pkg.workspaces !== undefined && pkg.workspaces.length > 0) {\n    return namesFromPatterns(cwd, pkg.workspaces);\n  }\n  return rootName(pkg);\n}\n\nasync function namesFromPatterns(cwd: string, patterns: readonly string[]): Promise<string[]> {\n  const names: string[] = [];\n  for (const pattern of patterns) {\n    // ⛔ Full glob support is not the job. Changesets already expands globs; this\n    //   guard only needs `.` and literal directory members — the case that hid\n    //   the root. A `*` pattern is skipped rather than half-parsed.\n    if (pattern.includes('*')) continue;\n    const pkgPath = pattern === '.' ? `${cwd}/package.json` : `${cwd}/${pattern}/package.json`;\n    const file = Bun.file(pkgPath);\n    if (!(await file.exists())) continue;\n    const name = ((await file.json()) as { readonly name?: unknown }).name;\n    if (typeof name === 'string') names.push(name);\n  }\n  return names;\n}\n\n/** Package names in a changeset file's YAML frontmatter. */\nexport function packagesNamedInChangeset(text: string): readonly string[] {\n  const match = /^---\\n([\\s\\S]*?)\\n---/m.exec(text);\n  if (match?.[1] === undefined) return [];\n  const parsed = Bun.YAML.parse(match[1]);\n  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return [];\n  return Object.keys(parsed);\n}\n\nexport async function problemsFromPendingChangesets(cwd: string): Promise<readonly string[]> {\n  let files: string[];\n  try {\n    files = (await readdir(`${cwd}/.changeset`)).filter(\n      (name) => name.endsWith('.md') && name !== 'README.md',\n    );\n  } catch {\n    // Missing `.changeset` is not a fault — nothing pending.\n    return [];\n  }\n  if (files.length === 0) return [];\n\n  const workspace = new Set(await workspacePackageNames(cwd));\n  const problems: string[] = [];\n  for (const name of files) {\n    const rel = `.changeset/${name}`;\n    for (const pkg of packagesNamedInChangeset(await Bun.file(`${cwd}/${rel}`).text())) {\n      if (!workspace.has(pkg)) {\n        problems.push(\n          `${rel} names \"${pkg}\" which is not in the workspace — changeset version ` +\n            'exits 1 (measured 2026-09-17: leftover pnpm-workspace.yaml listed nested ' +\n            'packages and hid the root)',\n        );\n      }\n    }\n  }\n  return problems;\n}\n",
+    "/**\n * Refuse to let `changeset version` run against a config that would silently no-op.\n *\n * 🔴 MEASURED 2026-09-16 on homeflare-openbao, TWO INDEPENDENT WAYS TO GET THE SAME\n *   SILENT FAILURE. `@changesets/cli` 3.0.3 does neither of these things loudly:\n *   1. `package.json` with no \"version\" — `changeset version` consumes the pending\n *      changeset file, writes no `CHANGELOG.md`, leaves `package.json` untouched.\n *   2. `\"private\": true` with no `privatePackages.version: true` in\n *      `.changeset/config.json` — the package is excluded from versioning entirely;\n *      `changeset status` reports zero packages to bump even with a real version and a\n *      pending changeset file.\n *   Either gap alone reproduces the same no-op. Both are required together.\n *\n * ★ This is regression protection against either field being dropped — a bad merge, a\n *   hand-edit, a generator overwriting either file — not a bootstrap blocker.\n *\n * 🔴 A leftover `pnpm-workspace.yaml` that lists only nested packages hides the\n *   root. `changeset version` then exits 1 (\"package X is not in the workspace\") —\n *   measured 2026-09-17 on homeflare-secrets. `problemsFromPendingChangesets`\n *   fails that before the version command consumes the file.\n *\n * ⛔ Path defaults are `process.cwd()`, NEVER `import.meta.url`. After publish this\n *   file lives in `node_modules/@homeflare/config`; resolving next to it would check\n *   the published package, not the app that invoked it.\n */\nimport { problemsFromPendingChangesets } from './changeset-workspace.ts';\n\ntype Pkg = { readonly version?: unknown; readonly private?: unknown };\ntype ChangesetConfig = { readonly privatePackages?: { readonly version?: unknown } };\n\nexport type ReleaseConfigPaths = {\n  readonly pkgPath: string;\n  readonly changesetConfigPath: string;\n};\n\n/** Resolve the two files a version command must see. Override in tests. */\nexport function releaseConfigPaths(cwd: string = process.cwd()): ReleaseConfigPaths {\n  return {\n    pkgPath: `${cwd}/package.json`,\n    changesetConfigPath: `${cwd}/.changeset/config.json`,\n  };\n}\n\n/** One thing a project should fix, in the imperative. */\nexport async function problemsInReleaseConfig(paths: ReleaseConfigPaths): Promise<string[]> {\n  const pkg = (await Bun.file(paths.pkgPath).json()) as Pkg;\n  const problems: string[] = [];\n\n  if (typeof pkg.version !== 'string' || pkg.version.length === 0) {\n    problems.push(`${paths.pkgPath} has no \"version\" — changeset version would silently no-op`);\n  }\n\n  if (pkg.private === true) {\n    const changesetConfig = (await Bun.file(paths.changesetConfigPath).json()) as ChangesetConfig;\n    if (changesetConfig.privatePackages?.version !== true) {\n      problems.push(\n        `${paths.changesetConfigPath} has no privatePackages.version: true — a private package ` +\n          'is excluded from versioning entirely, which reads as \"nothing to release\"',\n      );\n    }\n  }\n\n  const cwd = paths.pkgPath.replace(/\\/package\\.json$/, '');\n  problems.push(...(await problemsFromPendingChangesets(cwd)));\n\n  return problems;\n}\n\n/** Print and exit. App `version` scripts call this before `changeset version`. */\nexport async function runRequireReleaseConfig(paths?: Partial<ReleaseConfigPaths>): Promise<void> {\n  // ⚠️ A spread of `{ pkgPath: undefined }` from `process.argv[2]` would overwrite the\n  //   cwd default. Only copy keys that are actually present.\n  const defaults = releaseConfigPaths();\n  const resolved: ReleaseConfigPaths = {\n    pkgPath: paths?.pkgPath ?? defaults.pkgPath,\n    changesetConfigPath: paths?.changesetConfigPath ?? defaults.changesetConfigPath,\n  };\n  const problems = await problemsInReleaseConfig(resolved);\n\n  if (problems.length > 0) {\n    process.stderr.write('\\n✗ changeset version would silently no-op:\\n');\n    for (const problem of problems) process.stderr.write(`  - ${problem}\\n`);\n    process.stderr.write('\\n  Fix the file(s) above in a reviewed commit, then re-run this.\\n\\n');\n    process.exit(1);\n  }\n\n  const pkg = (await Bun.file(resolved.pkgPath).json()) as Pkg;\n  process.stdout.write(\n    `ok: ${resolved.pkgPath} version is ${pkg.version}, privatePackages.version is set\\n`,\n  );\n}\n\nif (import.meta.main) {\n  const pkgPath = process.argv[2];\n  const changesetConfigPath = process.argv[3];\n  await runRequireReleaseConfig({\n    ...(pkgPath === undefined ? {} : { pkgPath }),\n    ...(changesetConfigPath === undefined ? {} : { changesetConfigPath }),\n  });\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "5B77C8600B7D3E7B64756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homeflare/config",
-  "version": "0.4.0",
-  "description": "Shared tsconfig, oxlint and oxfmt configuration for HomeFlare projects.",
+  "version": "0.5.1",
+  "description": "Shared tsconfig, oxlint, oxfmt, and non-npm release helpers for HomeFlare projects.",
   "license": "MIT",
   "author": "Timothy Schneider",
   "repository": {
@@ -35,6 +35,14 @@
       "types": "./dist/check.d.ts",
       "default": "./dist/check.js"
     },
+    "./release": {
+      "types": "./dist/release.d.ts",
+      "default": "./dist/release.js"
+    },
+    "./require-release-config": {
+      "types": "./dist/require-release-config.d.ts",
+      "default": "./dist/require-release-config.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/src/changeset-workspace.ts

@@ -0,0 +1,95 @@
+/**
+ * Pending changesets must name a package Changesets actually considers a workspace
+ * member. Otherwise `changeset version` exits 1 and no Version Packages PR opens.
+ *
+ * 🔴 MEASURED 2026-09-17 on homeflare-secrets. A leftover `pnpm-workspace.yaml`
+ *   listed only `hfs` and `secret-vault`. `@changesets/cli` treats that file as the
+ *   workspace, so the root package (`homeflare-secrets` — the GitHub Release) was
+ *   "not in the workspace". The hygiene changeset named the root. Release on main
+ *   failed; no Version PR, no tag.
+ *
+ * ★ Root is a member only when the workspace file says so (`.` or a package.json
+ *   `workspaces` entry). Nested leftover packages keep their own package.json for
+ *   their own tools; they are not this repo's release.
+ */
+import { readdir } from 'node:fs/promises';
+
+type WorkspaceFile = { readonly packages?: readonly string[] };
+type RootPkg = {
+  readonly name?: unknown;
+  readonly workspaces?: readonly string[];
+};
+
+function rootName(pkg: RootPkg): readonly string[] {
+  return typeof pkg.name === 'string' ? [pkg.name] : [];
+}
+
+export async function workspacePackageNames(cwd: string): Promise<readonly string[]> {
+  const pnpm = Bun.file(`${cwd}/pnpm-workspace.yaml`);
+  if (await pnpm.exists()) {
+    const parsed = Bun.YAML.parse(await pnpm.text()) as WorkspaceFile;
+    return namesFromPatterns(cwd, parsed.packages ?? []);
+  }
+
+  const pkg = (await Bun.file(`${cwd}/package.json`).json()) as RootPkg;
+  // ★ Array form only. The yarn `{ packages: [] }` object is unused in this estate,
+  //   and `Array.isArray` does not narrow that union under exactOptionalPropertyTypes.
+  if (pkg.workspaces !== undefined && pkg.workspaces.length > 0) {
+    return namesFromPatterns(cwd, pkg.workspaces);
+  }
+  return rootName(pkg);
+}
+
+async function namesFromPatterns(cwd: string, patterns: readonly string[]): Promise<string[]> {
+  const names: string[] = [];
+  for (const pattern of patterns) {
+    // ⛔ Full glob support is not the job. Changesets already expands globs; this
+    //   guard only needs `.` and literal directory members — the case that hid
+    //   the root. A `*` pattern is skipped rather than half-parsed.
+    if (pattern.includes('*')) continue;
+    const pkgPath = pattern === '.' ? `${cwd}/package.json` : `${cwd}/${pattern}/package.json`;
+    const file = Bun.file(pkgPath);
+    if (!(await file.exists())) continue;
+    const name = ((await file.json()) as { readonly name?: unknown }).name;
+    if (typeof name === 'string') names.push(name);
+  }
+  return names;
+}
+
+/** Package names in a changeset file's YAML frontmatter. */
+export function packagesNamedInChangeset(text: string): readonly string[] {
+  const match = /^---\n([\s\S]*?)\n---/m.exec(text);
+  if (match?.[1] === undefined) return [];
+  const parsed = Bun.YAML.parse(match[1]);
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return [];
+  return Object.keys(parsed);
+}
+
+export async function problemsFromPendingChangesets(cwd: string): Promise<readonly string[]> {
+  let files: string[];
+  try {
+    files = (await readdir(`${cwd}/.changeset`)).filter(
+      (name) => name.endsWith('.md') && name !== 'README.md',
+    );
+  } catch {
+    // Missing `.changeset` is not a fault — nothing pending.
+    return [];
+  }
+  if (files.length === 0) return [];
+
+  const workspace = new Set(await workspacePackageNames(cwd));
+  const problems: string[] = [];
+  for (const name of files) {
+    const rel = `.changeset/${name}`;
+    for (const pkg of packagesNamedInChangeset(await Bun.file(`${cwd}/${rel}`).text())) {
+      if (!workspace.has(pkg)) {
+        problems.push(
+          `${rel} names "${pkg}" which is not in the workspace — changeset version ` +
+            'exits 1 (measured 2026-09-17: leftover pnpm-workspace.yaml listed nested ' +
+            'packages and hid the root)',
+        );
+      }
+    }
+  }
+  return problems;
+}

package/src/release.ts

@@ -0,0 +1,107 @@
+/**
+ * No npm publish. Tag a GitHub Release — but ONLY when this version genuinely just
+ * came out of `changeset version`, never on an arbitrary changeset-less push to main.
+ *
+ * 🔴 MEASURED 2026-09-16/17 on homeflare-openbao, and documented upstream
+ *   (changesets/action's own README, changesets/action#9): a custom publish-script runs
+ *   on EVERY push to `main` that has zero pending changesets — not just the one push
+ *   right after a Version Packages PR merges. The README says so directly: "a commit
+ *   without any new changesets can always land on your base branch after a successful
+ *   publish... you need to figure out on your own how to skip." Unguarded, this would
+ *   tag `<name>@<version>` on every unrelated push to main once CHANGELOG.md exists.
+ *
+ * ★ THE CONDITION: proceed only if `CHANGELOG.md` has an entry for the current version
+ *   (proof `changeset version` really ran and wrote it) AND no git tag `<name>@<version>`
+ *   exists yet (proof this exact release was not already cut). Both checks are local —
+ *   no network, no GitHub API — and both work from the checkout `release.yml` already
+ *   has (`fetch-depth: 0`).
+ *
+ * ⛔ TELL changesets/action WHAT TO TAG. With a custom publish-script it learns what
+ *   shipped only from `CHANGESETS_OUTPUT`. Without it, the action warns "GitHub releases
+ *   and git tags cannot be created without this output" and creates neither.
+ */
+type Pkg = { readonly name: string; readonly version: string };
+
+/**
+ * Does CHANGELOG.md have a heading for this exact version?
+ * @changesets/changelog-github writes `## <version>` for a single, non-monorepo package.
+ */
+export async function changelogHasEntry(cwd: string, version: string): Promise<boolean> {
+  const file = Bun.file(`${cwd}/CHANGELOG.md`);
+  if (!(await file.exists())) return false;
+
+  const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^## ${escaped}$`, 'm').test(await file.text());
+}
+
+/**
+ * ⛔ DROP HUSKY GIT_DIR. `cwd` is not enough — pre-push exports GIT_DIR
+ *   and `git tag -l` then reads this checkout, not the throwaway repo.
+ *   Symptom: shouldRelease is false during verify and a test commits `init`
+ *   onto the branch being pushed.
+ */
+const gitEnv = (): NodeJS.ProcessEnv => {
+  const env = { ...process.env };
+  delete env.GIT_DIR;
+  delete env.GIT_WORK_TREE;
+  delete env.GIT_INDEX_FILE;
+  return env;
+};
+
+/** Does this exact tag already exist? Local `git tag -l`, no network. */
+export function tagExists(cwd: string, tag: string): boolean {
+  const result = Bun.spawnSync(['git', 'tag', '-l', tag], { cwd, env: gitEnv() });
+  return result.stdout.toString().trim() === tag;
+}
+
+export type ReleaseDecision = { readonly ok: boolean; readonly reason: string };
+
+export async function shouldRelease(cwd: string, pkg: Pkg): Promise<ReleaseDecision> {
+  const tag = `${pkg.name}@${pkg.version}`;
+
+  if (!(await changelogHasEntry(cwd, pkg.version))) {
+    return {
+      ok: false,
+      reason: `CHANGELOG.md has no "## ${pkg.version}" entry — changeset version has not run for this version`,
+    };
+  }
+  if (tagExists(cwd, tag)) {
+    return { ok: false, reason: `${tag} already exists — this version was already released` };
+  }
+  return { ok: true, reason: `CHANGELOG.md has the entry and ${tag} does not exist yet` };
+}
+
+/** One ndjson line changesets/action turns into a git tag and a GitHub Release. */
+export function tagEvent(pkg: Pkg): { type: 'git-tag'; tag: string; packageName: string } {
+  return { type: 'git-tag', tag: `${pkg.name}@${pkg.version}`, packageName: pkg.name };
+}
+
+/**
+ * App-repo publish-script. Reads `package.json` at `cwd`, gates on `shouldRelease`,
+ * and writes the tag event to `$CHANGESETS_OUTPUT` when this version is new.
+ *
+ * ⛔ `cwd` is the APP, never this package. Defaulting from `import.meta.url` after
+ *   publish would inspect `@homeflare/config` itself.
+ */
+export async function runAppRelease(cwd: string): Promise<ReleaseDecision> {
+  const pkg = (await Bun.file(`${cwd}/package.json`).json()) as Pkg;
+  const decision = await shouldRelease(cwd, pkg);
+
+  if (!decision.ok) {
+    process.stdout.write(`skip: ${decision.reason}\n`);
+    return decision;
+  }
+
+  const outputFile = process.env['CHANGESETS_OUTPUT'];
+  if (outputFile !== undefined) {
+    await Bun.write(outputFile, `${JSON.stringify(tagEvent(pkg))}\n`);
+  }
+  process.stdout.write(
+    `${pkg.name}@${pkg.version} — no npm publish; tagged (${decision.reason}).\n`,
+  );
+  return decision;
+}
+
+if (import.meta.main) {
+  await runAppRelease(process.cwd());
+}

package/src/require-release-config.ts

@@ -0,0 +1,100 @@
+/**
+ * Refuse to let `changeset version` run against a config that would silently no-op.
+ *
+ * 🔴 MEASURED 2026-09-16 on homeflare-openbao, TWO INDEPENDENT WAYS TO GET THE SAME
+ *   SILENT FAILURE. `@changesets/cli` 3.0.3 does neither of these things loudly:
+ *   1. `package.json` with no "version" — `changeset version` consumes the pending
+ *      changeset file, writes no `CHANGELOG.md`, leaves `package.json` untouched.
+ *   2. `"private": true` with no `privatePackages.version: true` in
+ *      `.changeset/config.json` — the package is excluded from versioning entirely;
+ *      `changeset status` reports zero packages to bump even with a real version and a
+ *      pending changeset file.
+ *   Either gap alone reproduces the same no-op. Both are required together.
+ *
+ * ★ This is regression protection against either field being dropped — a bad merge, a
+ *   hand-edit, a generator overwriting either file — not a bootstrap blocker.
+ *
+ * 🔴 A leftover `pnpm-workspace.yaml` that lists only nested packages hides the
+ *   root. `changeset version` then exits 1 ("package X is not in the workspace") —
+ *   measured 2026-09-17 on homeflare-secrets. `problemsFromPendingChangesets`
+ *   fails that before the version command consumes the file.
+ *
+ * ⛔ Path defaults are `process.cwd()`, NEVER `import.meta.url`. After publish this
+ *   file lives in `node_modules/@homeflare/config`; resolving next to it would check
+ *   the published package, not the app that invoked it.
+ */
+import { problemsFromPendingChangesets } from './changeset-workspace.ts';
+
+type Pkg = { readonly version?: unknown; readonly private?: unknown };
+type ChangesetConfig = { readonly privatePackages?: { readonly version?: unknown } };
+
+export type ReleaseConfigPaths = {
+  readonly pkgPath: string;
+  readonly changesetConfigPath: string;
+};
+
+/** Resolve the two files a version command must see. Override in tests. */
+export function releaseConfigPaths(cwd: string = process.cwd()): ReleaseConfigPaths {
+  return {
+    pkgPath: `${cwd}/package.json`,
+    changesetConfigPath: `${cwd}/.changeset/config.json`,
+  };
+}
+
+/** One thing a project should fix, in the imperative. */
+export async function problemsInReleaseConfig(paths: ReleaseConfigPaths): Promise<string[]> {
+  const pkg = (await Bun.file(paths.pkgPath).json()) as Pkg;
+  const problems: string[] = [];
+
+  if (typeof pkg.version !== 'string' || pkg.version.length === 0) {
+    problems.push(`${paths.pkgPath} has no "version" — changeset version would silently no-op`);
+  }
+
+  if (pkg.private === true) {
+    const changesetConfig = (await Bun.file(paths.changesetConfigPath).json()) as ChangesetConfig;
+    if (changesetConfig.privatePackages?.version !== true) {
+      problems.push(
+        `${paths.changesetConfigPath} has no privatePackages.version: true — a private package ` +
+          'is excluded from versioning entirely, which reads as "nothing to release"',
+      );
+    }
+  }
+
+  const cwd = paths.pkgPath.replace(/\/package\.json$/, '');
+  problems.push(...(await problemsFromPendingChangesets(cwd)));
+
+  return problems;
+}
+
+/** Print and exit. App `version` scripts call this before `changeset version`. */
+export async function runRequireReleaseConfig(paths?: Partial<ReleaseConfigPaths>): Promise<void> {
+  // ⚠️ A spread of `{ pkgPath: undefined }` from `process.argv[2]` would overwrite the
+  //   cwd default. Only copy keys that are actually present.
+  const defaults = releaseConfigPaths();
+  const resolved: ReleaseConfigPaths = {
+    pkgPath: paths?.pkgPath ?? defaults.pkgPath,
+    changesetConfigPath: paths?.changesetConfigPath ?? defaults.changesetConfigPath,
+  };
+  const problems = await problemsInReleaseConfig(resolved);
+
+  if (problems.length > 0) {
+    process.stderr.write('\n✗ changeset version would silently no-op:\n');
+    for (const problem of problems) process.stderr.write(`  - ${problem}\n`);
+    process.stderr.write('\n  Fix the file(s) above in a reviewed commit, then re-run this.\n\n');
+    process.exit(1);
+  }
+
+  const pkg = (await Bun.file(resolved.pkgPath).json()) as Pkg;
+  process.stdout.write(
+    `ok: ${resolved.pkgPath} version is ${pkg.version}, privatePackages.version is set\n`,
+  );
+}
+
+if (import.meta.main) {
+  const pkgPath = process.argv[2];
+  const changesetConfigPath = process.argv[3];
+  await runRequireReleaseConfig({
+    ...(pkgPath === undefined ? {} : { pkgPath }),
+    ...(changesetConfigPath === undefined ? {} : { changesetConfigPath }),
+  });
+}