@agentuity/cli 0.0.91 → 0.0.93

package/src/cmd/cloud/storage/upload.ts

@@ -24,10 +24,18 @@ export const uploadSubcommand = createSubcommand({
 			command: `${getCommand('cloud storage put')} my-bucket file.txt --content-type text/plain`,
 			description: 'Upload file with content type',
 		},
+		{
+			command: `${getCommand('cloud storage upload')} my-bucket file.txt --key custom-name.txt`,
+			description: 'Upload file with custom object key',
+		},
 		{
 			command: `cat file.txt | ${getCommand('cloud storage upload')} my-bucket -`,
 			description: 'Upload from stdin',
 		},
+		{
+			command: `cat data.json | ${getCommand('cloud storage upload')} my-bucket - --key data.json`,
+			description: 'Upload from stdin with custom key',
+		},
 	],
 	schema: {
 		args: z.object({
@@ -35,6 +43,10 @@ export const uploadSubcommand = createSubcommand({
 			filename: z.string().describe('File path to upload or "-" for STDIN'),
 		}),
 		options: z.object({
+			key: z
+				.string()
+				.optional()
+				.describe('Remote object key (defaults to basename or "stdin" for piped uploads)'),
 			contentType: z
 				.string()
 				.optional()
@@ -75,40 +87,38 @@ export const uploadSubcommand = createSubcommand({
 			);
 		}
 
-		// TODO: we need to optimize this to not load the entire file in memory!
-
-		// Read file content
-		let fileContent: Buffer;
-		let actualFilename: string;
+		// Prepare streaming upload - we don't buffer the entire file in memory
+		let stream: ReadableStream<Uint8Array>;
 
 		if (args.filename === '-') {
-			// Read from STDIN (binary-safe)
-			try {
-				const arrayBuffer = await Bun.readableStreamToArrayBuffer(Bun.stdin.stream());
-				fileContent = Buffer.from(arrayBuffer);
-				actualFilename = 'stdin';
-			} catch (error) {
-				tui.fatal(
-					`Cannot read from stdin: ${error instanceof Error ? error.message : String(error)}`,
-					ErrorCode.FILE_NOT_FOUND
-				);
-			}
+			// Stream from STDIN
+			stream = Bun.stdin.stream();
 		} else {
-			// Read from file
+			// Stream from file
 			const file = Bun.file(args.filename);
 			if (!(await file.exists())) {
 				tui.fatal(`File not found: ${args.filename}`, ErrorCode.FILE_NOT_FOUND);
 			}
-			fileContent = Buffer.from(await file.arrayBuffer());
-			actualFilename = basename(args.filename);
+			stream = file.stream();
 		}
 
-		// Auto-detect content type
+		// Derive the remote object key:
+		// 1. Use --key if provided
+		// 2. For stdin (-), default to 'stdin'
+		// 3. For files, use the basename
+		const objectKey =
+			opts.key && opts.key.trim().length > 0
+				? opts.key
+				: args.filename === '-'
+					? 'stdin'
+					: basename(args.filename);
+
+		// Auto-detect content type from the object key's extension
+		// This allows content-type detection for stdin when --key is provided
 		let contentType = opts.contentType;
-		if (!contentType && args.filename !== '-') {
-			const filename = basename(args.filename);
-			const dotIndex = filename.lastIndexOf('.');
-			const ext = dotIndex > 0 ? filename.substring(dotIndex + 1).toLowerCase() : undefined;
+		if (!contentType) {
+			const dotIndex = objectKey.lastIndexOf('.');
+			const ext = dotIndex > 0 ? objectKey.substring(dotIndex + 1).toLowerCase() : undefined;
 			const mimeTypes: Record<string, string> = {
 				txt: 'text/plain',
 				html: 'text/html',
@@ -139,11 +149,15 @@ export const uploadSubcommand = createSubcommand({
 			region: bucket.region,
 		});
 
+		// Upload using streaming - wrap the stream in a Response object
+		// S3Client.write accepts Response which allows streaming without buffering in memory
+		let bytesUploaded = 0;
+
 		await tui.spinner({
-			message: `Uploading ${actualFilename} to ${args.name}`,
+			message: `Uploading ${objectKey} to ${args.name}`,
 			clearOnSuccess: true,
 			callback: async () => {
-				await s3Client.write(actualFilename, fileContent, {
+				bytesUploaded = await s3Client.write(objectKey, new Response(stream), {
 					type: contentType,
 				});
 			},
@@ -151,15 +165,15 @@ export const uploadSubcommand = createSubcommand({
 
 		if (!options.json) {
 			tui.success(
-				`Uploaded ${tui.bold(actualFilename)} to ${tui.bold(args.name)} (${fileContent.length} bytes)`
+				`Uploaded ${tui.bold(objectKey)} to ${tui.bold(args.name)} (${bytesUploaded} bytes)`
 			);
 		}
 
 		return {
 			success: true,
 			bucket: args.name,
-			filename: actualFilename,
-			size: fileContent.length,
+			filename: objectKey,
+			size: bytesUploaded,
 		};
 	},
 });

package/src/cmd/dev/index.ts

@@ -25,8 +25,9 @@ import { BuildMetadata } from '@agentuity/server';
 import { getCommand } from '../../command-prefix';
 import { notifyWorkbenchClients } from '../../utils/workbench-notify';
 import { getEnvFilePaths, readEnvFile } from '../../env-util';
+import { writeAgentsDocs } from '../../agents-docs';
 
-const shouldDisableInteractive = (interactive?: boolean) => {
+const shouldDisableInteractive= (interactive?: boolean) => {
 	if (!interactive) {
 		return true;
 	}
@@ -102,6 +103,9 @@ export const command = createCommand({
 
 		await saveProjectDir(rootDir);
 
+		// Regenerate AGENTS.md files if they are missing (e.g., after node_modules reinstall)
+		await writeAgentsDocs(rootDir, { onlyIfMissing: true });
+
 		let devmode: DevmodeResponse | undefined;
 		let gravityBin: string | undefined;
 		let gravityURL: string | undefined;

package/src/cmd/index.ts

@@ -13,6 +13,7 @@ export async function discoverCommands(): Promise<CommandDefinition[]> {
 		import('./profile').then((m) => m.command),
 		import('./project').then((m) => m.command),
 		import('./repl').then((m) => m.command),
+		import('./setup').then((m) => m.command),
 		import('./upgrade').then((m) => m.command),
 		import('./version').then((m) => m.command),
 	]);

package/src/cmd/project/download.ts

@@ -16,13 +16,11 @@ import { extract, type Headers } from 'tar-fs';
 import { StructuredError, type Logger } from '@agentuity/core';
 import * as tui from '../../tui';
 import { downloadWithSpinner } from '../../download';
-import { generateLLMPrompt as generateCLIPrompt } from '../ai/prompt/llm';
-import { generateLLMPrompt as generateAgentPrompt } from '../ai/prompt/agent';
-import { generateLLMPrompt as generateWebPrompt } from '../ai/prompt/web';
-import { generateLLMPrompt as generateAPIPrompt } from '../ai/prompt/api';
+import { writeAgentsDocs } from '../../agents-docs';
 import type { TemplateInfo } from './templates';
 
 const GITHUB_BRANCH = 'main';
+const BASE_TEMPLATE_DIR = '_base';
 
 interface DownloadOptions {
 	dest: string;
@@ -45,7 +43,78 @@ const TemplateDirectoryNotFoundError = StructuredError('TemplateDirectoryNotFoun
 	directory: string;
 }>();
 
-async function cleanup(sourceDir: string, dest: string) {
+async function copyTemplateFiles(sourceDir: string, dest: string, skipGitignoreRename = false) {
+	if (!existsSync(sourceDir)) {
+		return; // Source directory doesn't exist, skip (overlay may be empty)
+	}
+
+	// Copy all files from source to dest (overlay wins on conflicts)
+	const files = readdirSync(sourceDir);
+	for (const file of files) {
+		// Skip package.overlay.json - it's handled separately for merging
+		if (file === 'package.overlay.json') {
+			continue;
+		}
+		// Skip .gitkeep files - they're just placeholders for empty directories
+		if (file === '.gitkeep') {
+			continue;
+		}
+		cpSync(join(sourceDir, file), join(dest, file), { recursive: true });
+	}
+
+	// Rename gitignore -> .gitignore (only do this once, after all copies)
+	if (!skipGitignoreRename) {
+		const gi = join(dest, 'gitignore');
+		if (existsSync(gi)) {
+			renameSync(gi, join(dest, '.gitignore'));
+		}
+	}
+}
+
+async function mergePackageJson(dest: string, overlayDir: string) {
+	const basePackagePath = join(dest, 'package.json');
+	const overlayPackagePath = join(overlayDir, 'package.overlay.json');
+
+	// If no overlay package.json exists, nothing to merge
+	if (!existsSync(overlayPackagePath)) {
+		return;
+	}
+
+	// Read base package.json
+	const basePackage = JSON.parse(await Bun.file(basePackagePath).text());
+
+	// Read overlay package.json
+	const overlayPackage = JSON.parse(await Bun.file(overlayPackagePath).text());
+
+	// Merge dependencies (overlay wins on conflicts)
+	if (overlayPackage.dependencies) {
+		basePackage.dependencies = {
+			...basePackage.dependencies,
+			...overlayPackage.dependencies,
+		};
+	}
+
+	// Merge devDependencies (overlay wins on conflicts)
+	if (overlayPackage.devDependencies) {
+		basePackage.devDependencies = {
+			...basePackage.devDependencies,
+			...overlayPackage.devDependencies,
+		};
+	}
+
+	// Merge scripts (overlay wins on conflicts)
+	if (overlayPackage.scripts) {
+		basePackage.scripts = {
+			...basePackage.scripts,
+			...overlayPackage.scripts,
+		};
+	}
+
+	// Write merged package.json
+	await Bun.write(basePackagePath, JSON.stringify(basePackage, null, '\t') + '\n');
+}
+
+async function _cleanup(sourceDir: string, dest: string) {
 	if (!existsSync(sourceDir)) {
 		throw new TemplateDirectoryNotFoundError({
 			directory: sourceDir,
@@ -75,28 +144,59 @@ export async function downloadTemplate(options: DownloadOptions): Promise<void>
 
 	// Copy from local directory if provided
 	if (templateDir) {
-		const sourceDir = resolve(join(templateDir, template.directory));
+		const baseDir = resolve(join(templateDir, BASE_TEMPLATE_DIR));
+		const overlayDir = resolve(join(templateDir, template.directory));
 
-		if (!existsSync(sourceDir)) {
+		// Base template must exist
+		if (!existsSync(baseDir)) {
 			throw new TemplateDirectoryNotFoundError({
-				directory: sourceDir,
-				message: `Template directory not found: ${sourceDir}`,
+				directory: baseDir,
+				message: `Base template directory not found: ${baseDir}`,
 			});
 		}
 
-		return cleanup(sourceDir, dest);
+		// Overlay directory must exist (even if empty)
+		if (!existsSync(overlayDir)) {
+			throw new TemplateDirectoryNotFoundError({
+				directory: overlayDir,
+				message: `Template directory not found: ${overlayDir}`,
+			});
+		}
+
+		await tui.spinner({
+			type: 'progress',
+			message: '📦 Copying template files...',
+			clearOnSuccess: true,
+			callback: async (progress) => {
+				// Step 1: Copy base template files (skip gitignore rename for now)
+				await copyTemplateFiles(baseDir, dest, true);
+				progress(33);
+
+				// Step 2: Copy overlay template files (overlay wins on conflicts)
+				await copyTemplateFiles(overlayDir, dest, false);
+				progress(66);
+
+				// Step 3: Merge package.json with overlay dependencies
+				await mergePackageJson(dest, overlayDir);
+				progress(100);
+			},
+		});
+
+		return;
 	}
 
 	// Download from GitHub
 	const branch = templateBranch || GITHUB_BRANCH;
-	const templatePath = `templates/${template.directory}`;
+	const basePath = `templates/${BASE_TEMPLATE_DIR}`;
+	const overlayPath = `templates/${template.directory}`;
 	const url = `https://agentuity.sh/template/sdk/${branch}/tar.gz`;
 	const tempDir = mkdtempSync(join(tmpdir(), 'agentuity-'));
 	const tarballPath = join(tempDir, 'download.tar.gz');
 
 	logger.debug('[download] URL: %s', url);
 	logger.debug('[download] Branch: %s', branch);
-	logger.debug('[download] Template path: %s', templatePath);
+	logger.debug('[download] Base path: %s', basePath);
+	logger.debug('[download] Overlay path: %s', overlayPath);
 	logger.debug('[download] Temp dir: %s', tempDir);
 
 	try {
@@ -124,37 +224,53 @@ export async function downloadTemplate(options: DownloadOptions): Promise<void>
 			}
 		);
 
-		// Step 2: Extract tarball
-		// We extract only the files within the template directory
+		// Step 2: Extract tarball - extract both base and overlay templates
 		// The tarball structure is: sdk-{branch}/templates/{template.directory}/...
-		const extractDir = join(tempDir, 'extract');
-		mkdirSync(extractDir, { recursive: true });
-
-		const prefix = `sdk-${branch}/${templatePath}/`;
-		logger.debug('[extract] Extract dir: %s', extractDir);
-		logger.debug('[extract] Filter prefix: %s', prefix);
+		const baseExtractDir = join(tempDir, 'base');
+		const overlayExtractDir = join(tempDir, 'overlay');
+		mkdirSync(baseExtractDir, { recursive: true });
+		mkdirSync(overlayExtractDir, { recursive: true });
+
+		const basePrefix = `sdk-${branch}/${basePath}/`;
+		const overlayPrefix = `sdk-${branch}/${overlayPath}/`;
+		logger.debug('[extract] Base extract dir: %s', baseExtractDir);
+		logger.debug('[extract] Overlay extract dir: %s', overlayExtractDir);
+		logger.debug('[extract] Base prefix: %s', basePrefix);
+		logger.debug('[extract] Overlay prefix: %s', overlayPrefix);
 
 		// Track extraction stats for debugging
 		let ignoredCount = 0;
-		let extractedCount = 0;
+		let baseExtractedCount = 0;
+		let overlayExtractedCount = 0;
 
 		// Track which entries we've mapped so we don't ignore them later
 		// Note: tar-fs calls map BEFORE ignore (despite what docs say)
 		const mappedEntries = new Set<string>();
 
-		const extractor = extract(extractDir, {
+		const extractor = extract(tempDir, {
 			// map callback: called FIRST, allows modifying the entry before extraction
-			// We strip the prefix so files are extracted to the root of extractDir
+			// We extract base files to baseExtractDir and overlay files to overlayExtractDir
 			map: (header: Headers) => {
 				const originalName = header.name;
-				if (header.name.startsWith(prefix) && header.name.length > prefix.length) {
-					// This is a file/dir we want to extract - strip the prefix
-					header.name = header.name.substring(prefix.length);
-					mappedEntries.add(header.name); // Track that we mapped this
-					logger.debug('[extract] MAP: %s -> %s', originalName, header.name);
-					logger.debug('[extract] EXTRACT: %s', originalName);
-					extractedCount++;
+
+				// Check if this is a base template file
+				if (header.name.startsWith(basePrefix) && header.name.length > basePrefix.length) {
+					header.name = `base/${header.name.substring(basePrefix.length)}`;
+					mappedEntries.add(header.name);
+					logger.debug('[extract] MAP BASE: %s -> %s', originalName, header.name);
+					baseExtractedCount++;
+				}
+				// Check if this is an overlay template file
+				else if (
+					header.name.startsWith(overlayPrefix) &&
+					header.name.length > overlayPrefix.length
+				) {
+					header.name = `overlay/${header.name.substring(overlayPrefix.length)}`;
+					mappedEntries.add(header.name);
+					logger.debug('[extract] MAP OVERLAY: %s -> %s', originalName, header.name);
+					overlayExtractedCount++;
 				}
+
 				return header;
 			},
 			// ignore callback: called AFTER map, receives the MAPPED name
@@ -183,10 +299,28 @@ export async function downloadTemplate(options: DownloadOptions): Promise<void>
 
 		logger.debug('[extract] Extraction complete');
 		logger.debug('[extract] Ignored entries: %d', ignoredCount);
-		logger.debug('[extract] Extracted entries: %d', extractedCount);
+		logger.debug('[extract] Base extracted entries: %d', baseExtractedCount);
+		logger.debug('[extract] Overlay extracted entries: %d', overlayExtractedCount);
 
-		// Step 3: Copy extracted files to destination
-		await cleanup(extractDir, dest);
+		// Step 3: Copy base template files, then overlay template files
+		await tui.spinner({
+			type: 'progress',
+			message: '📦 Copying template files...',
+			clearOnSuccess: true,
+			callback: async (progress) => {
+				// Copy base template files (skip gitignore rename for now)
+				await copyTemplateFiles(baseExtractDir, dest, true);
+				progress(33);
+
+				// Copy overlay template files (overlay wins on conflicts)
+				await copyTemplateFiles(overlayExtractDir, dest, false);
+				progress(66);
+
+				// Merge package.json with overlay dependencies
+				await mergePackageJson(dest, overlayExtractDir);
+				progress(100);
+			},
+		});
 	} finally {
 		// Clean up temp directory
 		logger.debug('[cleanup] Removing temp dir: %s', tempDir);
@@ -214,6 +348,30 @@ export async function setupProject(options: SetupOptions): Promise<void> {
 		}
 	}
 
+	// Run optional template setup script if it exists
+	// This allows templates to run custom setup logic after bun install
+	const setupScriptPath = join(dest, '_setup.ts');
+	if (existsSync(setupScriptPath)) {
+		try {
+			const exitCode = await tui.runCommand({
+				command: 'bun _setup.ts',
+				cwd: dest,
+				cmd: ['bun', '_setup.ts'],
+				clearOnSuccess: true,
+			});
+			if (exitCode !== 0) {
+				logger.error('Template setup script failed');
+			}
+		} finally {
+			// Always delete the setup script after running (or attempting to run)
+			try {
+				rmSync(setupScriptPath);
+			} catch {
+				// Ignore errors when deleting the setup script
+			}
+		}
+	}
+
 	// Build project
 	if (!noBuild) {
 		const exitCode = await tui.runCommand({
@@ -278,32 +436,9 @@ export async function setupProject(options: SetupOptions): Promise<void> {
 		});
 	}
 
-	// generate and write the AGENTS.md for the cli
-	const cliDir = join(dest, 'node_modules', '@agentuity', 'cli');
-	if (existsSync(cliDir)) {
-		const agentFile = join(cliDir, 'AGENTS.md');
-		const prompt = generateCLIPrompt();
-		await Bun.write(agentFile, prompt);
-	}
-
-	// generate and write AGENTS.md for each of the main folders
-	const agentDir = join(dest, 'src', 'agent');
-	if (existsSync(agentDir)) {
-		const agentAPIFile = join(agentDir, 'AGENTS.md');
-		await Bun.write(agentAPIFile, generateAgentPrompt());
-	}
-
-	const apiDir = join(dest, 'src', 'api');
-	if (existsSync(apiDir)) {
-		const agentAPIFile = join(apiDir, 'AGENTS.md');
-		await Bun.write(agentAPIFile, generateAPIPrompt());
-	}
-
-	const webDir = join(dest, 'src', 'web');
-	if (existsSync(webDir)) {
-		const webFile = join(webDir, 'AGENTS.md');
-		await Bun.write(webFile, generateWebPrompt());
-	}
+	// Generate and write AGENTS.md files for the CLI and source folders
+	// Always overwrite during project setup to ensure fresh content
+	await writeAgentsDocs(dest);
 }
 
 async function replaceInFiles(dir: string, projectName: string, dirName: string): Promise<void> {

package/src/cmd/setup/index.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import { showBanner } from '../../banner';
+import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
+
+export const command = createCommand({
+	name: 'setup',
+	description: 'Display first-run setup information (internal use)',
+	hidden: true,
+	skipUpgradeCheck: true,
+	tags: ['read-only', 'fast'],
+	optional: { auth: true },
+	schema: {
+		options: z.object({
+			nonInteractive: z.boolean().optional().describe('Run in non-interactive mode'),
+		}),
+	},
+
+	async handler(ctx) {
+		const { opts, auth } = ctx;
+		const _nonInteractive = opts.nonInteractive ?? false;
+
+		tui.newline();
+		showBanner();
+		tui.newline();
+
+		if (!auth?.expires) {
+			tui.output(`${tui.muted('To get started, run:')}`);
+			tui.newline();
+			tui.output(
+				`${getCommand('login')}        ${tui.muted('Login to an existing account (or signup)')}`
+			);
+			tui.output(`${getCommand('create')}       ${tui.muted('Create a project')}`);
+			tui.output(`${getCommand('help')}         ${tui.muted('List commands and options')}`);
+		} else {
+			tui.success('Welcome back! 🙌');
+		}
+
+		return undefined;
+	},
+});

package/src/cmd/upgrade/index.ts

@@ -1,5 +1,5 @@
 import { createCommand } from '../../types';
-import { getVersion } from '../../version';
+import { getVersion, getCompareUrl, getReleaseUrl, toTag } from '../../version';
 import { getCommand } from '../../command-prefix';
 import { z } from 'zod';
 import { ErrorCode, createError, exitWithError } from '../../errors';
@@ -301,6 +301,13 @@ export const command = createCommand({
 				tui.info(`Current version: ${tui.muted(currentVersion)}`);
 				tui.info(`Latest version:  ${tui.bold(latestVersion)}`);
 				tui.newline();
+				if (toTag(currentVersion) !== toTag(latestVersion)) {
+					tui.warning(
+						`What's changed:  ${tui.link(getCompareUrl(currentVersion, latestVersion))}`
+					);
+				}
+				tui.success(`Release notes:   ${tui.link(getReleaseUrl(latestVersion))}`);
+				tui.newline();
 
 				const shouldUpgrade = await tui.confirm('Do you want to upgrade?', true);
 

package/src/tui.ts

@@ -307,7 +307,7 @@ export function link(url: string, title?: string, color = getColor('link')): str
 /**
  * Check if terminal supports OSC 8 hyperlinks
  */
-function supportsHyperlinks(): boolean {
+export function supportsHyperlinks(): boolean {
 	const term = process.env.TERM || '';
 	const termProgram = process.env.TERM_PROGRAM || '';
 	const wtSession = process.env.WT_SESSION || '';
@@ -361,7 +361,7 @@ export function output(message: string): void {
  * which causes incorrect alignment. We strip OSC 8 codes first, then use Bun.stringWidth()
  * to handle regular ANSI codes and unicode characters correctly.
  */
-function getDisplayWidth(str: string): number {
+export function getDisplayWidth(str: string): number {
 	// Remove OSC-8 hyperlink sequences using Unicode escapes (\u001b = ESC, \u0007 = BEL) to satisfy linter
 	// eslint-disable-next-line no-control-regex
 	const withoutOSC8 = str.replace(/\u001b\]8;;[^\u0007]*\u0007/g, '');
@@ -371,7 +371,7 @@ function getDisplayWidth(str: string): number {
 /**
  * Strip all ANSI escape sequences from a string
  */
-function stripAnsi(str: string): string {
+export function stripAnsi(str: string): string {
 	// eslint-disable-next-line no-control-regex
 	return str.replace(/\u001b\[[0-9;]*m/g, '').replace(/\u001b\]8;;[^\u0007]*\u0007/g, '');
 }

package/src/version-check.ts

@@ -1,6 +1,6 @@
 import type { Config, Logger, CommandDefinition } from './types';
 import { isRunningFromExecutable, fetchLatestVersion } from './cmd/upgrade';
-import { getVersion } from './version';
+import { getVersion, getCompareUrl, getReleaseUrl, toTag } from './version';
 import * as tui from './tui';
 import { saveConfig } from './config';
 import { $ } from 'bun';
@@ -97,6 +97,11 @@ async function promptUpgrade(currentVersion: string, latestVersion: string): Pro
 	tui.info(`Current version: ${tui.muted(currentVersion)}`);
 	tui.info(`Latest version:  ${tui.bold(latestVersion)}`);
 	tui.newline();
+	if (toTag(currentVersion) !== toTag(latestVersion)) {
+		tui.warning(`What's changed:  ${tui.link(getCompareUrl(currentVersion, latestVersion))}`);
+	}
+	tui.success(`Release notes:   ${tui.link(getReleaseUrl(latestVersion))}`);
+	tui.newline();
 
 	return await tui.confirm('Would you like to upgrade now?', true);
 }

package/src/version.ts

@@ -27,3 +27,31 @@ export function getRevision(): string {
 	// Bun provides git SHA via Bun.revision
 	return typeof Bun !== 'undefined' && Bun.revision ? Bun.revision.substring(0, 8) : 'unknown';
 }
+
+const GITHUB_REPO_URL = 'https://github.com/agentuity/sdk';
+
+/**
+ * Normalize a version string to a Git tag format (with 'v' prefix)
+ */
+export function toTag(version: string): string {
+	return version.startsWith('v') ? version : `v${version}`;
+}
+
+/**
+ * Get the GitHub URL for comparing two versions
+ * @param fromVersion - The current/old version
+ * @param toVersion - The new/target version
+ * @returns GitHub compare URL
+ */
+export function getCompareUrl(fromVersion: string, toVersion: string): string {
+	return `${GITHUB_REPO_URL}/compare/${toTag(fromVersion)}...${toTag(toVersion)}`;
+}
+
+/**
+ * Get the GitHub URL for a specific release
+ * @param version - The version to get the release URL for
+ * @returns GitHub release URL
+ */
+export function getReleaseUrl(version: string): string {
+	return `${GITHUB_REPO_URL}/releases/tag/${toTag(version)}`;
+}