@bensandee/tooling 0.61.0 → 0.62.0

package/README.md

@@ -137,7 +137,7 @@ Opt out entirely with `"pnpmWorkspace": false` in `.tooling.json`; the generator
 | Command                          | Description                                                                                                                                                                    |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `tooling release:changesets`     | Changesets version/publish for Forgejo CI. Flags: `--dry-run`, `--verbose`. Env: `FORGEJO_SERVER_URL`, `FORGEJO_REPOSITORY`, `RELEASE_TOKEN`.                                  |
-| `tooling release:simple`         | Streamlined release using commit-and-tag-version. Flags: `--release-as`, `--first-release`, `--prerelease`, `--verbose`.                                                       |
+| `tooling release:simple`         | Streamlined release using commit-and-tag-version. Flags: `--release-as`, `--first-release`, `--prerelease`, `--verbose`. Env: `RELEASE_TOKEN` (required on every platform).    |
 | `tooling release:trigger`        | Trigger a release workflow.                                                                                                                                                    |
 | `tooling workflow:dispatch`      | Dispatch a `workflow_dispatch` event for any workflow in any repo on the same git host. Flags: `--repo`, `--workflow` (required), `--ref`, `--input key=value` (repeatable).   |
 | `tooling forgejo:create-release` | Create a Forgejo release from a tag.                                                                                                                                           |
@@ -170,6 +170,10 @@ tooling release:simple --release-as major --prerelease beta  # → 2.0.0-beta.0
 
 The generated release workflow exposes these as optional `workflow_dispatch` inputs (`bump` and `prerelease`), so bumps can also be controlled from the CI UI.
 
+**Authentication:** `release:simple` requires `RELEASE_TOKEN` (a Personal Access Token with write access on the target forge) on every platform — Forgejo, GitHub, and GitHub Enterprise alike. The runner's auto-injected token (`github.token` / Forgejo Actions' internal auth) is never used: `actions/checkout@v6` writes that token to git config as an `http.<serverUrl>/.extraheader`, which silently overrides URL-embedded credentials and authenticates pushes as the runner pseudo-user. On Forgejo that pseudo-user is `uid=-2`, which fails the pre-receive hook (`Internal Server Error`); on GitHub Enterprise the same shape can mask custom hook rejections. `release:simple` actively unsets the extraheader and rewrites the remote URL with `RELEASE_TOKEN` before pushing.
+
+GitHub consumers that previously relied on `github.token` must mint a PAT (scope: `contents: write`) and store it as the `RELEASE_TOKEN` secret on the repo or org.
+
 #### `workflow:dispatch`
 
 Triggers a `workflow_dispatch` event for an arbitrary workflow in an arbitrary repo on the same git host — useful for release→deploy patterns where one repo's CI kicks off a workflow in another (e.g. an infra repo). `release:trigger` is a special case of this command, pinned to `release.yml` in the current repo.

package/dist/bin.mjs

@@ -844,15 +844,24 @@ function parseGitUrl(urlStr) {
 	}
 }
 /**
-* Configure the git remote origin to use a Forgejo token for push auth.
+* Configure the git remote origin to push as `token` regardless of what
+* `actions/checkout` left behind.
 *
-* This is necessary because `actions/checkout` configures git with the automatic
-* GITHUB_TOKEN, which may not have push permissions. Using RELEASE_TOKEN ensures
-* pushes use the explicitly provided token.
+* `actions/checkout@v6` injects an HTTP Authorization header into git config
+* under `http.<serverUrl>/.extraheader`. That header overrides Basic auth
+* embedded in the remote URL, so a `git remote set-url` alone is not enough —
+* the runner's pseudo-user token still wins and the push authenticates as
+* uid=-2 on Forgejo (and as the runner identity on GitHub Enterprise with
+* custom pre-receive hooks). Unset the extraheader before rewriting the URL.
 */
