Update publishing of new version

Author: iamdevlinph

.agents/skills/codex-kit-release/SKILL.md

@@ -11,4 +11,4 @@ Inspect changes since the latest `v*` release tag together with relevant working
 2. For `major`, `minor`, or `patch`, replace all of `RELEASE_NOTES.md` with concise bullets for only the upcoming release, without a heading or history. For `none`, preserve it unchanged.
 3. Run `node .agents/skills/codex-kit-release/release.mjs bump <classification>` before final validation.
 
-The script uses committed `package.json` as its baseline, is idempotent, and rejects malformed or conflicting versions, missing or empty notes, and bumps without changed notes. It never stages, commits, tags, pushes, publishes, or creates a release. Those actions always require explicit user authorization.
+The script uses committed `package.json` as its baseline, is idempotent, and rejects malformed or conflicting versions, missing or empty notes, and bumps without changed notes. It never stages, commits, tags, pushes, publishes, or creates a release. After an explicitly authorized release commit is pushed to `main`, the validated `publish.yml` workflow creates the immutable tag, publishes npm, and creates the GitHub Release. Agents never perform those actions interactively without explicit user authorization.

.agents/skills/codex-kit-release/release.mjs

@@ -40,6 +40,17 @@ function gitShow(revision, path) {
 	}
 }
 
