@bensandee/tooling 0.64.0 → 0.64.1

package/dist/bin.mjs

@@ -2516,7 +2516,7 @@ function buildManagedDevDeps(ctx) {
 	const devDeps = { ...ROOT_DEV_DEPS };
 	if (!isMonorepo) Object.assign(devDeps, PER_PACKAGE_DEV_DEPS);
 	devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.12.0";
-	if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.64.0";
+	if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.64.1";
 	if (ctx.config.useEslintPlugin) devDeps["@bensandee/eslint-plugin"] = isWorkspacePackage(ctx, "@bensandee/eslint-plugin") ? "workspace:*" : "0.13.1";
 	if (ctx.config.formatter === "oxfmt") devDeps["oxfmt"] = {
 		"@changesets/cli": "2.31.0",
@@ -3482,8 +3482,12 @@ async function generateTsdown(ctx) {
 }
 //#endregion
 //#region src/release/forgejo.ts
-const RETRY_ATTEMPTS = 3;
-const RETRY_BASE_DELAY_MS = 1e3;
+/** Patient-repair attempts (delete frozen release, wait, retry) before escalating. */
+const SETTLE_ATTEMPTS = 4;
+/** Base backoff between patient-repair attempts; doubles each attempt. */
+const SETTLE_BASE_DELAY_MS = 2e3;
+/** Cap on a single patient-repair backoff. */
+const SETTLE_MAX_DELAY_MS = 16e3;
 /** Safely read response body text for inclusion in error messages. */
 async function responseBodyText(res) {
 	try {
@@ -3691,20 +3695,29 @@ async function getReleaseByTag(executor, conn, tag) {
 	if (!parsed.success) throw new UnexpectedError(`Unexpected release response: ${parsed.error.message}`);
 	return parsed.data;
 }
-/** Create a Forgejo release for a given tag. */
-async function createRelease(executor, conn, tag) {
+/**
+* Create a Forgejo release for a given tag.
+*
+* When `options.target` (a commit SHA or branch) is provided and the tag does
+* not yet exist, Forgejo **creates the tag itself** from that commitish and
+* stamps `created_unix = now` synchronously — sidestepping the buggy async
+* stamping of a pushed tag. The created tag is lightweight.
+*/
+async function createRelease(executor, conn, tag, options = {}) {
 	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/releases`;
+	const payload = {
+		tag_name: tag,
+		name: tag,
+		body: `Published ${tag}`
+	};
+	if (options.target) payload["target_commitish"] = options.target;
 	const res = await executor.fetch(url, {
 		method: "POST",
 		headers: {
 			Authorization: `token ${conn.token}`,
 			"Content-Type": "application/json"
 		},
-		body: JSON.stringify({
-			tag_name: tag,
-			name: tag,
-			body: `Published ${tag}`
-		})
+		body: JSON.stringify(payload)
 	});
 	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
 		verb: "create release",
@@ -3712,6 +3725,26 @@ async function createRelease(executor, conn, tag) {
 	}));
 }
 /**
+* Delete a git tag from the repository (`DELETE /repos/{repo}/tags/{tag}`).
+*
+* Used by {@link ensureRelease} to take tag ownership away from the buggy
+* push-ingestion path: once the tag is gone, recreating the release with a
+* `target_commitish` makes Forgejo create the tag fresh with a real date. A 404
+* (already gone) is treated as success.
+*/
+async function deleteTag(executor, conn, tag) {
+	const encodedTag = encodeURIComponent(tag);
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/tags/${encodedTag}`;
+	const res = await executor.fetch(url, {
+		method: "DELETE",
+		headers: { Authorization: `token ${conn.token}` }
+	});
+	if (!res.ok && res.status !== 404) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "delete tag",
+		resource: tag
+	}));
+}
+/**
 * Delete a Forgejo release by id. Does **not** delete the underlying git tag
 * (no `delete_tag` query param) — the tag is the source of truth, and a
 * subsequent `POST /releases` relies on it still existing to insert a fresh
@@ -3731,62 +3764,83 @@ async function deleteRelease(executor, conn, releaseId) {
 /**
 * Ensure a Forgejo release exists for a tag **with a real created date**.
 *
-* The tag is pushed before this runs, so Forgejo may have already auto-created
-* a tag-placeholder release. A naive create can leave the release stuck at the
-* Unix epoch (see {@link isEpochReleaseDate}) — a published-but-invisible
-* release, because `/releases/latest` sorts by date. This function guarantees a
-* real date or throws:
+* Forgejo stamps a pushed annotated tag's date *asynchronously*; a release
+* creation that races that stamp freezes the row at the Unix epoch (see
+* {@link isEpochReleaseDate}) — a published-but-invisible release, because
+* `/releases/latest` sorts by date. The failure is intermittent. The repair:
 *
-* 1. A real-dated release already exists → return `"exists"`.
-* 2. An epoch-dated release/placeholder exists → delete it first.
-* 3. Create the release, then **read it back**. Forgejo returns 2xx even when it
-*    promotes a placeholder in place (keeping `created_unix = 0`), so a 2xx does
-*    not prove a real date. If the read-back is epoch-dated, delete and retry.
-* 4. The date stays epoch after all retries → throw (fail the job loudly rather
-*    than silently ship an invisible release).
+* 1. A real-dated release already exists → `"exists"`.
+* 2. Otherwise create the release and read it back. On epoch, delete the frozen
+*    release and wait (increasing backoff) for Forgejo to settle the tag's date,
+*    then retry — **preserving the pushed (annotated) tag**. The frozen release
+*    is never deleted-and-left-empty.
+* 3. If the date still never settles and a `target` commit is known, delete the
+*    tag and recreate the release with `target_commitish` so **Forgejo creates
+*    the tag itself**, stamped `now`. The tag becomes lightweight. → `"repaired"`.
+* 4. If nothing yields a real date, leave a visible release row (rather than only
+*    an invisible tag) and throw loudly.
 *
-* Retries on transient errors with exponential backoff. Returns
-* `"created" | "exists" | "race" | "repaired"`.
+* Returns `"created" | "exists" | "race" | "repaired"`.
 */
-async function ensureRelease(executor, conn, tag) {
+async function ensureRelease(executor, conn, tag, options = {}) {
+	const attempts = options.attempts ?? SETTLE_ATTEMPTS;
+	const baseDelayMs = options.baseDelayMs ?? SETTLE_BASE_DELAY_MS;
 	const existing = await getReleaseByTag(executor, conn, tag);
 	if (existing && !isEpochReleaseDate(existing.created_at)) return "exists";
+	let current = existing;
 	let repairing = false;
-	if (existing) {
-		log.warn(`Release for ${tag} has an epoch (1969/1970) date — deleting and recreating to fix the timestamp`);
-		await deleteRelease(executor, conn, existing.id);
-		repairing = true;
-	}
-	for (let attempt = 1; attempt <= RETRY_ATTEMPTS; attempt++) {
+	for (let attempt = 1; attempt <= attempts; attempt++) {
+		if (current && isEpochReleaseDate(current.created_at)) {
+			await deleteRelease(executor, conn, current.id);
+			current = null;
+			repairing = true;
+			await settleBackoff(attempt, baseDelayMs);
+		}
 		try {
 			await createRelease(executor, conn, tag);
 		} catch (error) {
 			const raced = await getReleaseByTag(executor, conn, tag);
 			if (raced && !isEpochReleaseDate(raced.created_at)) return "race";
-			if (raced) {
-				await deleteRelease(executor, conn, raced.id);
-				repairing = true;
-			}
-			if (attempt >= RETRY_ATTEMPTS) throw error;
-			log.warn(`Release creation attempt ${String(attempt)}/${String(RETRY_ATTEMPTS)} failed: ${error instanceof Error ? error.message : String(error)}`);
-			await backoff(attempt);
+			current = raced;
+			if (attempt >= attempts) break;
+			log.warn(`Release creation attempt ${String(attempt)}/${String(attempts)} failed: ${error instanceof Error ? error.message : String(error)}`);
+			await settleBackoff(attempt, baseDelayMs);
 			continue;
 		}
-		const created = await getReleaseByTag(executor, conn, tag);
-		if (created && !isEpochReleaseDate(created.created_at)) return repairing ? "repaired" : "created";
-		if (created) {
-			await deleteRelease(executor, conn, created.id);
-			repairing = true;
+		current = await getReleaseByTag(executor, conn, tag);
+		if (current && !isEpochReleaseDate(current.created_at)) return repairing ? "repaired" : "created";
+		if (attempt < attempts) log.warn(`Release for ${tag} came back epoch-dated (attempt ${String(attempt)}/${String(attempts)}) — waiting for Forgejo to settle the tag's date before retrying`);
+	}
+	if (options.target && await recreateTagViaApi(executor, conn, tag, {
+		target: options.target,
+		current,
+		attempts,
+		baseDelayMs
+	})) return "repaired";
+	throw new TransientError(`Release for ${tag} never got a real (non-epoch) created date after ${String(attempts)} attempts. This is an intermittent Forgejo bug: a pushed tag's date settles asynchronously and a racing release creation freezes it at the Unix epoch (1969/1970). ` + (options.target ? `Recreating the tag via the API did not help — investigate the server or upgrade Forgejo.` : `Pass the release tag's target commit so the tag can be recreated, or retry the release.`));
+}
+async function recreateTagViaApi(executor, conn, tag, opts) {
+	const { target, current, attempts, baseDelayMs } = opts;
+	log.warn(`Release for ${tag} stayed epoch-dated — recreating the tag via the API so Forgejo stamps a real date (the tag becomes lightweight)`);
+	if (current) await deleteRelease(executor, conn, current.id);
+	await deleteTag(executor, conn, tag);
+	for (let attempt = 1; attempt <= attempts; attempt++) {
+		try {
+			await createRelease(executor, conn, tag, { target });
+		} catch (error) {
+			if (attempt >= attempts) throw new TransientError(`Release for ${tag} was deleted to repair its epoch date, but recreating it from ${target} failed: ${error instanceof Error ? error.message : String(error)}. The tag no longer exists on the server — re-push it (or re-run the release) to restore it.`);
+			await settleBackoff(attempt, baseDelayMs);
+			continue;
 		}
-		if (attempt >= RETRY_ATTEMPTS) throw new TransientError(`Release for ${tag} still has an epoch (1969/1970) created date after ${String(RETRY_ATTEMPTS)} attempts — Forgejo keeps promoting a tag placeholder. The git tag exists but the release row cannot get a real timestamp; investigate the server.`);
-		log.warn(`Release for ${tag} came back epoch-dated (attempt ${String(attempt)}/${String(RETRY_ATTEMPTS)}) — deleting and recreating`);
-		await backoff(attempt);
+		const recreated = await getReleaseByTag(executor, conn, tag);
+		return Boolean(recreated && !isEpochReleaseDate(recreated.created_at));
 	}
-	throw new TransientError(`Failed to create release for ${tag} after ${String(RETRY_ATTEMPTS)} attempts`);
+	return false;
 }
-/** Exponential backoff between release-creation attempts. */
-async function backoff(attempt) {
-	const delay = RETRY_BASE_DELAY_MS * 2 ** (attempt - 1);
+/** Exponential backoff (capped) between patient-repair attempts; a non-positive base is a no-op. */
+async function settleBackoff(attempt, baseDelayMs) {
+	if (baseDelayMs <= 0) return;
+	const delay = Math.min(baseDelayMs * 2 ** (attempt - 1), SETTLE_MAX_DELAY_MS);
 	await new Promise((resolve) => setTimeout(resolve, delay));
 }
 /** Upload an asset file to a Forgejo release. */
@@ -5916,7 +5970,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.64.0 repo:sync\` on ${timestamp}_\n`);
+	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.64.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) => {
@@ -6396,6 +6450,17 @@ function computeSlidingTags(version) {
 		"latest"
 	];
 }
+/**
+* Resolve the commit SHA a tag points at (`git rev-parse <tag>^{commit}`), or
+* `undefined` if it can't be resolved. Used to pass a `target` to
+* {@link ensureRelease} so it can recreate a tag through Forgejo's API when the
+* pushed tag's release date never settles.
+*/
+function resolveTagCommit(executor, cwd, tag) {
+	const result = executor.exec("git", ["rev-parse", `${tag}^{commit}`], { cwd });
+	const sha = result.stdout.trim();
+	return result.exitCode === 0 && sha ? sha : void 0;
+}
 /** Parse "New tag:" lines from changeset publish output. */
 function parseNewTags(output) {
 	const tags = [];
@@ -6714,7 +6779,7 @@ async function runPublishMode(executor, config) {
 	for (const tag of allTags) try {
 		pushTagToRemote(executor, config, auth, tag, remoteSet);
 		debug(config, `Ensuring Forgejo release for ${tag}`);
-		if (await ensureRelease(executor, conn, tag) === "exists") log.warn(`Release for ${tag} already exists — skipping`);
+		if (await ensureRelease(executor, conn, tag, { target: resolveTagCommit(executor, config.cwd, tag) }) === "exists") log.warn(`Release for ${tag} already exists — skipping`);
 		else log.info(`Created release for ${tag}`);
 	} catch (error) {
 		errors.push({
@@ -7051,7 +7116,8 @@ const createForgejoReleaseCommand = defineCommand({
 		if (resolved.type !== "forgejo") throw new FatalError("forgejo:create-release requires a Forgejo repository");
 		const executor = createRealExecutor();
 		const conn = resolved.conn;
-		if (await ensureRelease(executor, conn, args.tag) === "exists") log.info(`Release for ${args.tag} already exists — skipping`);
+		const target = resolveTagCommit(executor, process.cwd(), args.tag);
+		if (await ensureRelease(executor, conn, args.tag, { target }) === "exists") log.info(`Release for ${args.tag} already exists — skipping`);
 		else log.info(`Created Forgejo release for ${args.tag}`);
 	}
 });
@@ -7330,7 +7396,8 @@ async function runSimpleRelease(executor, config) {
 async function createPlatformRelease(executor, config, tag) {
 	if (!config.platform) return false;
 	if (config.platform.type === "forgejo") {
-		if (await ensureRelease(executor, config.platform.conn, tag) === "exists") {
+		const target = resolveTagCommit(executor, config.cwd, tag);
+		if (await ensureRelease(executor, config.platform.conn, tag, { target }) === "exists") {
 			debug(config, `Release for ${tag} already exists, skipping`);
 			return false;
 		}
@@ -10396,7 +10463,7 @@ const out = (msg) => console.log(msg);
 const main = defineCommand({
 	meta: {
 		name: "bst",
-		version: "0.64.0",
+		version: "0.64.1",
 		description: "Bootstrap and maintain standardized TypeScript project tooling"
 	},
 	subCommands: {
@@ -10468,7 +10535,7 @@ const main = defineCommand({
 		})
 	}
 });
-console.log(`@bensandee/tooling v0.64.0`);
+console.log(`@bensandee/tooling v0.64.1`);
 async function run() {
 	await runMain(main);
 	process.exit(process.exitCode ?? 0);

package/package.json

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