@bensandee/tooling 0.61.0 → 0.62.1

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,21 +844,27 @@ function parseGitUrl(urlStr) {
 	}
 }
 /**
-* Configure the git remote origin to use a Forgejo token for push auth.
+* Build per-invocation git auth for release pushes.
 *
-* 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.
+* Pure: no executor side effects, no `.git/config` mutation. Caller threads
+* `auth.args` + `auth.url` through every `git push` / `git ls-remote` that
+* needs to authenticate as the RELEASE_TOKEN owner.
+*
+* Background: `actions/checkout@v6` mounts its Authorization header through
+* `includeIf.gitdir:<workspace>/.git.path → /tmp/git-credentials-*.config`
+* (the file holds `http.<server>/.extraheader = Authorization: Basic <runner
+* pseudo-user>`). That header overrides URL-embedded auth in the request,
+* which is why pushes from CI authenticated as `uid: -2` and tripped the
+* Forgejo pre-receive hook. Setting `extraheader=` to empty at the
+* command-line layer wins over the include, so the only Authorization git
+* sends is the one from `auth.url`.
 */
-function configureGitAuth(executor, conn, cwd) {
-	const host = conn.serverUrl.replace(/^https?:\/\//, "");
-	const authUrl = `https://x-access-token:${conn.token}@${host}/${conn.repository}`;
-	executor.exec("git", [
-		"remote",
-		"set-url",
-		"origin",
-		authUrl
-	], { cwd });
+function buildGitAuth(coords) {
+	const host = coords.serverUrl.replace(/^https?:\/\//, "");
+	return {
+		args: ["-c", `http.${coords.serverUrl}/.extraheader=`],
+		url: `https://x-access-token:${coords.token}@${host}/${coords.repository}`
+	};
 }
 /** Resolve the CI bot actor name for the given platform. */
 function ciActorName(platform) {
@@ -1580,11 +1586,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 +2222,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.1";
 	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 +3188,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 +3262,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 +3287,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 +3306,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 +3325,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 +3337,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 +3357,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 +3392,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 +3407,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 +3441,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 +3465,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 +3491,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 +3510,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 +3534,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 +3546,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 +3615,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 +3639,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 +3648,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 +3856,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 +3886,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 +3953,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 +3989,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 +4082,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 +4110,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 +4169,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 +4238,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 +4257,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 +4276,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 +4310,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 +5422,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.1 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) => {
@@ -5938,9 +6087,11 @@ async function runVersionMode(executor, config) {
 		};
 	}
 	debug(config, `Force-pushing version commit to ${BRANCH}`);
+	const auth = buildGitAuth(config);
 	const pushResult = executor.exec("git", [
+		...auth.args,
 		"push",
-		"origin",
+		auth.url,
 		`HEAD:refs/heads/${BRANCH}`,
 		"--force"
 	], { cwd: config.cwd });
@@ -6001,10 +6152,12 @@ async function runPublishMode(executor, config) {
 	debug(config, `Tags from publish stdout: ${stdoutTags.length > 0 ? stdoutTags.join(", ") : "(none)"}`);
 	const expectedTags = computeExpectedTags(executor.listWorkspacePackages(config.cwd));
 	debug(config, `Expected tags from workspace packages: ${expectedTags.length > 0 ? expectedTags.join(", ") : "(none)"}`);
+	const auth = buildGitAuth(config);
 	const remoteTags = parseRemoteTags(executor.exec("git", [
+		...auth.args,
 		"ls-remote",
 		"--tags",
-		"origin"
+		auth.url
 	], { cwd: config.cwd }).stdout);
 	debug(config, `Remote tags: ${remoteTags.length > 0 ? remoteTags.join(", ") : "(none)"}`);
 	const remoteSet = new Set(remoteTags);
@@ -6053,8 +6206,9 @@ async function runPublishMode(executor, config) {
 				if (tagResult.exitCode !== 0) throw new FatalError(`Failed to create tag ${tag}: ${tagResult.stderr || tagResult.stdout}`);
 			}
 			const pushTagResult = executor.exec("git", [
+				...auth.args,
 				"push",
-				"origin",
+				auth.url,
 				`refs/tags/${tag}`
 			], { cwd: config.cwd });
 			if (pushTagResult.exitCode !== 0) throw new FatalError(`Failed to push tag ${tag}: ${pushTagResult.stderr || pushTagResult.stdout}`);
@@ -6164,8 +6318,6 @@ async function runRelease(config, executor) {
 	}
 	const identity = await configureGitIdentity(executor, "forgejo", config.cwd, config);
 	log.info(`Git identity: ${identity.name} <${identity.email}>`);
-	configureGitAuth(executor, config, config.cwd);
-	debug(config, `Configured git remote auth for ${config.repository}`);
 	const changesetFiles = executor.listChangesetFiles(config.cwd);
 	debug(config, `Changeset files found: ${changesetFiles.length > 0 ? changesetFiles.join(", ") : "(none)"}`);
 	if (changesetFiles.length > 0) {
@@ -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)}`);
@@ -6528,23 +6716,32 @@ async function runSimpleRelease(executor, config) {
 		};
 	}
 	let pushed = false;
+	const authCoords = resolveAuthCoordinates(executor, config, releaseToken);
+	let auth;
+	if (authCoords) {
+		auth = buildGitAuth(authCoords);
+		debug(config, `Built git auth for ${authCoords.repository}`);
+	} else debug(config, "Skipping git auth: could not resolve server URL / repository");
 	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 branch = executor.exec("git", [
 			"rev-parse",
 			"--abbrev-ref",
 			"HEAD"
 		], { cwd: config.cwd }).stdout.trim() || "main";
 		debug(config, `Pushing ${tag} to origin/${branch} with --follow-tags`);
-		const pushResult = executor.exec("git", [
+		const pushArgs = auth ? [
+			...auth.args,
+			"push",
+			"--follow-tags",
+			auth.url,
+			branch
+		] : [
 			"push",
 			"--follow-tags",
 			"origin",
 			branch
-		], { cwd: config.cwd });
+		];
+		const pushResult = executor.exec("git", pushArgs, { cwd: config.cwd });
 		debugExec(config, "git push", pushResult);
 		if (pushResult.exitCode !== 0) throw new FatalError(`git push failed (exit code ${String(pushResult.exitCode)}):\n${pushResult.stderr || pushResult.stdout}`);
 		pushed = true;
@@ -6562,12 +6759,19 @@ async function runSimpleRelease(executor, config) {
 			], { cwd: config.cwd });
 			if (slidingTagResult.exitCode !== 0) throw new FatalError(`Failed to create sliding tag ${slidingTag}: ${slidingTagResult.stderr || slidingTagResult.stdout}`);
 		}
-		const forcePushResult = executor.exec("git", [
+		const forcePushArgs = auth ? [
+			...auth.args,
+			"push",
+			auth.url,
+			...slidingTags,
+			"--force"
+		] : [
 			"push",
 			"origin",
 			...slidingTags,
 			"--force"
-		], { cwd: config.cwd });
+		];
+		const forcePushResult = executor.exec("git", forcePushArgs, { cwd: config.cwd });
 		debugExec(config, "force-push sliding tags", forcePushResult);
 		if (forcePushResult.exitCode !== 0) log.warn(`Warning: Failed to push sliding tags: ${forcePushResult.stderr || forcePushResult.stdout}`);
 		else log.info(`Created sliding tags: ${slidingTags.join(", ")}`);
@@ -8450,7 +8654,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 +8665,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 +8723,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 +9137,7 @@ const out = (msg) => console.log(msg);
 const main = defineCommand({
 	meta: {
 		name: "bst",
-		version: "0.61.0",
+		version: "0.62.1",
 		description: "Bootstrap and maintain standardized TypeScript project tooling"
 	},
 	subCommands: {
@@ -8994,7 +9210,7 @@ const main = defineCommand({
 		})
 	}
 });
-console.log(`@bensandee/tooling v0.61.0`);
+console.log(`@bensandee/tooling v0.62.1`);
 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.1",
   "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
   "license": "MIT",
   "repository": {
@@ -54,8 +54,8 @@
     "prettier": "3.8.3",
     "release-it": "20.0.1",
     "tsdown": "0.22.0",
-    "@bensandee/claude-hooks": "0.8.1",
-    "@bensandee/config": "0.11.3"
+    "@bensandee/config": "0.11.3",
+    "@bensandee/claude-hooks": "0.8.1"
   },
   "scripts": {
     "build": "tsdown",