-function configureGitAuth(executor, conn, cwd) {
-	const host = conn.serverUrl.replace(/^https?:\/\//, "");
-	const authUrl = `https://x-access-token:${conn.token}@${host}/${conn.repository}`;
+function configureGitAuth(executor, coords, cwd) {
+	const host = coords.serverUrl.replace(/^https?:\/\//, "");
+	executor.exec("git", [
+		"config",
+		"--unset-all",
+		`http.${coords.serverUrl}/.extraheader`
+	], { cwd });
+	const authUrl = `https://x-access-token:${coords.token}@${host}/${coords.repository}`;
 	executor.exec("git", [
 		"remote",
 		"set-url",
@@ -1580,11 +1589,21 @@ function buildWorkflowYaml(options) {
 	doc["on"] = options.on;
 	if (options.permissions) doc["permissions"] = options.permissions;
 	if (options.concurrency) doc["concurrency"] = options.concurrency;
-	doc["jobs"] = { [options.jobName]: {
+	const jobs = { [options.jobName]: {
 		"runs-on": options.runsOn ?? "ubuntu-latest",
 		...options.jobEnv && { env: options.jobEnv },
+		...options.jobOutputs && { outputs: options.jobOutputs },
 		steps: options.steps.map((s) => s.step)
 	} };
+	for (const [name, def] of Object.entries(options.extraJobs ?? {})) jobs[name] = {
+		...def.needs && { needs: def.needs },
+		...def.if && { if: def.if },
+		...def["continue-on-error"] && { "continue-on-error": true },
+		"runs-on": def.runsOn ?? "ubuntu-latest",
+		...def.env && { env: def.env },
+		steps: def.steps.map((s) => s.step)
+	};
+	doc["jobs"] = jobs;
 	const readable = stringify(doc, {
 		lineWidth: 0,
 		nullStr: ""
@@ -2206,7 +2225,7 @@ async function generatePackageJson(ctx) {
 	const devDeps = { ...ROOT_DEV_DEPS };
 	if (!isMonorepo) Object.assign(devDeps, PER_PACKAGE_DEV_DEPS);
 	devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.11.3";
-	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.61.0";
+	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.62.0";
 	if (ctx.config.useEslintPlugin) devDeps["@bensandee/eslint-plugin"] = isWorkspacePackage(ctx, "@bensandee/eslint-plugin") ? "workspace:*" : "0.13.0";
 	if (ctx.config.formatter === "oxfmt") devDeps["oxfmt"] = {
 		"@changesets/cli": "2.31.0",
@@ -3172,6 +3191,67 @@ async function responseBodyText(res) {
 		return "(could not read response body)";
 	}
 }
+const SwaggerEnvelopeSchema = z.union([z.object({ message: z.literal("") }), z.object({
+	message: z.string(),
+	url: z.string().regex(/\/api\/swagger$/)
+})]);
+/**
+* Detect Forgejo's signature "route not handled" response shape — empty body
+* or a JSON envelope with either an empty `message` or a `url` pointing at
+* `/api/swagger`. Forgejo returns this from a 500 (and sometimes 404) when no
+* route handles the request, even though the status code suggests a
+* server-side fault.
+*/
+function isForgejoGenericServerErrorBody(body) {
+	if (body === "") return true;
+	try {
+		const parsed = JSON.parse(body);
+		return SwaggerEnvelopeSchema.safeParse(parsed).success;
+	} catch (_error) {
+		return false;
+	}
+}
+const DISPATCH_VERB_PATTERN = /\bdispatch\b/i;
+/**
+* Map a non-2xx Forgejo response to a human-readable hint.
+*
+* Returns the most-likely cause first; callers still surface the raw body so an
+* uncommon failure mode isn't masked. Returns "" for unmapped codes (2xx/3xx,
+* teapots) so the caller can decide whether to include a Hint line at all.
+*/
+function forgejoErrorHint(status, body, operation) {
+	const isDispatch = DISPATCH_VERB_PATTERN.test(operation.verb);
+	const resource = operation.resource ?? "the resource";
+	if (status === 401 || status === 403) return `Forgejo rejected the token. It needs the scope required for "${operation.verb}" on ${resource}.`;
+	if (status === 404) {
+		const base = `"${resource}" was not found on the server. Verify the name${operation.ref ? `, that it exists on ${operation.ref}` : ""}, and that the token can see it.`;
+		return isDispatch ? `${base} For dispatch, also confirm the workflow has an "on: workflow_dispatch:" trigger.` : base;
+	}
+	if (status === 400 || status === 422) {
+		const base = `Forgejo rejected the request payload for "${operation.verb}". Check for missing or invalid fields.`;
+		return isDispatch ? `${base} For dispatch, common causes are a missing "on: workflow_dispatch:" trigger or a required input not being provided.` : base;
+	}
+	if (status >= 500 && status < 600) {
+		if (isForgejoGenericServerErrorBody(body)) {
+			const ref = operation.ref ? ` on ${operation.ref}` : "";
+			return `Forgejo returned a generic server error. Most often this means the requested route is unavailable${isDispatch ? ` (e.g. "${resource}" doesn't exist${ref}, or the workflow lacks an "on: workflow_dispatch:" trigger)` : ""}. Less commonly: the token lacks scope, or it is a server-side bug.`;
+		}
+		return `Forgejo server error — usually transient. Retry; if it persists, check the server logs.`;
+	}
+	return "";
+}
+/**
+* Build a richer error message for a non-2xx Forgejo API response.
+*
+* Reads, truncates, and redacts the body via {@link responseBodyText}; appends
+* a `Hint:` line when {@link forgejoErrorHint} has one; appends the raw body as
+* a `Response:` block. Callers still pick the error class (Transient vs Fatal).
+*/
+async function forgejoErrorMessage(res, operation) {
+	const body = await responseBodyText(res);
+	const hint = forgejoErrorHint(res.status, body, operation);
+	return `Failed to ${operation.verb} on Forgejo: ${String(res.status)} ${res.statusText}` + (hint ? `\nHint: ${hint}` : "") + (body ? `\nResponse: ${body}` : "");
+}
 const PullRequestSchema = z.array(z.object({
 	number: z.number(),
 	head: z.object({ ref: z.string() })
@@ -3185,10 +3265,10 @@ const PullRequestSchema = z.array(z.object({
 async function findOpenPr(executor, conn, head) {
 	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/pulls?state=open`;
 	const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
-	if (!res.ok) {
-		const body = await responseBodyText(res);
-		throw new TransientError(`Failed to list PRs: ${res.status} ${res.statusText}\n${body}`);
-	}
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "list PRs",
+		resource: conn.repository
+	}));
 	const parsed = PullRequestSchema.safeParse(await res.json());
 	if (!parsed.success) throw new UnexpectedError(`Unexpected PR list response: ${parsed.error.message}`);
 	return parsed.data.find((pr) => pr.head.ref === head)?.number ?? null;
@@ -3210,10 +3290,10 @@ async function createPr(executor, conn, options) {
 		},
 		body: JSON.stringify(payload)
 	});
-	if (!res.ok) {
-		const body = await responseBodyText(res);
-		throw new TransientError(`Failed to create PR: ${res.status} ${res.statusText}\n${body}`);
-	}
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "create PR",
+		resource: `${options.head}→${options.base}`
+	}));
 }
 /** Update an existing pull request's title and body. */
 async function updatePr(executor, conn, prNumber, options) {
@@ -3229,10 +3309,10 @@ async function updatePr(executor, conn, prNumber, options) {
 			body: options.body
 		})
 	});
-	if (!res.ok) {
-		const body = await responseBodyText(res);
-		throw new TransientError(`Failed to update PR #${String(prNumber)}: ${res.status} ${res.statusText}\n${body}`);
-	}
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "update PR",
+		resource: `#${String(prNumber)}`
+	}));
 }
 /** Merge a pull request by number. */
 async function mergePr(executor, conn, prNumber, options) {
@@ -3248,10 +3328,10 @@ async function mergePr(executor, conn, prNumber, options) {
 			delete_branch_after_merge: options?.deleteBranch ?? true
 		})
 	});
-	if (!res.ok) {
-		const body = await responseBodyText(res);
-		throw new TransientError(`Failed to merge PR #${String(prNumber)}: ${res.status} ${res.statusText}\n${body}`);
-	}
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "merge PR",
+		resource: `#${String(prNumber)}`
+	}));
 }
 /** Check whether a Forgejo release already exists for a given tag. */
 async function findRelease(executor, conn, tag) {
@@ -3260,8 +3340,10 @@ async function findRelease(executor, conn, tag) {
 	const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
 	if (res.status === 200) return true;
 	if (res.status === 404) return false;
-	const body = await responseBodyText(res);
-	throw new TransientError(`Failed to check release for ${tag}: ${res.status} ${res.statusText}\n${body}`);
+	throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "check release",
+		resource: tag
+	}));
 }
 /** Create a Forgejo release for a given tag. */
 async function createRelease(executor, conn, tag) {
@@ -3278,10 +3360,10 @@ async function createRelease(executor, conn, tag) {
 			body: `Published ${tag}`
 		})
 	});
-	if (!res.ok) {
-		const body = await responseBodyText(res);
-		throw new TransientError(`Failed to create release for ${tag}: ${res.status} ${res.statusText}\n${body}`);
-	}
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "create release",
+		resource: tag
+	}));
 }
 /**
 * Ensure a Forgejo release exists for a tag, creating it if necessary.
@@ -3313,10 +3395,10 @@ async function uploadReleaseAsset(executor, conn, tag, options) {
 	const encodedTag = encodeURIComponent(tag);
 	const releaseUrl = `${conn.serverUrl}/api/v1/repos/${conn.repository}/releases/tags/${encodedTag}`;
 	const releaseRes = await executor.fetch(releaseUrl, { headers: { Authorization: `token ${conn.token}` } });
-	if (!releaseRes.ok) {
-		const body = await responseBodyText(releaseRes);
-		throw new TransientError(`Failed to get release for ${tag}: ${String(releaseRes.status)} ${releaseRes.statusText}\n${body}`);
-	}
+	if (!releaseRes.ok) throw new TransientError(await forgejoErrorMessage(releaseRes, {
+		verb: "get release",
+		resource: tag
+	}));
 	const parsed = z.object({ id: z.number() }).safeParse(await releaseRes.json());
 	if (!parsed.success) throw new UnexpectedError(`Unexpected release response: ${parsed.error.message}`);
 	const releaseId = parsed.data.id;
@@ -3328,10 +3410,10 @@ async function uploadReleaseAsset(executor, conn, tag, options) {
 		headers: { Authorization: `token ${conn.token}` },
 		body: form
 	});
-	if (!res.ok) {
-		const body = await responseBodyText(res);
-		throw new TransientError(`Failed to upload asset ${options.assetName} to ${tag}: ${String(res.status)} ${res.statusText}\n${body}`);
-	}
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "upload asset",
+		resource: `${options.assetName} to ${tag}`
+	}));
 }
 const ActionSecretListSchema = z.object({
 	secrets: z.array(z.object({ name: z.string() })),
@@ -3362,10 +3444,10 @@ async function createAccessToken(executor, serverUrl, username, password, tokenN
 			scopes
 		})
 	});
-	if (!res.ok) {
-		const body = await responseBodyText(res);
-		throw new TransientError(`Failed to create access token: ${String(res.status)} ${res.statusText}\n${body}`);
-	}
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "create access token",
+		resource: username
+	}));
 	const parsed = AccessTokenResponseSchema.safeParse(await res.json());
 	if (!parsed.success) throw new UnexpectedError(`Unexpected token response: ${parsed.error.message}`);
 	return parsed.data.sha1;
@@ -3386,10 +3468,10 @@ async function setActionSecret(executor, conn, secretName, secretValue) {
 		},
 		body: JSON.stringify({ data: secretValue })
 	});
-	if (!res.ok) {
-		const body = await responseBodyText(res);
-		throw new TransientError(`Failed to set secret ${secretName}: ${String(res.status)} ${res.statusText}\n${body}`);
-	}
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "set secret",
+		resource: secretName
+	}));
 }
 /**
 * Set (or overwrite) a Forgejo Actions secret at the user level.
@@ -3412,10 +3494,10 @@ async function setUserActionSecret(executor, serverUrl, authorization, secretNam
 		headers,
 		body: JSON.stringify({ data: secretValue })
 	});
-	if (!res.ok) {
-		const body = await responseBodyText(res);
-		throw new TransientError(`Failed to set user secret ${secretName}: ${String(res.status)} ${res.statusText}\n${body}`);
-	}
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "set user secret",
+		resource: secretName
+	}));
 }
 /**
 * List Forgejo Actions secret names for a repository.
@@ -3431,10 +3513,10 @@ async function listActionSecrets(executor, conn) {
 	for (;;) {
 		const url = `${conn.serverUrl}/api/v1/repos/${owner}/${repo}/actions/secrets?page=${String(page)}&limit=${String(limit)}`;
 		const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
-		if (!res.ok) {
-			const body = await responseBodyText(res);
-			throw new TransientError(`Failed to list secrets: ${String(res.status)} ${res.statusText}\n${body}`);
-		}
+		if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+			verb: "list secrets",
+			resource: `${owner}/${repo}`
+		}));
 		const parsed = ActionSecretListSchema.safeParse(await res.json());
 		if (!parsed.success) throw new UnexpectedError(`Unexpected secrets list response: ${parsed.error.message}`);
 		for (const secret of parsed.data.secrets) names.push(secret.name);
@@ -3455,10 +3537,10 @@ async function deleteActionSecret(executor, conn, secretName) {
 		method: "DELETE",
 		headers: { Authorization: `token ${conn.token}` }
 	});
-	if (!res.ok) {
-		const body = await responseBodyText(res);
-		throw new TransientError(`Failed to delete secret ${secretName}: ${String(res.status)} ${res.statusText}\n${body}`);
-	}
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "delete secret",
+		resource: secretName
+	}));
 }
 const WebhookSchema = z.object({
 	id: z.number(),
@@ -3467,6 +3549,11 @@ const WebhookSchema = z.object({
 	config: z.record(z.string(), z.string()).optional()
 });
 const WebhookListSchema = z.array(WebhookSchema);
+/**
+* Returns a status struct instead of throwing, so it deliberately does not use
+* {@link forgejoErrorMessage} — the caller branches on `status` rather than
+* catching an error.
+*/
 async function fetchHooks(executor, conn, endpoint) {
 	const res = await executor.fetch(`${conn.serverUrl}/api/v1${endpoint}`, { headers: { Authorization: `token ${conn.token}` } });
 	if (res.status === 401 || res.status === 403) return {
@@ -3531,17 +3618,17 @@ async function hasAdminAccess(executor, conn) {
 const OrgSchema = z.object({ username: z.string() });
 const OrgListSchema = z.array(OrgSchema);
 const PAGE_LIMIT = 50;
-async function paginate(executor, conn, endpoint, extract) {
+async function paginate(executor, conn, endpoint, verb, extract) {
 	const all = [];
 	let page = 1;
 	const separator = endpoint.includes("?") ? "&" : "?";
 	for (;;) {
 		const url = `${conn.serverUrl}/api/v1${endpoint}${separator}page=${String(page)}&limit=${String(PAGE_LIMIT)}`;
 		const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
-		if (!res.ok) {
-			const body = await responseBodyText(res);
-			throw new TransientError(`Failed to fetch ${endpoint} (page ${String(page)}): ${String(res.status)} ${res.statusText}\n${body}`);
-		}
+		if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+			verb,
+			resource: `${endpoint} (page ${String(page)})`
+		}));
 		const items = extract(await res.json());
 		all.push(...items);
 		if (items.length < PAGE_LIMIT) break;
@@ -3555,7 +3642,7 @@ async function paginate(executor, conn, endpoint, extract) {
 */
 async function listOrgs(executor, conn, mode) {
 	const endpoint = mode === "admin" ? "/admin/orgs" : "/user/orgs";
-	return (await paginate(executor, conn, endpoint, (raw) => {
+	return (await paginate(executor, conn, endpoint, "list orgs", (raw) => {
 		const parsed = OrgListSchema.safeParse(raw);
 		if (!parsed.success) throw new UnexpectedError(`Unexpected ${endpoint} response: ${parsed.error.message}`);
 		return parsed.data;
@@ -3564,7 +3651,7 @@ async function listOrgs(executor, conn, mode) {
 const RepoSearchSchema = z.object({ data: z.array(z.object({ full_name: z.string() })) });
 /** List repositories visible to the token via `/repos/search`. */
 async function searchRepos(executor, conn) {
-	return (await paginate(executor, conn, "/repos/search", (raw) => {
+	return (await paginate(executor, conn, "/repos/search", "list repos", (raw) => {
 		const parsed = RepoSearchSchema.safeParse(raw);
 		if (!parsed.success) throw new UnexpectedError(`Unexpected /repos/search response: ${parsed.error.message}`);
 		return parsed.data.data;
@@ -3772,7 +3859,11 @@ async function generateGitignore(ctx) {
 }
 //#endregion
 //#region src/generators/release-ci.ts
-const DEFAULT_POST_RELEASE_COMMAND = ["pnpm exec bst webhook:send", " \"$POST_RELEASE_HOOK_URL\""].join("");
+const DEFAULT_POST_RELEASE_COMMAND = [
+	"pnpm exec bst webhook:send",
+	" \"$POST_RELEASE_HOOK_URL\"",
+	" --tag \"$RELEASE_TAG\""
+].join("");
 /** Map secret names to `${{ secrets.<NAME> }}` env entries. */
 function secretsEnv(secrets) {
 	const env = {};
@@ -3798,6 +3889,26 @@ function postReleaseHookStep(opts) {
 	} };
 }
 /**
+* Post-release hook as a separate job with `continue-on-error: true` so a
+* webhook failure (HTTP 5xx, DNS, etc.) shows up as a red job in the run UI
+* without failing the overall workflow conclusion.
+*/
+function postReleaseHookJob(opts) {
+	return {
+		needs: opts.needsJob,
+		if: opts.publishCondition,
+		"continue-on-error": true,
+		steps: [...commonSteps(opts.nodeVersionYaml, opts.publishesNpm), { step: {
+			name: "Post-release hook",
+			env: {
+				...hookSecretEnv(opts.secrets),
+				RELEASE_TAG: opts.releaseTagExpr
+			},
+			run: opts.command ?? DEFAULT_POST_RELEASE_COMMAND
+		} }]
+	};
+}
+/**
 * Step that dispatches a `workflow_dispatch` event to another repo after a
 * release, triggering a downstream deploy. The release tag is forwarded from
 * the `release` step's `tag` output.
@@ -3845,7 +3956,7 @@ function commonSteps(nodeVersionYaml, publishesNpm) {
 	];
 }
 function releaseItSteps(ci, nodeVersionYaml, publishesNpm) {
-	const tokenEnv = ci === "github" ? { GITHUB_TOKEN: actionsExpr("github.token") } : { RELEASE_TOKEN: actionsExpr("secrets.RELEASE_TOKEN") };
+	const tokenEnv = ci === "github" ? { GITHUB_TOKEN: actionsExpr("secrets.RELEASE_TOKEN") } : { RELEASE_TOKEN: actionsExpr("secrets.RELEASE_TOKEN") };
 	const npmEnv = publishesNpm ? { NODE_AUTH_TOKEN: actionsExpr("secrets.NPM_TOKEN") } : {};
 	return [...commonSteps(nodeVersionYaml, publishesNpm), { step: {
 		run: "pnpm release-it --ci",
@@ -3881,7 +3992,11 @@ function simpleWorkflowDispatchTrigger() {
 }
 /** Platform connection env so a `bst` step can resolve the git host. */
 function connectionEnv(ci) {
-	return ci === "github" ? { GITHUB_TOKEN: actionsExpr("github.token") } : {
+	if (ci === "github") return {
+		RELEASE_TOKEN: actionsExpr("secrets.RELEASE_TOKEN"),
+		GITHUB_TOKEN: actionsExpr("secrets.RELEASE_TOKEN")
+	};
+	return {
 		FORGEJO_SERVER_URL: actionsExpr("github.server_url"),
 		FORGEJO_REPOSITORY: actionsExpr("github.repository"),
 		RELEASE_TOKEN: actionsExpr("secrets.RELEASE_TOKEN")
@@ -3970,15 +4085,27 @@ async function generateReleaseCi(ctx) {
 			secrets: hookSecrets
 		}));
 	}
+	let extraJobs;
+	let jobOutputs;
 	if (ctx.config.releaseStrategy === "release-it") steps.push(postReleaseHookStep({
 		command: getPostReleaseHookCommand(ctx),
 		secrets: hookSecrets
 	}));
-	else if (ctx.config.releaseStrategy === "simple") steps.push(postReleaseHookStep({
-		command: getPostReleaseHookCommand(ctx),
-		secrets: hookSecrets,
-		condition: "steps.release.outputs.pushed == 'true'"
-	}));
+	else if (ctx.config.releaseStrategy === "simple") {
+		jobOutputs = {
+			pushed: actionsExpr("steps.release.outputs.pushed"),
+			tag: actionsExpr("steps.release.outputs.tag")
+		};
+		extraJobs = { "post-release-hook": postReleaseHookJob({
+			needsJob: "release",
+			publishCondition: "needs.release.outputs.pushed == 'true'",
+			releaseTagExpr: actionsExpr("needs.release.outputs.tag"),
+			command: getPostReleaseHookCommand(ctx),
+			secrets: hookSecrets,
+			nodeVersionYaml,
+			publishesNpm
+		}) };
+	}
 	const on = ctx.config.releaseStrategy === "simple" ? simpleWorkflowDispatchTrigger() : { workflow_dispatch: null };
 	const content = buildWorkflowYaml({
 		ci: ctx.config.ci,
@@ -3986,7 +4113,9 @@ async function generateReleaseCi(ctx) {
 		on,
 		...isGitHub && { permissions: { contents: "write" } },
 		jobName: "release",
-		steps
+		...jobOutputs && { jobOutputs },
+		steps,
+		...extraJobs && { extraJobs }
 	});
 	const alreadyExists = ctx.exists(workflowPath);
 	const existing = alreadyExists ? ctx.read(workflowPath) : void 0;
@@ -4043,7 +4172,7 @@ function changesetsReleaseStep(ci, publishesNpm) {
 			version: "pnpm changeset version"
 		},
 		env: {
-			GITHUB_TOKEN: actionsExpr("github.token"),
+			GITHUB_TOKEN: actionsExpr("secrets.RELEASE_TOKEN"),
 			...publishesNpm && { NPM_TOKEN: actionsExpr("secrets.NPM_TOKEN") }
 		}
 	} };
@@ -4112,8 +4241,16 @@ async function generateCi(ctx) {
 	const hasAssets = isChangesets && hasReleaseAssets(ctx);
 	const host = hasDocker ? resolveGenTimeHost(ctx) : null;
 	const publishedIf = "steps.release.outputs.published == 'true'";
+	const githubChangesetsDeriveTagStep = { step: {
+		name: "Derive release tag",
+		id: "derive-tag",
+		if: publishedIf,
+		env: { PUBLISHED_PACKAGES: actionsExpr("steps.release.outputs.publishedPackages") },
+		run: "echo \"tag=$(echo \"$PUBLISHED_PACKAGES\" | jq -r '.[0] | \"\\(.name)@\\(.version)\"')\" >> \"$GITHUB_OUTPUT\""
+	} };
+	const changesetsTagOutputExpr = isGitHub ? actionsExpr("steps.derive-tag.outputs.tag") : actionsExpr("steps.release.outputs.tag");
 	const releaseEnv = {};
-	if (isGitHub) releaseEnv["GITHUB_TOKEN"] = actionsExpr("github.token");
+	if (isGitHub) releaseEnv["GITHUB_TOKEN"] = actionsExpr("secrets.RELEASE_TOKEN");
 	else {
 		releaseEnv["FORGEJO_SERVER_URL"] = actionsExpr("github.server_url");
 		releaseEnv["FORGEJO_REPOSITORY"] = actionsExpr("github.repository");
@@ -4123,6 +4260,7 @@ async function generateCi(ctx) {
 		...checkSteps(nodeVersionYaml, isChangesets && publishesNpm, coverage.enabled),
 		...emitCoverageSteps ? coverageHistorySteps() : [],
 		...isChangesets ? [changesetsReleaseStep(ctx.config.ci, publishesNpm)] : [],
+		...isChangesets && isGitHub ? [githubChangesetsDeriveTagStep] : [],
 		...hasAssets ? [{ step: {
 			name: "Upload Release Assets",
 			if: publishedIf,
@@ -4141,13 +4279,25 @@ async function generateCi(ctx) {
 			releaseEnv,
 			condition: publishedIf,
 			secrets: hookSecrets
-		})] : [],
-		...isChangesets ? [postReleaseHookStep({
-			command: hookCommand,
-			secrets: hookSecrets,
-			condition: publishedIf
 		})] : []
 	];
+	let extraJobs;
+	let jobOutputs;
+	if (isChangesets) {
+		jobOutputs = {
+			published: actionsExpr("steps.release.outputs.published"),
+			tag: changesetsTagOutputExpr
+		};
+		extraJobs = { "post-release-hook": postReleaseHookJob({
+			needsJob: "check",
+			publishCondition: "needs.check.outputs.published == 'true'",
+			releaseTagExpr: actionsExpr("needs.check.outputs.tag"),
+			command: hookCommand,
+			secrets: hookSecrets,
+			nodeVersionYaml,
+			publishesNpm
+		}) };
+	}
 	const content = buildWorkflowYaml({
 		ci: ctx.config.ci,
 		name: "CI",
@@ -4163,7 +4313,9 @@ async function generateCi(ctx) {
 		...isChangesets && { concurrency: CI_CONCURRENCY },
 		jobName: "check",
 		...emitCoverageSteps && { jobEnv: IS_MAIN_JOB_ENV },
-		steps
+		...jobOutputs && { jobOutputs },
+		steps,
+		...extraJobs && { extraJobs }
 	});
 	const filePath = ciWorkflowPath(ctx.config.ci, ctx.config.releaseStrategy);
 	const alreadyExists = ctx.exists(filePath);
@@ -5273,7 +5425,7 @@ async function runGenerators(ctx) {
 function generateMigratePrompt(results, config, detected) {
 	const sections = [];
 	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.61.0 repo:sync\` on ${timestamp}_\n`);
+	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.62.0 repo:sync\` on ${timestamp}_\n`);
 	const changed = results.filter((r) => r.action === "created" || r.action === "updated" || r.action === "archived");
 	if (changed.length > 0) {
 		const items = changed.map((r) => {
@@ -6239,10 +6391,11 @@ async function dispatchForgejo(conn, options, executor) {
 		},
 		body: JSON.stringify(body)
 	});
-	if (!res.ok) {
-		const text = await res.text();
-		throw new FatalError(`Failed to dispatch workflow on Forgejo: ${String(res.status)} ${res.statusText}` + (text ? `\n${text}` : ""));
-	}
+	if (!res.ok) throw new FatalError(await forgejoErrorMessage(res, {
+		verb: "dispatch workflow",
+		resource: options.workflow,
+		ref: options.ref
+	}));
 	log.info(`Dispatched ${options.workflow} on ${repo} (ref: ${options.ref})`);
 }
 function dispatchGitHub(options, executor) {
@@ -6472,6 +6625,39 @@ function readVersion(executor, cwd) {
 function platformType(config) {
 	return config.platform?.type === "github" ? "github" : "forgejo";
 }
+/**
+* Resolve the serverUrl + repository the push will target so the auth URL
+* can be rewritten in `configureGitAuth`. For Forgejo we already have these
+* in the connection. For GitHub, prefer the Actions-injected env vars
+* (also set on Forgejo runners that emulate GitHub Actions) and fall back to
+* parsing package.json so local invocations still work.
+*/
+function resolveAuthCoordinates(executor, config, token) {
+	if (config.platform?.type === "forgejo") return {
+		serverUrl: config.platform.conn.serverUrl,
+		repository: config.platform.conn.repository,
+		token
+	};
+	const envServer = process.env["GITHUB_SERVER_URL"]?.trim();
+	const envRepo = process.env["GITHUB_REPOSITORY"]?.trim();
+	if (envServer && envRepo) return {
+		serverUrl: envServer,
+		repository: envRepo,
+		token
+	};
+	const pkgRaw = executor.readFile(path.join(config.cwd, "package.json"));
+	if (!pkgRaw) return void 0;
+	const repoField = parsePackageJson(pkgRaw)?.repository;
+	const urlStr = typeof repoField === "string" ? repoField : repoField?.url;
+	if (!urlStr) return void 0;
+	const parsed = parseGitUrl(urlStr);
+	if (!parsed) return void 0;
+	return {
+		serverUrl: `${parsed.protocol}//${parsed.hostname}`,
+		repository: parsed.repository,
+		token
+	};
+}
 /** Check whether a "tag already exists" failure can be recovered from. */
 function recoverFromExistingTag(executor, config, output) {
 	const match = /tag '([^']+)' already exists/.exec(output);
@@ -6486,6 +6672,8 @@ function recoverFromExistingTag(executor, config, output) {
 }
 /** Run the full commit-and-tag-version release flow. */
 async function runSimpleRelease(executor, config) {
+	const releaseToken = process.env["RELEASE_TOKEN"]?.trim();
+	if (!releaseToken) throw new FatalError("RELEASE_TOKEN environment variable is required for release:simple. Create a PAT with write:repository (Forgejo) or contents: write (GitHub) scope on the target forge, store it as the RELEASE_TOKEN secret on your repo (or org), and expose it as env to this step.");
 	const platform = platformType(config);
 	debug(config, `Platform: ${platform}`);
 	debug(config, `Config: dryRun=${String(config.dryRun)} noPush=${String(config.noPush)} noSlidingTags=${String(config.noSlidingTags)} noRelease=${String(config.noRelease)}`);
@@ -6529,10 +6717,11 @@ async function runSimpleRelease(executor, config) {
 	}
 	let pushed = false;
 	if (!config.noPush) {
-		if (config.platform?.type === "forgejo") {
-			configureGitAuth(executor, config.platform.conn, config.cwd);
-			debug(config, `Configured git remote auth for ${config.platform.conn.repository}`);
-		}
+		const authCoords = resolveAuthCoordinates(executor, config, releaseToken);
+		if (authCoords) {
+			configureGitAuth(executor, authCoords, config.cwd);
+			debug(config, `Configured git remote auth for ${authCoords.repository}`);
+		} else debug(config, "Skipping git remote auth: could not resolve server URL / repository");
 		const branch = executor.exec("git", [
 			"rev-parse",
 			"--abbrev-ref",
@@ -8450,7 +8639,8 @@ function maskSecret(secret) {
 }
 /**
 * Send a webhook and log the result. Intended for CLI usage.
-* Never throws.
+* Returns the underlying result so the caller can decide whether to
+* surface a non-zero exit. Never throws.
 */
 async function sendWebhookWithLogging(url, secret, payload) {
 	const result = await sendWebhook({
@@ -8460,10 +8650,27 @@ async function sendWebhookWithLogging(url, secret, payload) {
 	});
 	const context = `url=${url}, secret=${maskSecret(secret)}`;
 	if (result.ok) log.info(`Post-release hook completed successfully (${context})`);
-	else log.warn(`Post-release hook failed: ${result.error ?? "unknown error"} (${context})`);
+	else log.error(`Post-release hook failed: ${result.error ?? "unknown error"} (${context})`);
+	return result;
 }
 //#endregion
 //#region src/commands/webhook-send.ts
+/**
+* Choose the payload source for `webhook:send`. When `--tag` or
+* `--repository` is set, build from flags via `buildSimplePayload` — this
+* makes the explicit tag win over `GITHUB_REF`, which is often `refs/heads/main`
+* (not a tag) when the post-release hook fires.
+*/
+function resolveWebhookPayload(args, env = process.env) {
+	if (args.tag || args.repository) return buildSimplePayload({
+		tag: args.tag ?? "",
+		repository: args.repository ?? env["GITHUB_REPOSITORY"] ?? "",
+		serverUrl: args["server-url"] ?? env["GITHUB_SERVER_URL"] ?? "https://github.com",
+		actor: args.actor ?? env["GITHUB_ACTOR"] ?? "github-actions[bot]",
+		prerelease: args.prerelease ?? false
+	});
+	return buildPayloadFromEnv();
+}
 const webhookSendCommand = defineCommand({
 	meta: {
 		name: "webhook:send",
@@ -8501,14 +8708,8 @@ const webhookSendCommand = defineCommand({
 			return;
 		}
 		const secret = process.env["WEBHOOK_SECRET"];
-		const payload = args.tag || args.repository ? buildSimplePayload({
-			tag: args.tag ?? "",
-			repository: args.repository ?? process.env["GITHUB_REPOSITORY"] ?? "",
-			serverUrl: args["server-url"] ?? process.env["GITHUB_SERVER_URL"] ?? "https://github.com",
-			actor: args.actor ?? process.env["GITHUB_ACTOR"] ?? "github-actions[bot]",
-			prerelease: args.prerelease ?? false
-		}) : buildPayloadFromEnv();
-		await sendWebhookWithLogging(args.url, secret || void 0, payload);
+		const payload = resolveWebhookPayload(args);
+		if (!(await sendWebhookWithLogging(args.url, secret || void 0, payload)).ok) process.exitCode = 1;
 	}
 });
 //#endregion
@@ -8921,7 +9122,7 @@ const out = (msg) => console.log(msg);
 const main = defineCommand({
 	meta: {
 		name: "bst",
-		version: "0.61.0",
+		version: "0.62.0",
 		description: "Bootstrap and maintain standardized TypeScript project tooling"
 	},
 	subCommands: {
@@ -8994,7 +9195,7 @@ const main = defineCommand({
 		})
 	}
 });
-console.log(`@bensandee/tooling v0.61.0`);
+console.log(`@bensandee/tooling v0.62.0`);
 async function run() {
 	await runMain(main);
 	process.exit(process.exitCode ?? 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bensandee/tooling",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
   "license": "MIT",
   "repository": {