pi-release 1.0.0

package/extensions/index.ts

@@ -0,0 +1,955 @@
+/**
+ * pi-release — Release Automation Extension
+ *
+ * Automates the full release flow: bump version → changelog → commit →
+ * tag → GitHub release → npm publish.
+ *
+ * Tools:
+ *   1. bump_version          — Bump package.json version, create git tag
+ *   2. create_github_release — Create GitHub release from tag
+ *   3. publish_npm           — Publish package to npm registry
+ *
+ * Commands:
+ *   /release — Full orchestrated release flow
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+// ── Types ───────────────────────────────────────────────────────────
+
+type BumpType = "major" | "minor" | "patch";
+
+interface ReleaseConfig {
+	/** npm registry URL (default: https://registry.npmjs.org/) */
+	registry: string;
+	/** GitHub owner/repo (auto-detected from git remote) */
+	githubRepo: string | null;
+	/** Default bump type (default: patch) */
+	defaultBump: BumpType;
+	/** Pre-release tag (e.g. "beta", "alpha") — empty string for stable */
+	preReleaseTag: string;
+	/** Whether to generate changelog before release */
+	generateChangelog: boolean;
+	/** Whether to create git commit for version bump */
+	commitBump: boolean;
+	/** Custom commit message template — {version} is replaced */
+	commitMessage: string;
+	/** Whether to create git tag */
+	createTag: boolean;
+	/** Custom tag prefix (default: "v") */
+	tagPrefix: string;
+	/** Whether to create GitHub release */
+	createGithubRelease: boolean;
+	/** Whether to publish to npm */
+	publishToNpm: boolean;
+}
+
+interface BumpResult {
+	previousVersion: string;
+	newVersion: string;
+	tag: string;
+	commitHash: string | null;
+	dryRun: boolean;
+}
+
+interface GithubReleaseResult {
+	tag: string;
+	url: string;
+	dryRun: boolean;
+}
+
+interface PublishResult {
+	package: string;
+	version: string;
+	registry: string;
+	dryRun: boolean;
+}
+
+// ── Default Config ──────────────────────────────────────────────────
+
+const DEFAULT_CONFIG: ReleaseConfig = {
+	registry: "https://registry.npmjs.org/",
+	githubRepo: null,
+	defaultBump: "patch",
+	preReleaseTag: "",
+	generateChangelog: true,
+	commitBump: true,
+	commitMessage: "chore(release): {version}",
+	createTag: true,
+	tagPrefix: "v",
+	createGithubRelease: true,
+	publishToNpm: true,
+};
+
+// ── Config Loading ──────────────────────────────────────────────────
+
+function loadConfig(cwd?: string): ReleaseConfig {
+	const base = cwd || process.cwd();
+	const configPaths = ["pi-release.json", ".pi-release.json"];
+
+	for (const configPath of configPaths) {
+		const fullPath = join(base, configPath);
+		if (existsSync(fullPath)) {
+			try {
+				const raw = readFileSync(fullPath, "utf-8");
+				const parsed = JSON.parse(raw) as Partial<ReleaseConfig>;
+				return { ...DEFAULT_CONFIG, ...parsed };
+			} catch {
+				// Fall back to defaults if config is malformed
+			}
+		}
+	}
+
+	return { ...DEFAULT_CONFIG };
+}
+
+// ── Shell Helpers ───────────────────────────────────────────────────
+
+function exec(cmd: string, cwd?: string): string {
+	try {
+		return execSync(cmd, {
+			cwd: cwd || process.cwd(),
+			encoding: "utf-8",
+			timeout: 60_000,
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+	} catch (err: unknown) {
+		const e = err as { stdout?: string; stderr?: string; message?: string };
+		if (e.stderr) throw new Error(e.stderr);
+		throw new Error(e.message || "Command failed");
+	}
+}
+
+// ── Package.json Helpers ────────────────────────────────────────────
+
+function readPackageJson(cwd?: string): { name: string; version: string } {
+	const base = cwd || process.cwd();
+	const pkgPath = join(base, "package.json");
+	if (!existsSync(pkgPath)) {
+		throw new Error("No package.json found in current directory");
+	}
+	const raw = readFileSync(pkgPath, "utf-8");
+	const pkg = JSON.parse(raw) as { name?: string; version?: string };
+	if (!pkg.name) throw new Error("package.json missing 'name' field");
+	if (!pkg.version) throw new Error("package.json missing 'version' field");
+	return { name: pkg.name, version: pkg.version };
+}
+
+function writePackageVersion(version: string, cwd?: string): void {
+	const base = cwd || process.cwd();
+	const pkgPath = join(base, "package.json");
+	const raw = readFileSync(pkgPath, "utf-8");
+	const pkg = JSON.parse(raw) as Record<string, unknown>;
+	pkg.version = version;
+	writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf-8");
+}
+
+// ── Version Bumping ─────────────────────────────────────────────────
+
+export function bumpSemver(version: string, type: BumpType): string {
+	const parts = version.split(".").map(Number);
+	if (parts.length !== 3 || parts.some((p) => Number.isNaN(p))) {
+		throw new Error(`Invalid semver version: ${version}`);
+	}
+	const [major = 0, minor = 0, patch = 0] = parts;
+
+	switch (type) {
+		case "major":
+			return `${major + 1}.0.0`;
+		case "minor":
+			return `${major}.${minor + 1}.0`;
+		case "patch":
+			return `${major}.${minor}.${patch + 1}`;
+	}
+}
+
+// ── Git Helpers ─────────────────────────────────────────────────────
+
+function getGitRemote(cwd?: string): string | null {
+	try {
+		return exec("git remote get-url origin", cwd);
+	} catch {
+		return null;
+	}
+}
+
+export function parseGithubRepo(remoteUrl: string): string | null {
+	// SSH: git@github.com:owner/repo.git
+	const sshMatch = /^git@github\.com:(.+?)\.git$/.exec(remoteUrl);
+	if (sshMatch) return sshMatch[1];
+
+	// HTTPS: https://github.com/owner/repo.git
+	const httpsMatch = /^https:\/\/github\.com\/(.+?)\.git$/.exec(remoteUrl);
+	if (httpsMatch) return httpsMatch[1];
+
+	// HTTPS without .git
+	const httpsNoGit = /^https:\/\/github\.com\/(.+?)$/.exec(remoteUrl);
+	if (httpsNoGit) return httpsNoGit[1];
+
+	return null;
+}
+
+function isGitClean(cwd?: string): boolean {
+	try {
+		const status = exec("git status --porcelain", cwd);
+		return status.length === 0;
+	} catch {
+		return false;
+	}
+}
+
+function getLatestTag(cwd?: string): string | null {
+	try {
+		return exec("git describe --tags --abbrev=0", cwd);
+	} catch {
+		return null;
+	}
+}
+
+function tagExists(tag: string, cwd?: string): boolean {
+	try {
+		exec(`git rev-parse ${tag}`, cwd);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+// ── Changelog Generation ────────────────────────────────────────────
+
+const CONVENTIONAL_PATTERN = /^(\w+)(?:\(([^)]*)\))?(!)?:\s+(.+)$/;
+const TYPE_LABELS: Record<string, string> = {
+	feat: "Features",
+	fix: "Bug Fixes",
+	docs: "Documentation",
+	style: "Styles",
+	refactor: "Code Refactoring",
+	perf: "Performance Improvements",
+	test: "Tests",
+	ci: "CI/CD",
+	build: "Build System",
+	chore: "Miscellaneous",
+	revert: "Reverts",
+};
+const TYPE_ORDER = [
+	"feat",
+	"fix",
+	"perf",
+	"refactor",
+	"docs",
+	"style",
+	"test",
+	"ci",
+	"build",
+	"chore",
+	"revert",
+];
+
+interface SimpleCommit {
+	hash: string;
+	type: string;
+	scope: string | null;
+	subject: string;
+	breaking: boolean;
+}
+
+function parseSimpleCommit(line: string): SimpleCommit | null {
+	const parts = line.split("|");
+	if (parts.length < 2) return null;
+
+	const hash = parts[0]?.trim() || "";
+	const subject = parts.slice(1).join("|").trim();
+
+	const match = CONVENTIONAL_PATTERN.exec(subject);
+	if (!match) {
+		return { hash, type: "other", scope: null, subject, breaking: false };
+	}
+
+	const [, type, scope, bang, desc] = match;
+	return {
+		hash,
+		type: (type || "other").toLowerCase(),
+		scope: scope || null,
+		subject: desc?.trim() || subject,
+		breaking: bang === "!",
+	};
+}
+
+export function generateBasicChangelog(version: string, cwd?: string): string {
+	const base = cwd || process.cwd();
+	const latestTag = getLatestTag(base);
+	const range = latestTag ? `${latestTag}..HEAD` : "";
+	const cmd = `git log ${range} --format="%H|%s" --date=short`;
+
+	let logOutput: string;
+	try {
+		logOutput = exec(cmd, base);
+	} catch {
+		return `# Changelog\n\n## [${version}]\n\nNo commits found.\n`;
+	}
+
+	if (!logOutput) {
+		return `# Changelog\n\n## [${version}]\n\nNo commits found.\n`;
+	}
+
+	const lines = logOutput.split("\n");
+	const commits: SimpleCommit[] = [];
+	for (const line of lines) {
+		const commit = parseSimpleCommit(line);
+		if (commit) commits.push(commit);
+	}
+
+	// Group by type
+	const grouped = new Map<string, SimpleCommit[]>();
+	for (const commit of commits) {
+		const existing = grouped.get(commit.type) || [];
+		existing.push(commit);
+		grouped.set(commit.type, existing);
+	}
+
+	const date = new Date().toISOString().split("T")[0];
+	const mdLines: string[] = [
+		"# Changelog",
+		"",
+		`## [${version}] - ${date}`,
+		"",
+	];
+
+	// Breaking changes first
+	const breaking = commits.filter((c) => c.breaking);
+	if (breaking.length > 0) {
+		mdLines.push("### ⚠ BREAKING CHANGES", "");
+		for (const c of breaking) {
+			const scope = c.scope ? `**${c.scope}:** ` : "";
+			mdLines.push(`- ${scope}${c.subject} (${c.hash.slice(0, 7)})`);
+		}
+		mdLines.push("");
+	}
+
+	// Grouped entries
+	for (const type of TYPE_ORDER) {
+		const typeCommits = grouped.get(type);
+		if (typeCommits && typeCommits.length > 0) {
+			mdLines.push(`### ${TYPE_LABELS[type] || type}`, "");
+			for (const c of typeCommits) {
+				const scope = c.scope ? `**${c.scope}:** ` : "";
+				mdLines.push(`- ${scope}${c.subject} (${c.hash.slice(0, 7)})`);
+			}
+			mdLines.push("");
+		}
+	}
+
+	// Other types not in TYPE_ORDER
+	for (const [type, typeCommits] of grouped) {
+		if (!TYPE_ORDER.includes(type) && typeCommits.length > 0) {
+			mdLines.push(`### ${TYPE_LABELS[type] || type}`, "");
+			for (const c of typeCommits) {
+				mdLines.push(`- ${c.subject} (${c.hash.slice(0, 7)})`);
+			}
+			mdLines.push("");
+		}
+	}
+
+	return mdLines.join("\n");
+}
+
+// ── Tool Implementations ────────────────────────────────────────────
+
+export function bumpVersionImpl(
+	bumpType: BumpType,
+	options: {
+		cwd?: string;
+		dryRun?: boolean;
+		preReleaseTag?: string;
+		commitMessage?: string;
+		tagPrefix?: string;
+	} = {},
+): BumpResult {
+	const cwd = options.cwd;
+	const config = loadConfig(cwd);
+	const dryRun = options.dryRun ?? false;
+	const tagPrefix = options.tagPrefix ?? config.tagPrefix;
+	const preRelease = options.preReleaseTag ?? config.preReleaseTag;
+
+	const pkg = readPackageJson(cwd);
+	const previousVersion = pkg.version;
+	let newVersion = bumpSemver(previousVersion, bumpType);
+
+	if (preRelease) {
+		newVersion = `${newVersion}-${preRelease}`;
+	}
+
+	const tag = `${tagPrefix}${newVersion}`;
+	const commitMsg = (options.commitMessage || config.commitMessage).replace(
+		"{version}",
+		newVersion,
+	);
+
+	if (dryRun) {
+		return {
+			previousVersion,
+			newVersion,
+			tag,
+			commitHash: null,
+			dryRun: true,
+		};
+	}
+
+	// Check git state
+	if (!isGitClean(cwd)) {
+		throw new Error(
+			"Working directory has uncommitted changes. Commit or stash them first.",
+		);
+	}
+
+	if (tagExists(tag, cwd)) {
+		throw new Error(`Tag ${tag} already exists`);
+	}
+
+	// Write new version to package.json
+	writePackageVersion(newVersion, cwd);
+
+	// Commit the version bump
+	let commitHash: string | null = null;
+	if (config.commitBump) {
+		exec("git add package.json", cwd);
+		exec(`git commit -m "${commitMsg}"`, cwd);
+		commitHash = exec("git rev-parse HEAD", cwd);
+	}
+
+	// Create tag
+	if (config.createTag) {
+		exec(`git tag ${tag}`, cwd);
+	}
+
+	return {
+		previousVersion,
+		newVersion,
+		tag,
+		commitHash,
+		dryRun: false,
+	};
+}
+
+export function createGithubReleaseImpl(
+	tag: string,
+	options: {
+		cwd?: string;
+		dryRun?: boolean;
+		title?: string;
+		notes?: string;
+		prerelease?: boolean;
+	} = {},
+): GithubReleaseResult {
+	const cwd = options.cwd;
+	const config = loadConfig(cwd);
+	const dryRun = options.dryRun ?? false;
+
+	// Detect GitHub repo
+	const remote = getGitRemote(cwd);
+	const repo = remote ? parseGithubRepo(remote) : config.githubRepo;
+	if (!repo) {
+		throw new Error(
+			"Cannot determine GitHub repo. Set githubRepo in pi-release.json or ensure git remote 'origin' points to GitHub.",
+		);
+	}
+
+	const title = options.title || `Release ${tag}`;
+	const url = `https://github.com/${repo}/releases/tag/${tag}`;
+
+	if (dryRun) {
+		return { tag, url, dryRun: true };
+	}
+
+	// Check gh CLI is available
+	try {
+		exec("gh --version", cwd);
+	} catch {
+		throw new Error(
+			"GitHub CLI (gh) is not installed. Install it from https://cli.github.com/",
+		);
+	}
+
+	// Check tag exists
+	if (!tagExists(tag, cwd)) {
+		throw new Error(`Tag ${tag} does not exist. Run bump_version first.`);
+	}
+
+	// Build gh release create command
+	const args = ["gh release create", tag];
+	args.push("--repo", repo);
+	args.push("--title", `"${title}"`);
+
+	if (options.notes) {
+		args.push("--notes", `"${options.notes}"`);
+	} else {
+		args.push("--generate-notes");
+	}
+
+	if (options.prerelease) {
+		args.push("--prerelease");
+	}
+
+	exec(args.join(" "), cwd);
+
+	return { tag, url, dryRun: false };
+}
+
+export function publishNpmImpl(
+	options: {
+		cwd?: string;
+		dryRun?: boolean;
+		otp?: string;
+		registry?: string;
+		tag?: string;
+	} = {},
+): PublishResult {
+	const cwd = options.cwd;
+	const config = loadConfig(cwd);
+	const dryRun = options.dryRun ?? false;
+	const registry = options.registry || config.registry;
+
+	const pkg = readPackageJson(cwd);
+
+	if (dryRun) {
+		return {
+			package: pkg.name,
+			version: pkg.version,
+			registry,
+			dryRun: true,
+		};
+	}
+
+	// Build npm publish command
+	const args = ["npm publish"];
+	if (registry !== "https://registry.npmjs.org/") {
+		args.push("--registry", registry);
+	}
+	if (options.otp) {
+		args.push("--otp", options.otp);
+	}
+	if (options.tag) {
+		args.push("--tag", options.tag);
+	}
+
+	exec(args.join(" "), cwd);
+
+	return {
+		package: pkg.name,
+		version: pkg.version,
+		registry,
+		dryRun: false,
+	};
+}
+
+// ── Formatting ──────────────────────────────────────────────────────
+
+function formatBumpResult(result: BumpResult): string {
+	const lines: string[] = [];
+	const prefix = result.dryRun ? "[DRY RUN] " : "";
+
+	lines.push(`${prefix}📦 Version Bump`);
+	lines.push(`   ${result.previousVersion} → ${result.newVersion}`);
+	lines.push(`   Tag: ${result.tag}`);
+	if (result.commitHash) {
+		lines.push(`   Commit: ${result.commitHash.slice(0, 8)}`);
+	}
+	if (result.dryRun) {
+		lines.push("   ⚠️  No changes made (dry run)");
+	}
+
+	return lines.join("\n");
+}
+
+function formatGithubReleaseResult(result: GithubReleaseResult): string {
+	const lines: string[] = [];
+	const prefix = result.dryRun ? "[DRY RUN] " : "";
+
+	lines.push(`${prefix}🚀 GitHub Release`);
+	lines.push(`   Tag: ${result.tag}`);
+	lines.push(`   URL: ${result.url}`);
+	if (result.dryRun) {
+		lines.push("   ⚠️  No release created (dry run)");
+	}
+
+	return lines.join("\n");
+}
+
+function formatPublishResult(result: PublishResult): string {
+	const lines: string[] = [];
+	const prefix = result.dryRun ? "[DRY RUN] " : "";
+
+	lines.push(`${prefix}📤 npm Publish`);
+	lines.push(`   Package: ${result.package}@${result.version}`);
+	lines.push(`   Registry: ${result.registry}`);
+	if (result.dryRun) {
+		lines.push("   ⚠️  Not published (dry run)");
+	}
+
+	return lines.join("\n");
+}
+
+function formatReleaseReport(
+	bump: BumpResult,
+	changelog: string,
+	ghRelease: GithubReleaseResult | null,
+	publish: PublishResult | null,
+): string {
+	const bar = "═".repeat(60);
+	const lines: string[] = [];
+
+	lines.push(`╔${bar}╗`);
+	lines.push("║  🎉 RELEASE REPORT");
+	lines.push(`║  ${bump.newVersion}`);
+	if (bump.dryRun) lines.push("║  [DRY RUN — no changes made]");
+	lines.push(`╚${bar}╝`);
+	lines.push("");
+	lines.push(formatBumpResult(bump));
+	lines.push("");
+
+	if (changelog) {
+		lines.push("📝 Changelog:");
+		lines.push(changelog);
+		lines.push("");
+	}
+
+	if (ghRelease) {
+		lines.push(formatGithubReleaseResult(ghRelease));
+		lines.push("");
+	}
+
+	if (publish) {
+		lines.push(formatPublishResult(publish));
+		lines.push("");
+	}
+
+	if (bump.dryRun) {
+		lines.push("─".repeat(40));
+		lines.push("This was a dry run. Run without --dry-run to execute.");
+	} else {
+		lines.push("─".repeat(40));
+		lines.push("✅ Release complete!");
+	}
+
+	return lines.join("\n");
+}
+
+// ── Extension Registration ──────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+	// ── Tool: bump_version ──────────────────────────────────────────
+	pi.registerTool({
+		name: "bump_version",
+		label: "Bump Version",
+		description:
+			"Bump the version in package.json (major/minor/patch), create a git commit and tag. Supports pre-release tags (beta, alpha, rc) and dry-run mode. Requires a clean git working directory.",
+		parameters: Type.Object({
+			bump: Type.Optional(
+				Type.Union(
+					[Type.Literal("major"), Type.Literal("minor"), Type.Literal("patch")],
+					{
+						description:
+							"Version bump type: major (1.0.0→2.0.0), minor (1.0.0→1.1.0), patch (1.0.0→1.0.1). Default: patch.",
+						default: "patch",
+					},
+				),
+			),
+			pre_release: Type.Optional(
+				Type.String({
+					description:
+						"Pre-release tag to append (e.g. 'beta', 'alpha', 'rc'). Result: 1.0.0-beta.",
+				}),
+			),
+			dry_run: Type.Optional(
+				Type.Boolean({
+					description:
+						"Preview the version bump without making changes. Default: false.",
+					default: false,
+				}),
+			),
+			message: Type.Optional(
+				Type.String({
+					description:
+						"Custom commit message. Use {version} as placeholder. Default: 'chore(release): {version}'.",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			try {
+				const bumpType = (params.bump || "patch") as BumpType;
+				const result = bumpVersionImpl(bumpType, {
+					cwd: ctx.cwd,
+					dryRun: params.dry_run,
+					preReleaseTag: params.pre_release,
+					commitMessage: params.message,
+				});
+
+				return {
+					content: [{ type: "text", text: formatBumpResult(result) }],
+					details: result,
+				};
+			} catch (err: unknown) {
+				const msg = err instanceof Error ? err.message : "Unknown error";
+				return {
+					content: [{ type: "text", text: `❌ Version bump failed: ${msg}` }],
+					details: { error: msg },
+				};
+			}
+		},
+	});
+
+	// ── Tool: create_github_release ─────────────────────────────────
+	pi.registerTool({
+		name: "create_github_release",
+		label: "Create GitHub Release",
+		description:
+			"Create a GitHub release from a git tag using 'gh release create'. Auto-generates release notes unless custom notes are provided. Requires GitHub CLI (gh) to be installed and authenticated.",
+		parameters: Type.Object({
+			tag: Type.String({
+				description:
+					"Git tag to create the release from (e.g. 'v1.0.0'). Tag must already exist.",
+			}),
+			title: Type.Optional(
+				Type.String({
+					description: "Release title. Defaults to 'Release {tag}'.",
+				}),
+			),
+			notes: Type.Optional(
+				Type.String({
+					description:
+						"Custom release notes. If omitted, GitHub auto-generates notes from commits since last release.",
+				}),
+			),
+			prerelease: Type.Optional(
+				Type.Boolean({
+					description: "Mark as a pre-release. Default: false.",
+					default: false,
+				}),
+			),
+			dry_run: Type.Optional(
+				Type.Boolean({
+					description:
+						"Preview the release without creating it. Default: false.",
+					default: false,
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			try {
+				const result = createGithubReleaseImpl(params.tag, {
+					cwd: ctx.cwd,
+					dryRun: params.dry_run,
+					title: params.title,
+					notes: params.notes,
+					prerelease: params.prerelease,
+				});
+
+				return {
+					content: [{ type: "text", text: formatGithubReleaseResult(result) }],
+					details: result,
+				};
+			} catch (err: unknown) {
+				const msg = err instanceof Error ? err.message : "Unknown error";
+				return {
+					content: [
+						{
+							type: "text",
+							text: `❌ GitHub release creation failed: ${msg}`,
+						},
+					],
+					details: { error: msg },
+				};
+			}
+		},
+	});
+
+	// ── Tool: publish_npm ──────────────────────────────────────────
+	pi.registerTool({
+		name: "publish_npm",
+		label: "Publish to npm",
+		description:
+			"Publish the current package to npm. Supports custom registries, OTP for 2FA, dist-tags, and dry-run mode.",
+		parameters: Type.Object({
+			otp: Type.Optional(
+				Type.String({
+					description: "One-time password for npm 2FA authentication.",
+				}),
+			),
+			registry: Type.Optional(
+				Type.String({
+					description:
+						"npm registry URL. Defaults to https://registry.npmjs.org/ or value in pi-release.json.",
+				}),
+			),
+			tag: Type.Optional(
+				Type.String({
+					description:
+						"npm dist-tag (e.g. 'beta', 'next'). Defaults to 'latest'.",
+				}),
+			),
+			dry_run: Type.Optional(
+				Type.Boolean({
+					description: "Preview the publish without executing. Default: false.",
+					default: false,
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			try {
+				const result = publishNpmImpl({
+					cwd: ctx.cwd,
+					dryRun: params.dry_run,
+					otp: params.otp,
+					registry: params.registry,
+					tag: params.tag,
+				});
+
+				return {
+					content: [{ type: "text", text: formatPublishResult(result) }],
+					details: result,
+				};
+			} catch (err: unknown) {
+				const msg = err instanceof Error ? err.message : "Unknown error";
+				return {
+					content: [{ type: "text", text: `❌ npm publish failed: ${msg}` }],
+					details: { error: msg },
+				};
+			}
+		},
+	});
+
+	// ── Command: /release ──────────────────────────────────────────
+	pi.registerCommand("release", {
+		description:
+			"Full release flow: bump version → generate changelog → commit → tag → GitHub release → npm publish. Usage: /release [major|minor|patch] [--dry-run]",
+		handler: async (args, ctx) => {
+			const config = loadConfig(ctx.cwd);
+			const argStr = args?.trim() || "";
+
+			// Parse arguments
+			const isDryRun = argStr.includes("--dry-run");
+			const cleanArgs = argStr.replace("--dry-run", "").trim();
+			const bumpType = (cleanArgs || config.defaultBump) as BumpType;
+
+			if (!["major", "minor", "patch"].includes(bumpType)) {
+				ctx.ui.notify(
+					`❌ Invalid bump type '${bumpType}'. Use: major, minor, or patch.`,
+					"error",
+				);
+				return;
+			}
+
+			const dryLabel = isDryRun ? " [DRY RUN]" : "";
+			ctx.ui.notify(`🚀 Starting ${bumpType} release${dryLabel}...`, "info");
+
+			try {
+				// Step 1: Bump version
+				ctx.ui.notify("📦 Step 1/4: Bumping version...", "info");
+				const bump = bumpVersionImpl(bumpType, {
+					cwd: ctx.cwd,
+					dryRun: isDryRun,
+					preReleaseTag: config.preReleaseTag,
+				});
+				ctx.ui.notify(formatBumpResult(bump), "info");
+
+				// Step 2: Generate changelog
+				let changelog = "";
+				if (config.generateChangelog) {
+					ctx.ui.notify("📝 Step 2/4: Generating changelog...", "info");
+					changelog = generateBasicChangelog(bump.newVersion, ctx.cwd);
+
+					if (!isDryRun) {
+						// Append to CHANGELOG.md
+						const changelogPath = join(
+							ctx.cwd || process.cwd(),
+							"CHANGELOG.md",
+						);
+						let existing = "";
+						if (existsSync(changelogPath)) {
+							existing = readFileSync(changelogPath, "utf-8");
+						}
+						const newContent = changelog.replace("# Changelog\n", "");
+						const fullChangelog = existing
+							? `# Changelog\n\n${newContent}\n${existing.replace("# Changelog\n", "").trim()}\n`
+							: changelog;
+						writeFileSync(changelogPath, fullChangelog, "utf-8");
+
+						// Commit changelog
+						exec("git add CHANGELOG.md", ctx.cwd);
+						exec(
+							`git commit -m "docs(release): changelog for ${bump.newVersion}"`,
+							ctx.cwd,
+						);
+					}
+					ctx.ui.notify("   ✅ Changelog generated", "info");
+				} else {
+					ctx.ui.notify(
+						"📝 Step 2/4: Changelog generation skipped (disabled in config)",
+						"info",
+					);
+				}
+
+				// Step 3: GitHub release
+				let ghRelease: GithubReleaseResult | null = null;
+				if (config.createGithubRelease) {
+					ctx.ui.notify("🚀 Step 3/4: Creating GitHub release...", "info");
+					try {
+						ghRelease = createGithubReleaseImpl(bump.tag, {
+							cwd: ctx.cwd,
+							dryRun: isDryRun,
+						});
+						ctx.ui.notify(formatGithubReleaseResult(ghRelease), "info");
+					} catch (err) {
+						const msg = err instanceof Error ? err.message : "Unknown error";
+						ctx.ui.notify(`⚠️  GitHub release skipped: ${msg}`, "warning");
+					}
+				} else {
+					ctx.ui.notify(
+						"🚀 Step 3/4: GitHub release skipped (disabled in config)",
+						"info",
+					);
+				}
+
+				// Step 4: npm publish
+				let publish: PublishResult | null = null;
+				if (config.publishToNpm) {
+					ctx.ui.notify("📤 Step 4/4: Publishing to npm...", "info");
+					try {
+						publish = publishNpmImpl({
+							cwd: ctx.cwd,
+							dryRun: isDryRun,
+						});
+						ctx.ui.notify(formatPublishResult(publish), "info");
+					} catch (err) {
+						const msg = err instanceof Error ? err.message : "Unknown error";
+						ctx.ui.notify(`⚠️  npm publish skipped: ${msg}`, "warning");
+					}
+				} else {
+					ctx.ui.notify(
+						"📤 Step 4/4: npm publish skipped (disabled in config)",
+						"info",
+					);
+				}
+
+				// Final report
+				const report = formatReleaseReport(bump, changelog, ghRelease, publish);
+				ctx.ui.notify(report, "info");
+			} catch (err: unknown) {
+				const msg = err instanceof Error ? err.message : "Unknown error";
+				ctx.ui.notify(`❌ Release failed: ${msg}`, "error");
+			}
+		},
+	});
+
+	// ── Event: session_start ────────────────────────────────────────
+	pi.on("session_start", async (_event, ctx) => {
+		ctx.ui.notify(
+			"🚀 pi-release loaded — run /release to start a release",
+			"info",
+		);
+	});
+}