Add @astrojs/upgrade package for automatic package upgrades

.changeset/tasty-dryers-bathe.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/upgrade': minor
+---
+
+Initial release! `@astrojs/upgrade` is an automated command-line tool for upgrading your Astro integrations

packages/upgrade/README.md

@@ -0,0 +1,51 @@
+# @astrojs/upgrade
+
+A command-line tool for upgrading your Astro integrations and dependencies.
+
+## Usage
+
+`@astrojs/upgrade` should not be added as a dependency to your project, but run as a temporary executable using [`npx`](https://docs.npmjs.com/cli/v10/commands/npx) or [`dlx`](https://pnpm.io/cli/dlx).
+
+**With NPM:**
+
+```bash
+npx @astrojs/upgrade
+```
+
+**With Yarn:**
+
+```bash
+yarn dlx @astrojs/upgrade
+```
+
+**With PNPM:**
+
+```bash
+pnpm dlx @astrojs/upgrade
+```
+
+## Options
+
+### tag (optional)
+
+It is possible to pass a specific `tag` to resolve packages against. If not included, `@astrojs/upgrade` looks for the `latest` tag.
+
+As an example, Astro often releases `beta` versions prior to an upcoming major release. Your project could be updated by running the following commands.
+
+**With NPM:**
+
+```bash
+npx @astrojs/upgrade beta
+```
+
+**With Yarn:**
+
+```bash
+yarn dlx @astrojs/upgrade beta
+```
+
+**With PNPM:**
+
+```bash
+pnpm dlx @astrojs/upgrade beta
+```

packages/upgrade/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@astrojs/upgrade",
+  "version": "0.0.1",
+  "type": "module",
+  "author": "withastro",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/withastro/astro.git",
+    "directory": "packages/upgrade"
+  },
+  "bugs": "https://github.com/withastro/astro/issues",
+  "homepage": "https://astro.build",
+  "exports": {
+    ".": "./upgrade.mjs"
+  },
+  "main": "./upgrade.mjs",
+  "bin": "./upgrade.mjs",
+  "scripts": {
+    "build": "astro-scripts build \"src/index.ts\" --bundle && tsc",
+    "build:ci": "astro-scripts build \"src/index.ts\" --bundle",
+    "dev": "astro-scripts dev \"src/**/*.ts\"",
+    "test": "mocha --exit --timeout 20000 --parallel"
+  },
+  "files": [
+    "dist",
+    "upgrade.js"
+  ],
+  "//a": "MOST PACKAGES SHOULD GO IN DEV_DEPENDENCIES! THEY WILL BE BUNDLED.",
+  "//b": "DEPENDENCIES IS FOR UNBUNDLED PACKAGES",
+  "dependencies": {
+    "@astrojs/cli-kit": "^0.2.3",
+    "semver": "^7.5.4",
+    "which-pm-runs": "^1.1.0",
+    "terminal-link": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/semver": "^7.5.2",
+    "@types/which-pm-runs": "^1.0.0",
+    "arg": "^5.0.2",
+    "astro-scripts": "workspace:*",
+    "chai": "^4.3.7",
+    "mocha": "^10.2.0",
+    "strip-ansi": "^7.1.0"
+  },
+  "engines": {
+    "node": ">=18.14.1"
+  }
+}

packages/upgrade/src/actions/context.ts

@@ -0,0 +1,56 @@
+import { prompt } from '@astrojs/cli-kit';
+import arg from 'arg';
+import { pathToFileURL } from 'node:url';
+import detectPackageManager from 'which-pm-runs';
+
+export interface Context {
+	help: boolean;
+	prompt: typeof prompt;
+	version: string;
+	dryRun?: boolean;
+	cwd: URL;
+	stdin?: typeof process.stdin;
+	stdout?: typeof process.stdout;
+	packageManager: string;
+	packages: PackageInfo[];
+	exit(code: number): never;
+}
+
+export interface PackageInfo {
+	name: string;
+	currentVersion: string;
+	targetVersion: string;
+	tag?: string;
+	isDevDependency?: boolean;
+	isMajor?: boolean;
+	changelogURL?: string;
+	changelogTitle?: string;
+}
+
+export async function getContext(argv: string[]): Promise<Context> {
+	const flags = arg(
+		{
+			'--dry-run': Boolean,
+			'--help': Boolean,
+
+			'-h': '--help',
+		},
+		{ argv, permissive: true }
+	)
+
+	const packageManager = detectPackageManager()?.name ?? 'npm';
+	const { _: [version = 'latest'] = [], '--help': help = false, '--dry-run': dryRun } = flags;
+
+	return {
+		help,
+		prompt,
+		packageManager,
+		packages: [],
+		cwd: new URL(pathToFileURL(process.cwd()) + '/'),
+		dryRun,
+		version,
+		exit(code) {
+			process.exit(code);
+		},
+	} satisfies Context
+}

packages/upgrade/src/actions/help.ts

@@ -0,0 +1,15 @@
+import { printHelp } from '../messages.js';
+
+export function help() {
+	printHelp({
+		commandName: '@astrojs/upgrade',
+		usage: '[version] [...flags]',
+		headline: 'Upgrade Astro dependencies.',
+		tables: {
+			Flags: [
+				['--help (-h)', 'See all available flags.'],
+				['--dry-run', 'Walk through steps without executing.']
+			],
+		},
+	});
+}

packages/upgrade/src/actions/install.ts