+function git(...args) {
+	try {
+		return execFileSync("git", args, {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trim();
+	} catch {
+		return undefined;
+	}
+}
+
 function manifest(source, label) {
 	let value;
 	try {
@@ -114,16 +125,57 @@ export function validateTag(tag, previousTag) {
 	return current;
 }
 
+export function releaseState(expectedTag) {
+	const current = manifest(
+		readFileSync("package.json", "utf8"),
+		"package.json",
+	).version;
+	const tag = `v${current}`;
+	if (expectedTag && expectedTag !== tag)
+		fail(`tag ${expectedTag} does not match package.json version ${current}`);
+	const head = git("rev-parse", "HEAD");
+	if (!head) fail("HEAD is required");
+	const taggedCommit = git("rev-parse", `${tag}^{commit}`);
+	if (taggedCommit && taggedCommit !== head) {
+		if (git("merge-base", "--is-ancestor", taggedCommit, head) !== undefined) {
+			const taggedVersion = manifest(
+				gitShow(tag, "package.json"),
+				`${tag}:package.json`,
+			).version;
+			if (taggedVersion !== current)
+				fail(`tag ${tag} contains package.json version ${taggedVersion}`);
+			releaseNotes();
+			return { state: "skip", tag };
+		}
+		fail(`tag ${tag} does not point to HEAD`);
+	}
+	const previousTag = git(
+		"describe",
+		"--tags",
+		"--match",
+		"v*",
+		"--abbrev=0",
+		"HEAD^",
+	);
+	if (!previousTag) fail("a previous v* release tag is required");
+	validateTag(tag, previousTag);
+	return { state: taggedCommit ? "retry" : "new", tag };
+}
+
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	try {
 		const [, , command, first, second] = process.argv;
 		let version;
 		if (command === "bump") version = bump(first);
 		else if (command === "validate-tag" && first && second)
 			version = validateTag(first, second);
-		else
+		else if (command === "release-state") {
+			const release = releaseState(first);
+			console.log(`state=${release.state}`);
+			version = `tag=${release.tag}`;
+		} else
 			fail(
-				"usage: release.mjs bump <kind> | validate-tag <tag> <previous-tag>",
+				"usage: release.mjs bump <kind> | validate-tag <tag> <previous-tag> | release-state",
 			);
 		console.log(version);
 	} catch (error) {

.agents/skills/codex-kit-release/release.node-test.mjs

@@ -33,6 +33,20 @@ function run(root, ...args) {
 	});
 }
 
+function commit(root, message = "release") {
+	execFileSync("git", ["add", "."], { cwd: root });
+	execFileSync("git", ["commit", "-qm", message], { cwd: root });
+}
+
+function prepareRelease(root, version = "1.3.0") {
+	writeFileSync(
+		join(root, "package.json"),
+		`${JSON.stringify({ name: "test", version }, null, "\t")}\n`,
+	);
+	writeFileSync(join(root, "RELEASE_NOTES.md"), "- New release\n");
+	commit(root);
+}
+
 test("bumps each classification and reruns idempotently", () => {
 	for (const [kind, expected] of Object.entries({
 		none: "1.2.3",
@@ -77,3 +91,71 @@ test("validates release tags, one-step versions, and changed notes", () => {
 	assert.equal(run(root, "validate-tag", "v1.3.0", "v1.2.3").status, 0);
 	assert.equal(run(root, "validate-tag", "v1.3.1", "v1.2.3").status, 1);
 });
+
+test("classifies new, retry, already-released, and conflicting tags", () => {
+	const root = repo();
+	prepareRelease(root);
+	assert.match(run(root, "release-state").stdout, /state=new\ntag=v1\.3\.0/);
+	assert.equal(run(root, "release-state", "v1.3.1").status, 1);
+	execFileSync("git", ["tag", "v1.3.0"], { cwd: root });
+	assert.match(run(root, "release-state").stdout, /state=retry/);
+	writeFileSync(join(root, "next.txt"), "next\n");
+	commit(root, "next");
+	assert.match(run(root, "release-state").stdout, /state=skip/);
+
+	const conflict = repo();
+	execFileSync("git", ["tag", "v1.3.0"], { cwd: conflict });
+	prepareRelease(conflict);
+	assert.equal(run(conflict, "release-state").status, 1);
+});
+
+test("release state rejects invalid versions and unchanged, empty, or missing notes", () => {
+	for (const state of ["invalid", "unchanged", "empty", "missing"]) {
+		const root = repo();
+		if (state === "invalid") {
+			writeFileSync(
+				join(root, "package.json"),
+				JSON.stringify({ version: "bad" }),
+			);
+		} else {
+			writeFileSync(
+				join(root, "package.json"),
+				JSON.stringify({ version: "1.3.0" }),
+			);
+			if (state === "empty")
+				writeFileSync(join(root, "RELEASE_NOTES.md"), "\n");
+			if (state === "missing") unlinkSync(join(root, "RELEASE_NOTES.md"));
+		}
+		commit(root);
+		assert.equal(run(root, "release-state").status, 1);
+	}
+});
+
+test("a pushed release tag targets the validated commit and retry never moves it", () => {
+	const root = repo();
+	prepareRelease(root);
+	const remote = mkdtempSync(join(tmpdir(), "codex-kit-release-remote-"));
+	execFileSync("git", ["init", "--bare", "-q", remote]);
+	execFileSync("git", ["remote", "add", "origin", remote], { cwd: root });
+	const tag = run(root, "release-state").stdout.match(/tag=(v\S+)/)?.[1];
+	assert.equal(tag, "v1.3.0");
+	execFileSync("git", ["tag", tag], { cwd: root });
+	execFileSync("git", ["push", "-q", "origin", `refs/tags/${tag}`], {
+		cwd: root,
+	});
+	const releasedCommit = execFileSync("git", ["rev-parse", "HEAD"], {
+		cwd: root,
+		encoding: "utf8",
+	}).trim();
+	assert.equal(run(root, "release-state").stdout.includes("state=retry"), true);
+	assert.equal(
+		execFileSync(
+			"git",
+			[`--git-dir=${remote}`, "rev-parse", `${tag}^{commit}`],
+			{
+				encoding: "utf8",
+			},
+		).trim(),
+		releasedCommit,
+	);
+});

.github/workflows/publish.yml

@@ -2,19 +2,79 @@ name: Publish package
 
 on:
   push:
+    branches:
+      - main
     tags:
       - "v*"
 
+concurrency:
+  group: publish-package
+  cancel-in-progress: false
+
 jobs:
-  publish:
+  prepare:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      id-token: write
+    outputs:
+      state: ${{ steps.release.outputs.state }}
+      tag: ${{ steps.release.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - id: release
+        name: Resolve release state
+        env:
+          PUSHED_TAG: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || '' }}
+        run: node .agents/skills/codex-kit-release/release.mjs release-state "$PUSHED_TAG" >> "$GITHUB_OUTPUT"
+      - uses: pnpm/action-setup@v4
+        if: steps.release.outputs.state != 'skip'
+        with:
+          version: 11.5.2
+      - uses: actions/setup-node@v6
+        if: steps.release.outputs.state != 'skip'
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
+      - if: steps.release.outputs.state != 'skip'
+        run: npm install --global npm@11.5.1
+      - if: steps.release.outputs.state != 'skip'
+        run: pnpm install --frozen-lockfile
+      - if: steps.release.outputs.state != 'skip'
+        run: pnpm run typecheck
+      - if: steps.release.outputs.state != 'skip'
+        run: pnpm test
+      - if: steps.release.outputs.state != 'skip'
+        run: pnpm run pack:check
+
+  tag:
+    needs: prepare
+    if: needs.prepare.outputs.state != 'skip'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
+      - name: Create release tag
+        if: needs.prepare.outputs.state == 'new'
+        env:
+          RELEASE_TAG: ${{ needs.prepare.outputs.tag }}
+        run: |
+          git tag "$RELEASE_TAG" "$GITHUB_SHA"
+          git push origin "refs/tags/$RELEASE_TAG"
+
+  publish:
+    needs: [prepare, tag]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
       - uses: pnpm/action-setup@v4
         with:
           version: 11.5.2
@@ -25,16 +85,13 @@ jobs:
           package-manager-cache: false
       - run: npm install --global npm@11.5.1
       - run: pnpm install --frozen-lockfile
-      - run: pnpm run typecheck
-      - run: pnpm test
-      - name: Validate release version and notes
-        run: |
-          previous_tag=$(git describe --tags --abbrev=0 "$GITHUB_REF_NAME^")
-          node .agents/skills/codex-kit-release/release.mjs validate-tag "$GITHUB_REF_NAME" "$previous_tag"
-      - run: npm publish --access public
+      - name: Publish if absent from npm
+        env:
+          RELEASE_TAG: ${{ needs.prepare.outputs.tag }}
+        run: npm view "@iamdevlinph/codex-kit@${RELEASE_TAG#v}" version >/dev/null 2>&1 || npm publish --access public
 
   release:
-    needs: publish
+    needs: [prepare, publish]
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -43,9 +100,10 @@ jobs:
       - name: Create or update GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ needs.prepare.outputs.tag }}
         run: |
-          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
-            gh release edit "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file RELEASE_NOTES.md
+          if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
+            gh release edit "$RELEASE_TAG" --title "$RELEASE_TAG" --notes-file RELEASE_NOTES.md
           else
-            gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file RELEASE_NOTES.md
+            gh release create "$RELEASE_TAG" --title "$RELEASE_TAG" --notes-file RELEASE_NOTES.md
           fi

AGENTS.md

@@ -95,7 +95,8 @@
   merge into or replace a project's `AGENTS.md`.
 - `project mark-applied` is bookkeeping only; it must not claim to validate the
   semantic merge or modify project instructions.
-- Do not add a `commit-pusher` role or automate Git publishing.
+- Do not add a `commit-pusher` role or automate Git publishing outside the
+  validated `.github/workflows/publish.yml` release flow.
 
 ## Change requirements
 
@@ -142,7 +143,8 @@
 - A template update requires a new package release before downstream
   `project sync` commands can receive it.
 - The release tag must match `package.json` as `v<version>`.
-- Never commit, tag, push, publish, or create a release unless the user explicitly
-  requests that operation in the current task.
+- Never commit, tag, push, publish, or create a release interactively unless the
+  user explicitly requests that operation in the current task. The validated
+  release workflow may perform those actions after an authorized push to `main`.
 - Never store credentials, npm tokens, or personal access tokens in this
   repository.

MAINTAINERS.md

@@ -113,25 +113,26 @@ Inspect the dry-run contents. They should contain only:
 `codex-kit-release` skill, `src/`, tests, lockfiles, generated test output,
 credentials, and local backups must not appear.
 
-After reviewing the prepared version and notes, explicitly authorize and create
-the release commit and matching tag, then push:
+After reviewing the prepared version and notes, explicitly authorize and push
+the release commit to `main`:
 
 ```sh
 git add package.json RELEASE_NOTES.md
 git commit -m "v<version>"
-git tag v<version>
-git push origin main --follow-tags
+git push origin main
 ```
 
-The workflow checks that the tag matches `package.json`, the version is one
-SemVer increment from the previous tag, and latest-only `RELEASE_NOTES.md` is
-non-empty and changed. It publishes npm first, then creates or updates the
-public GitHub Release from the complete notes file.
+The workflow checks that the version is one SemVer increment from the previous
+tag and latest-only `RELEASE_NOTES.md` is non-empty and changed. After all checks
+pass, it creates the immutable matching tag, publishes npm, then creates or
+updates the public GitHub Release from the complete notes file. A push whose
+version tag belongs to an ancestor skips cleanly.
 
 If a workflow fails because of external configuration and no source change is
-needed, rerun the failed job. A rerun uses the original tag and commit. If code
-or workflow changes are required, publish a new version unless the failed tag
-was never released and is intentionally deleted and recreated.
+needed, rerun the failed job. If the tag already targets the tested commit, the
+workflow reuses it; if npm already contains the version, it continues with the
+GitHub Release. A manual push of the matching `v*` tag remains the recovery path.
+The workflow never moves an existing tag.
 
 ## Promote a reusable guideline
 

RELEASE_NOTES.md

@@ -2,3 +2,5 @@
 - Expand reconciliation and initialization audits to classify existing and incoming guidance, preserve local adaptations, and validate narrow workflow routing.
 - Shorten project prompts so the packaged reconciliation skill owns semantic restructuring, with updated upgrade and global-refresh guidance.
 - Add read-only `project audit` prompting and an explicit-only audit skill managed by global install, list, and uninstall.
+- Update Vitest to `4.1.11` to resolve its development-server security advisory.
+- Automatically validate, tag, publish, and create the GitHub Release for release-ready pushes to `main`.

package.json

@@ -46,7 +46,7 @@
 		"husky": "9.1.7",
 		"lint-staged": "17.0.8",
 		"typescript": "7.0.1-rc",
-		"vitest": "4.1.10"
+		"vitest": "4.1.11"
 	},
 	"packageManager": "pnpm@11.5.2",
 	"license": "ISC",