feat(p1): add upgrade channels and pinning

Author: Kinin-Code-Offical

docs/commands.md

@@ -317,17 +317,21 @@ Usage: cloudsqlctl upgrade [options]
 Upgrade cloudsqlctl to the latest version
 
 Options:
-  --check-only    Only check for updates, do not download or install
-  --no-install    Download only, do not install
-  --asset <mode>  Asset type to download (auto, installer, exe) (default:
-                  "auto")
-  --dir <path>    Download directory (default:
-                  "<USER_HOME>\\AppData\\Local\\CloudSQLCTL\\downloads\\updates")
-  --force         Force update even if version is same or older
-  --no-silent     Run installer in interactive mode (installer only)
-  --no-elevate    Do not attempt to elevate privileges (installer only)
-  --json          Output status in JSON format
-  -h, --help      display help for command
+  --check-only         Only check for updates, do not download or install
+  --no-install         Download only, do not install
+  --asset <mode>       Asset type to download (auto, installer, exe) (default:
+                       "auto")
+  --dir <path>         Download directory (default:
+                       "<USER_HOME>\\AppData\\Local\\CloudSQLCTL\\downloads\\updates")
+  --force              Force update even if version is same or older
+  --no-silent          Run installer in interactive mode (installer only)
+  --no-elevate         Do not attempt to elevate privileges (installer only)
+  --channel <channel>  Update channel (stable or beta)
+  --version <version>  Install a specific version (e.g. 0.4.14 or v0.4.14)
+  --pin <version>      Pin to a specific version for future upgrades
+  --unpin              Clear pinned version
+  --json               Output status in JSON format
+  -h, --help           display help for command
 ```
 
 ### support

src/commands/upgrade.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import path from 'path';
 import { logger } from '../core/logger.js';
+import { readConfig, writeConfig } from '../core/config.js';
 import { USER_PATHS } from '../system/paths.js';
 import {
     checkForUpdates,
@@ -28,16 +29,38 @@ export const upgradeCommand = new Command('upgrade')
     .option('--force', 'Force update even if version is same or older')
     .option('--no-silent', 'Run installer in interactive mode (installer only)')
     .option('--no-elevate', 'Do not attempt to elevate privileges (installer only)')
+    .option('--channel <channel>', 'Update channel (stable or beta)')
+    .option('--version <version>', 'Install a specific version (e.g. 0.4.14 or v0.4.14)')
+    .option('--pin <version>', 'Pin to a specific version for future upgrades')
+    .option('--unpin', 'Clear pinned version')
     .option('--json', 'Output status in JSON format')
     .action(async (options) => {
         try {
             const currentVersion = process.env.CLOUDSQLCTL_VERSION || '0.0.0';
+            const config = await readConfig();
+            const channel = (options.channel || config.updateChannel || 'stable') as 'stable' | 'beta';
+
+            if (channel !== 'stable' && channel !== 'beta') {
+                throw new Error(`Invalid channel '${channel}'. Use 'stable' or 'beta'.`);
+            }
+
+            if (options.unpin) {
+                await writeConfig({ pinnedVersion: undefined });
+            }
+
+            if (options.pin) {
+                await writeConfig({ pinnedVersion: options.pin, updateChannel: channel });
+            } else if (options.channel) {
+                await writeConfig({ updateChannel: channel });
+            }
+            const targetVersion = options.version || options.pin || (!options.unpin ? config.pinnedVersion : undefined);
 
             if (!options.json) {
-                logger.info(`Checking for updates (Current: v${currentVersion})...`);
+                const suffix = targetVersion ? ` (target: ${targetVersion})` : '';
+                logger.info(`Checking for updates (Current: v${currentVersion}, channel: ${channel})${suffix}...`);
             }
 
-            const status = await checkForUpdates(currentVersion);
+            const status = await checkForUpdates(currentVersion, { channel, targetVersion });
 
             if (options.json) {
                 console.log(JSON.stringify(status, null, 2));

src/core/config.ts

@@ -10,6 +10,8 @@ export interface AppConfig {
     lastUpdateCheck?: string;
     lastUpdateAvailableVersion?: string;
     gcloudPath?: string;
+    updateChannel?: 'stable' | 'beta';
+    pinnedVersion?: string;
 }
 
 export async function ensureDirs() {

src/core/selfUpdate.ts

@@ -10,6 +10,8 @@ import { writeConfig } from './config.js';
 const REPO_OWNER = 'Kinin-Code-Offical';
 const REPO_NAME = 'cloudsqlctl';
 const GITHUB_API_URL = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases/latest`;
+const GITHUB_RELEASES_URL = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases`;
+const GITHUB_RELEASE_TAG_URL = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases/tags`;
 const TIMEOUT_MS = 60000;
 const MAX_RETRIES = 2;
 
@@ -42,8 +44,53 @@ export async function getLatestRelease(): Promise<ReleaseInfo> {
     }
 }
 
-export async function checkForUpdates(currentVersion: string): Promise<UpdateStatus> {
-    const release = await getLatestRelease();
+function normalizeTag(tag: string): string {
+    return tag.startsWith('v') ? tag : `v${tag}`;
+}
+
+export async function getReleaseByTag(tag: string): Promise<ReleaseInfo> {
+    try {
+        const response = await axios.get(`${GITHUB_RELEASE_TAG_URL}/${normalizeTag(tag)}`, {
+            timeout: TIMEOUT_MS,
+            headers: { 'User-Agent': 'cloudsqlctl/upgrade' }
+        });
+        return response.data;
+    } catch (error) {
+        logger.error('Failed to fetch release by tag', error);
+        throw error;
+    }
+}
+
+export async function getLatestPrerelease(): Promise<ReleaseInfo> {
+    try {
+        const response = await axios.get(GITHUB_RELEASES_URL, {
+            timeout: TIMEOUT_MS,
+            headers: { 'User-Agent': 'cloudsqlctl/upgrade' }
+        });
+        const releases = Array.isArray(response.data) ? response.data : [];
+        const prerelease = releases.find((r: { prerelease?: boolean; draft?: boolean }) => r.prerelease && !r.draft);
+        if (!prerelease) {
+            throw new Error('No prerelease found');
+        }
+        return prerelease;
+    } catch (error) {
+        logger.error('Failed to fetch latest prerelease info', error);
+        throw error;
+    }
+}
+
+export async function checkForUpdates(
+    currentVersion: string,
+    options: { channel?: 'stable' | 'beta'; targetVersion?: string } = {}
+): Promise<UpdateStatus> {
+    let release: ReleaseInfo;
+    if (options.targetVersion) {
+        release = await getReleaseByTag(options.targetVersion);
+    } else if (options.channel === 'beta') {
+        release = await getLatestPrerelease();
+    } else {
+        release = await getLatestRelease();
+    }
     // Remove 'v' prefix if present for semver comparison
     const latestVer = release.tag_name.replace(/^v/, '');
     const currentVer = currentVersion.replace(/^v/, '');