@@ -0,0 +1,124 @@
+import type { Context, PackageInfo } from './context.js';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { color, say } from '@astrojs/cli-kit';
+import { pluralize, celebrations, done, error, info, log, spinner, success, upgrade, banner, title, changelog, warn, bye } from '../messages.js';
+import { shell } from '../shell.js';
+import { random, sleep } from '@astrojs/cli-kit/utils';
+
+export async function install(
+	ctx: Pick<Context, 'version' | 'packages' | 'packageManager' | 'prompt' | 'dryRun' | 'exit' | 'cwd'>
+) {
+	await banner();
+	log('')
+	const { current, dependencies, devDependencies } = filterPackages(ctx);
+	const toInstall = [...dependencies, ...devDependencies];
+	for (const packageInfo of current.sort(sortPackages)) {
+		const tag = /^\d/.test(packageInfo.targetVersion) ? packageInfo.targetVersion : packageInfo.targetVersion.slice(1)
+		await info(`${packageInfo.name}`, `is up to date on`, `v${tag}`)
+		await sleep(random(50, 150));
+	}
+	if (toInstall.length === 0 && !ctx.dryRun) {
+		log('')
+		await success(random(celebrations), random(done));
+		return;
+	}
+	const majors: PackageInfo[] = []
+	for (const packageInfo of [...dependencies, ...devDependencies].sort(sortPackages)) {
+		const word = ctx.dryRun ? 'can' : 'will';
+		await upgrade(packageInfo, `${word} be updated to`)
+		if (packageInfo.isMajor) {
+			majors.push(packageInfo)
+		}
+	}
+	if (majors.length > 0) {
+		const { proceed } = await ctx.prompt({
+			name: 'proceed',
+			type: 'confirm',
+			label: title('WAIT'),
+			message: `${pluralize(['One package has', 'Some packages have'], majors.length)} breaking changes. Continue?`,
+			initial: true,
+		});
+		if (!proceed) {
+			return ctx.exit(0);
+		}
+
+		log('');
+
+		await warn('CHECK', `Be sure to follow the ${pluralize('CHANGELOG', majors.length)}.`);
+		for (const pkg of majors.sort(sortPackages)) {
+			await changelog(pkg.name, pkg.changelogTitle!, pkg.changelogURL!);
+		}
+	}
+
+	log('')
+	if (ctx.dryRun) {
+		await info('--dry-run', `Skipping dependency installation`);
+	} else {
+		await runInstallCommand(ctx, dependencies, devDependencies);
+	}
+}
+
+function filterPackages(ctx: Pick<Context, 'packages'>) {
+	const current: PackageInfo[] = [];
+	const dependencies: PackageInfo[] = [];
+	const devDependencies: PackageInfo[] = [];
+	for (const packageInfo of ctx.packages) {
+		const { currentVersion, targetVersion, isDevDependency } = packageInfo;
+		if (currentVersion === targetVersion) {
+			current.push(packageInfo);
+		} else {
+			const arr = isDevDependency ? devDependencies : dependencies;
+			arr.push(packageInfo);
+		}
+	}
+	return { current, dependencies, devDependencies }
+}
+
+function sortPackages(a: PackageInfo, b: PackageInfo): number {
+	if (a.isMajor && !b.isMajor) return 1;
+	if (b.isMajor && !a.isMajor) return -1;
+	if (a.name === 'astro') return -1;
+	if (b.name === 'astro') return 1;
+	if (a.name.startsWith('@astrojs') && !b.name.startsWith('@astrojs')) return -1;
+	if (b.name.startsWith('@astrojs') && !a.name.startsWith('@astrojs')) return 1;
+	return a.name.localeCompare(b.name);
+}
+
+async function runInstallCommand(ctx: Pick<Context, 'cwd' | 'packageManager' | 'exit'>, dependencies: PackageInfo[], devDependencies: PackageInfo[]) {
+	const cwd = fileURLToPath(ctx.cwd);
+	if (ctx.packageManager === 'yarn') await ensureYarnLock({ cwd });
+
+	await spinner({
+		start: `Installing dependencies with ${ctx.packageManager}...`,
+		end: `Installed dependencies!`,
+		while: async () => {
+			try {
+				if (dependencies.length > 0) {
+					await shell(ctx.packageManager, ['install', ...dependencies.map(({ name, targetVersion }) => `${name}@${(targetVersion).replace(/^\^/, '')}`)], { cwd, timeout: 90_000, stdio: 'ignore' })
+				}
+				if (devDependencies.length > 0) {
+					await shell(ctx.packageManager, ['install', '--save-dev', ...devDependencies.map(({ name, targetVersion }) => `${name}@${(targetVersion).replace(/^\^/, '')}`)], { cwd, timeout: 90_000, stdio: 'ignore' })
+				}
+			} catch {
+				const packages = [...dependencies, ...devDependencies].map(({ name, targetVersion }) => `${name}@${targetVersion}`).join(' ')
+				log('');
+				error(
+					'error',
+					`Dependencies failed to install, please run the following command manually:\n${color.bold(`${ctx.packageManager} install ${packages}`)}`
+				);
+				return ctx.exit(1);
+			}
+		},
+	});
+
+	await say([`${random(celebrations)} ${random(done)}`, random(bye)], { clear: false });
+}
+
+async function ensureYarnLock({ cwd }: { cwd: string }) {
+	const yarnLock = path.join(cwd, 'yarn.lock');
+	if (fs.existsSync(yarnLock)) return;
+	return fs.promises.writeFile(yarnLock, '', { encoding: 'utf-8' });
+}