grada-run 0.0.2 → 0.32.0

package/src/commands/logs.js

@@ -0,0 +1,256 @@
+import { CloudWatchLogsClient, FilterLogEventsCommand, DescribeLogStreamsCommand } from '@aws-sdk/client-cloudwatch-logs';
+import color from 'picocolors';
+import { trackEvent, flushTelemetry, trackSuccess, trackFailure } from '../core/telemetry.js';
+import { parseFlags, normalizeOptions, normalizeArgv } from '../utils/args.js';
+import { isAuthError, handleAuthErrorBranch, resolveClient } from '../utils/aws.js';
+import { resolveRegion, resolveProjectName, resolveLogGroup, resolveCwd, readTerraformComputeTarget } from '../utils/resolvers.js';
+import { failProjectNotInitialized } from '../utils/command.js';
+import { sleep } from '../utils/system.js';
+
+export const DEFAULT_TAIL_LINES = 50;
+export const DEFAULT_SINCE = '1h';
+export const FOLLOW_POLL_INTERVAL_MS = 2000;
+export const ERROR_KEYWORDS = ['ERROR', 'FATAL', 'Exception', 'fail', '500', '502'];
+
+const ERROR_PATTERN = /ERROR|FATAL|Exception|fail|500|502/i;
+const HIGHLIGHT_ERROR_PATTERN = /error|fatal|exception|fail|5\d\d/i;
+const WARN_PATTERN = /warn/i;
+
+const SINCE_RE = /^(\d+)\s*(s|sec|secs|second|seconds|m|min|mins|minute|minutes|h|hr|hrs|hour|hours|d|day|days|w|week|weeks)?$/i;
+const UNIT_MS = { s: 1000, m: 60 * 1000, h: 60 * 60 * 1000, d: 24 * 60 * 60 * 1000, w: 7 * 24 * 60 * 60 * 1000 };
+
+export function resolveServiceName(options = {}, cwd = process.cwd()) {
+    for (const key of ['service', 'serviceName', 'container']) {
+        if (typeof options[key] === 'string' && options[key].trim()) {
+            return options[key].trim();
+        }
+    }
+    return resolveProjectName(options, cwd);
+}
+
+export function hasExplicitService(options = {}) {
+    return ['service', 'serviceName', 'container'].some(
+        (key) => typeof options[key] === 'string' && options[key].trim()
+    );
+}
+
+export function normalizeTailLines(value) {
+    const n = typeof value === 'string' && value.trim() === '' ? NaN : parseInt(value, 10);
+    if (!Number.isFinite(n) || n < 1) return DEFAULT_TAIL_LINES;
+    return n;
+}
+
+export function parseSinceDuration(input) {
+    if (input === undefined || input === null || input === '') return UNIT_MS.h;
+    if (typeof input === 'number' && Number.isFinite(input)) return Math.max(0, input * 1000);
+    const match = String(input).trim().match(SINCE_RE);
+    if (!match) return UNIT_MS.h;
+    const amount = parseInt(match[1], 10);
+    const unit = (match[2] || 's').toLowerCase()[0];
+    return amount * (UNIT_MS[unit] || UNIT_MS.h);
+}
+
+// Alias kept for convenience; both names are part of the public surface.
+export const parseSince = parseSinceDuration;
+
+export function isErrorLine(line) {
+    return ERROR_PATTERN.test(String(line ?? ''));
+}
+
+// Alias kept for convenience.
+export const matchesErrorFilter = isErrorLine;
+
+export function extractTaskId(logStreamName) {
+    if (!logStreamName) return '';
+    const parts = String(logStreamName).split('/');
+    return parts[parts.length - 1] || '';
+}
+
+export function formatLogLine(event = {}) {
+    const timestamp = event.timestamp ? new Date(event.timestamp).toISOString() : new Date().toISOString();
+    const taskId = extractTaskId(event.logStreamName);
+    const message = String(event.message ?? '').replace(/\n$/, '');
+    let body = message;
+    if (HIGHLIGHT_ERROR_PATTERN.test(message)) {
+        body = color.red(message);
+    } else if (WARN_PATTERN.test(message)) {
+        body = color.yellow(message);
+    }
+    return taskId ? `${color.dim(timestamp)} ${color.dim(taskId)} ${body}` : `${color.dim(timestamp)} ${body}`;
+}
+
+// Alias kept for convenience.
+export const formatLogEvent = formatLogLine;
+
+export function parseLogsArgs(argv = []) {
+    const args = normalizeArgv(argv);
+    if (args[0] === 'logs') args.shift();
+    const { options, rest } = parseFlags(args, {
+        string: ['since', 'region'],
+        number: ['tail'],
+        bareBoolean: ['follow', 'error'],
+        alias: { f: 'follow' },
+    });
+    const positionals = rest.filter((arg) => typeof arg === 'string' && !arg.startsWith('-'));
+    if (positionals.length > 0) options.service = positionals[0];
+    return options;
+}
+
+function eventKey(event) {
+    if (event.eventId) return `id:${event.eventId}`;
+    return `${event.timestamp}:${event.message}`;
+}
+
+export function isNotFoundError(error) {
+    return error && (
+        error.name === 'ResourceNotFoundException' ||
+        /log group .* (does not exist|not found|cannot be found)/i.test(error.message || '')
+    );
+}
+
+// CloudWatch log stream for one container run. Mirrors the `awslogs`
+// configuration in `templates/terraform/main.tf` (`stream-prefix "ecs"`):
+// `<prefix>/<container-name>/<task-id>`. Inverse of `extractTaskId`.
+export function buildLogStreamName(containerName, taskId, prefix = 'ecs') {
+    return `${prefix}/${containerName}/${taskId}`;
+}
+
+function printMissingLogGroupGuidance(logGroup, service, region) {
+    const prefix = `/${String(logGroup).split('/').filter(Boolean).slice(0, 2).join('/')}/`;
+    console.log(color.yellow(`\n⚠ No log group found for "${service}" (expected ${logGroup}).`));
+    console.log(color.dim(`List matching groups with: aws logs describe-log-groups --log-group-name-prefix "${prefix}" --region ${region}`));
+}
+
+export async function runLogs(input = {}) {
+    const options = normalizeOptions(input);
+    let cwd;
+    let region;
+    let service;
+    let logGroup;
+    try {
+        cwd = resolveCwd(options);
+        region = resolveRegion(options, cwd);
+        service = resolveServiceName(options, cwd);
+        logGroup = resolveLogGroup(options, cwd);
+    } catch {
+        return failProjectNotInitialized({ event: 'logs_streamed' });
+    }
+    const tail = normalizeTailLines(options.tail ?? options.tailLines ?? options.lines);
+    const follow = Boolean(options.follow ?? options.f);
+    const onlyErrors = Boolean(options.error ?? options.onlyErrors ?? options.filterErrors);
+    // Lambda stream names are date/request-id based, not container names, so
+    // a service stream-prefix filter would hide every event on that target.
+    const isLambda = readTerraformComputeTarget(cwd) === 'lambda';
+    const explicitService = hasExplicitService(options) && !isLambda;
+
+    const sinceRaw = options.since ?? options.sinceDuration ?? (follow ? undefined : DEFAULT_SINCE);
+    const startTime = sinceRaw === undefined ? undefined : Date.now() - parseSinceDuration(sinceRaw);
+
+    const pollIntervalMs = options.pollIntervalMs ?? FOLLOW_POLL_INTERVAL_MS;
+    const maxPolls = options.maxPolls ?? (follow ? Infinity : 1);
+
+    if (process.env.CI_MOCK_AWS === 'true' && !options.logsClient && !options.client) {
+        const mocked = ['INFO service started', 'ERROR mocked failure for offline mode'];
+        const visible = onlyErrors ? mocked.filter(isErrorLine) : mocked;
+        for (const line of visible.slice(-tail)) console.log(formatLogLine({ timestamp: Date.now(), message: line }));
+        return { logs: visible.slice(-tail), logGroup, region, service, mocked: true };
+    }
+
+    const logsClient = resolveClient(options.logsClient ?? options.client ?? options.cloudwatchClient, CloudWatchLogsClient, { region });
+
+    let stopped = false;
+    const onSigint = () => {
+        stopped = true;
+        console.log(color.dim('\nStopped following logs.'));
+    };
+    if (follow) process.once('SIGINT', onSigint);
+
+    try {
+        try {
+            await logsClient.send(new DescribeLogStreamsCommand({ logGroupName: logGroup, limit: 1 }));
+        } catch (verifyError) {
+            if (isAuthError(verifyError)) throw verifyError;
+            if (isNotFoundError(verifyError)) {
+                printMissingLogGroupGuidance(logGroup, service, region);
+                return { logs: [], logGroup, region, service };
+            }
+            // Any other verification failure is non-fatal: the fetch below is authoritative.
+        }
+
+        const seen = new Set();
+        const collected = [];
+        let nextToken;
+        let polls = 0;
+        let firstPoll = true;
+
+        do {
+            const input = { logGroupName: logGroup, limit: Math.min(Math.max(tail, 1), 10000) };
+            if (startTime !== undefined) input.startTime = startTime;
+            if (explicitService) input.logStreamNamePrefix = service;
+            if (nextToken) input.nextToken = nextToken;
+
+            const resp = await logsClient.send(new FilterLogEventsCommand(input));
+            if (resp.nextToken) nextToken = resp.nextToken;
+
+            if (seen.size > 5000) seen.clear();
+
+            let fresh = (resp.events || []).filter((e) => {
+                const key = eventKey(e);
+                if (seen.has(key)) return false;
+                seen.add(key);
+                return true;
+            });
+            if (onlyErrors) fresh = fresh.filter((e) => isErrorLine(e.message));
+            if (firstPoll) fresh = fresh.slice(-tail);
+
+            for (const event of fresh) {
+                console.log(formatLogLine(event));
+                collected.push(String(event.message ?? ''));
+            }
+
+            firstPoll = false;
+            polls += 1;
+            if (!follow || stopped || polls >= maxPolls) break;
+            await sleep(pollIntervalMs);
+        } while (true);
+
+        if (collected.length === 0) {
+            console.log(color.cyan(`\nℹ Waiting for logs...`));
+            console.log(`  The log group "${logGroup}" exists, but no application logs have been written yet.`);
+            console.log(`  This is perfectly normal immediately after running 'apply' while the container boots.`);
+            console.log(`  Try again in a minute, or run ${color.green('npx grada-run logs -f')} to watch the stream live.\n`);
+        }
+
+        await trackSuccess('logs_streamed', {
+            projectName: resolveProjectName(options, cwd),
+            is_following: follow,
+            filtered_errors: onlyErrors,
+            tail_lines: tail
+        });
+
+        return { logs: collected, logGroup, region, service };
+    } catch (error) {
+
+        await trackFailure('logs_streamed', {
+            projectName: resolveProjectName(options, cwd),
+            error_type: error.name || 'UNKNOWN'
+        });
+
+        if (handleAuthErrorBranch(error, null, options)) {
+            return { logs: [], logGroup, region, service };
+        }
+        if (isNotFoundError(error)) {
+            printMissingLogGroupGuidance(logGroup, service, region);
+            return { logs: [], logGroup, region, service };
+        }
+
+        throw error;
+    } finally {
+        if (follow) process.removeListener('SIGINT', onSigint);
+    }
+}
+
+// Convenience alias mirroring the CLI verb.
+export const logsCommand = runLogs;
+
+export default runLogs;

package/src/commands/rollback.js

@@ -0,0 +1,323 @@
+import {
+    ECSClient,
+    DescribeServicesCommand,
+    ListTaskDefinitionsCommand,
+    DescribeTaskDefinitionCommand,
+    UpdateServiceCommand,
+} from '@aws-sdk/client-ecs';
+import color from 'picocolors';
+import { intro, outro, spinner, select, isCancel } from '@clack/prompts';
+import { trackEvent, flushTelemetry, trackSuccess, trackFailure } from '../core/telemetry.js';
+import { failCommand, failProjectNotInitialized } from '../utils/command.js';
+import { parseFlags, normalizeOptions, normalizeArgv } from '../utils/args.js';
+import { isAuthError, handleAwsAuthError, resolveClient } from '../utils/aws.js';
+import { resolveRegion, resolveProjectName, resolveCluster, resolveService, readFileSafe, resolveWorkspaceSuffix, resolveCwd, readTerraformComputeTarget } from '../utils/resolvers.js';
+import { sleep } from '../utils/system.js';
+
+export const DEFAULT_POLL_INTERVAL_MS = 5000;
+export const DEFAULT_TIMEOUT_MS = 300000;
+
+export function parseRollbackArgs(argv = []) {
+    const args = normalizeArgv(argv);
+    if (args[0] === 'rollback') args.shift();
+    const { options: parsed, rest } = parseFlags(args, {
+        string: ['cluster', 'service', 'region', 'workspace'],
+        boolean: ['skip-wait'],
+    });
+    const options = { skipWait: false, ...parsed };
+    for (const arg of rest) {
+        if (typeof arg === 'string' && !arg.startsWith('-') && options.revision === undefined) {
+            options.revision = arg;
+        }
+    }
+    return options;
+}
+
+function parseFamilyAndRevision(taskDefArn) {
+    const familyAndRev = String(taskDefArn).split('/').pop();
+    const [family, revStr] = familyAndRev.split(':');
+    return { family, revNum: Number(revStr) };
+}
+
+function formatRegisteredAt(registeredAt) {
+    if (registeredAt instanceof Date) return registeredAt.toISOString().slice(0, 10);
+    if (registeredAt) return String(registeredAt).slice(0, 10);
+    return '';
+}
+
+export async function runRollback(input = {}) {
+    const options = normalizeOptions(input);
+    let cwd;
+    let region;
+    let projectName;
+    let cluster;
+    let service;
+    try {
+        cwd = resolveCwd(options);
+        region = resolveRegion(options, cwd);
+        projectName = resolveProjectName(options, cwd);
+
+        // Namespace cluster/service for PR-preview workspaces; explicit
+        // --cluster/--service flags still win inside the resolvers.
+        const namespacedProject = `${projectName}${resolveWorkspaceSuffix(options, cwd)}`;
+        const namespacedOptions = { ...options, projectName: namespacedProject };
+        cluster = resolveCluster(namespacedOptions, cwd);
+        service = resolveService(namespacedOptions, cwd);
+    } catch {
+        return failProjectNotInitialized({ event: 'rollback_run' });
+    }
+
+    const headless = typeof options.isHeadless === 'boolean'
+        ? options.isHeadless
+        : Boolean(process.env.CI || !process.stdin.isTTY);
+
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+    const ecsClient = resolveClient(options.ecsClient, ECSClient, { region });
+
+    intro(color.bgCyan(color.black(' grada rollback ⏪ ')));
+
+    if (readTerraformComputeTarget(cwd) === 'lambda') {
+        const functionName = `${projectName}-fn`;
+        return failCommand({
+            print: () => {
+                console.log(color.red(`\n✖ Rollback targets ECS task revisions, but "${projectName}" is a Lambda project.`));
+                console.log(`  Redeploy a previous image instead: ${color.green(`aws lambda update-function-code --function-name ${functionName} --image-uri <ecr-repo>:<sha-tag> --region ${region}`)}`);
+                console.log(`  List past image tags with: ${color.green(`aws ecr describe-images --repository-name ${projectName}-repo --region ${region}`)}\n`);
+            },
+            event: 'rollback_run',
+            telemetry: { projectName, error_code: 'LAMBDA_TARGET_UNSUPPORTED' },
+            reason: 'lambda-target-unsupported',
+            resultExtra: { cluster, service, region },
+        });
+    }
+
+    const s = spinner();
+    s.start('Inspecting service and task revisions...');
+
+    try {
+        // 1. Fetch current service state.
+        const svcResp = await ecsClient.send(new DescribeServicesCommand({ cluster, services: [service] }));
+        const serviceDesc = (svcResp.services || [])[0] || null;
+
+        if (!serviceDesc || serviceDesc.status !== 'ACTIVE') {
+            s.stop(color.yellow('Service not found.'));
+            return failCommand({
+                print: () => {
+                    console.log(`\n  The ECS service ${color.cyan(service)} does not exist or is inactive.`);
+                    console.log(`  Run ${color.green('npx grada-run apply')} to provision your infrastructure.\n`);
+                },
+                event: 'rollback_run',
+                telemetry: { projectName, error_code: 'SERVICE_NOT_FOUND' },
+                reason: 'service-not-found',
+                resultExtra: { cluster, service, region },
+            });
+        }
+
+        const currentTaskDefArn = serviceDesc.taskDefinition;
+        const { family, revNum: currentRevNum } = parseFamilyAndRevision(currentTaskDefArn);
+
+        let targetTaskDefArn;
+        let targetRevisionNum;
+
+        if (options.revision !== undefined && options.revision !== null && String(options.revision).trim() !== '') {
+            // Case A: explicit revision. A request for the currently deployed
+            // revision is accepted silently; UpdateService with
+            // forceNewDeployment still redeploys it.
+            const rawRevision = String(options.revision).trim();
+            const targetInput = /^\d+$/.test(rawRevision) ? `${family}:${rawRevision}` : rawRevision;
+            let descResp;
+            try {
+                descResp = await ecsClient.send(new DescribeTaskDefinitionCommand({ taskDefinition: targetInput }));
+            } catch {
+                descResp = null;
+            }
+            if (!descResp?.taskDefinition || descResp.taskDefinition.status === 'INACTIVE') {
+                s.stop(color.red('Revision not found.'));
+                return failCommand({
+                    message: `\n✖ Task definition "${targetInput}" was not found in family "${family}".`,
+                    hint: 'List recent revisions with: aws ecs list-task-definitions --family-prefix ' + family + ` --region ${region}\n`,
+                    event: 'rollback_run',
+                    telemetry: { projectName, error_code: 'REVISION_NOT_FOUND' },
+                    reason: 'revision-not-found',
+                    resultExtra: { cluster, service, region },
+                });
+            }
+            targetTaskDefArn = descResp.taskDefinition.taskDefinitionArn;
+            targetRevisionNum = String(descResp.taskDefinition.revision);
+            s.stop(`Resolved revision ${targetRevisionNum}.`);
+        } else {
+            // Case B: discover eligible older revisions.
+            const listResp = await ecsClient.send(new ListTaskDefinitionsCommand({
+                familyPrefix: family,
+                status: 'ACTIVE',
+                sort: 'DESC',
+                maxResults: 10,
+            }));
+            const eligibleArns = (listResp.taskDefinitionArns || []).filter(
+                (arn) => Number(arn.split(':').pop()) < currentRevNum
+            );
+
+            if (eligibleArns.length === 0) {
+                s.stop(color.yellow('No previous revisions.'));
+                return failCommand({
+                    message: `\n⚠ No previous task definition revisions found for family ${family}. Cannot roll back.\n`,
+                    tone: 'yellow',
+                    event: 'rollback_run',
+                    telemetry: { projectName, error_code: 'NO_PRIOR_REVISIONS' },
+                    reason: 'no-prior-revisions',
+                    resultExtra: { cluster, service, region },
+                });
+            }
+
+            if (headless) {
+                targetTaskDefArn = eligibleArns[0];
+                targetRevisionNum = targetTaskDefArn.split(':').pop();
+                s.stop(`Selected previous revision ${targetRevisionNum}.`);
+            } else {
+                const candidates = eligibleArns.slice(0, 5);
+                const settled = await Promise.allSettled(
+                    candidates.map((arn) => ecsClient.send(new DescribeTaskDefinitionCommand({ taskDefinition: arn })))
+                );
+                const promptOptions = candidates.map((arn, index) => {
+                    const result = settled[index];
+                    if (result.status === 'fulfilled') {
+                        const taskDef = result.value?.taskDefinition || {};
+                        const rev = taskDef.revision ?? arn.split(':').pop();
+                        const rawImage = taskDef.containerDefinitions?.[0]?.image || 'unknown';
+                        return {
+                            value: arn,
+                            label: `Revision ${rev} — ${rawImage.split('/').pop()}`,
+                            hint: formatRegisteredAt(taskDef.registeredAt),
+                        };
+                    }
+                    return {
+                        value: arn,
+                        label: `Revision ${arn.split(':').pop()} — unknown`,
+                        hint: '',
+                    };
+                });
+                s.stop('Found previous revisions.');
+                const selectedArn = await select({
+                    message: 'Select a task definition revision to roll back to:',
+                    options: promptOptions,
+                });
+                if (isCancel(selectedArn)) {
+                    outro(color.yellow('Rollback cancelled.'));
+                    return { ok: false, reason: 'cancelled', cluster, service, region };
+                }
+                targetTaskDefArn = selectedArn;
+                targetRevisionNum = targetTaskDefArn.split(':').pop();
+            }
+        }
+
+        // 2. Trigger the rollback.
+        s.start(`Rolling back ${service} to revision ${targetRevisionNum}...`);
+        await ecsClient.send(new UpdateServiceCommand({
+            cluster,
+            service,
+            taskDefinition: targetTaskDefArn,
+            forceNewDeployment: true,
+        }));
+
+        if (options.skipWait === true) {
+            s.stop(`Rollback to revision ${targetRevisionNum} triggered.`);
+            await trackSuccess('rollback_run', { projectName, targetRevision: String(targetRevisionNum), skipWait: true });
+            outro(color.green(`Rollback to revision ${targetRevisionNum} initiated! 🚀`));
+            return { ok: true, targetTaskDefArn, targetRevision: targetRevisionNum, cluster, service, region };
+        }
+
+        // 3. Monitor the deployment until it stabilizes or times out,
+        // with live spinner updates on every non-terminal tick.
+        const startTime = Date.now();
+        const deadline = startTime + timeoutMs;
+        while (true) {
+            const pollResp = await ecsClient.send(new DescribeServicesCommand({ cluster, services: [service] }));
+            const svc = (pollResp.services || [])[0] || null;
+            const primary = svc?.deployments?.find(
+                (d) => d.status === 'PRIMARY' && d.taskDefinition === targetTaskDefArn
+            );
+
+            if (primary && (primary.rolloutState === 'COMPLETED'
+                || (primary.runningCount === primary.desiredCount
+                    && primary.desiredCount > 0
+                    && (svc.deployments || []).length === 1))) {
+                s.stop(color.green(`Rolled back to revision ${targetRevisionNum}.`));
+                await trackSuccess('rollback_run', { projectName, targetRevision: String(targetRevisionNum) });
+                outro(color.green(`Service successfully rolled back to revision ${targetRevisionNum}! 🚀`));
+                return { ok: true, targetTaskDefArn, targetRevision: targetRevisionNum, cluster, service, region };
+            }
+
+            if (primary?.rolloutState === 'FAILED') {
+                s.stop(color.red('❌ Rollback deployment failed.'));
+                return failCommand({
+                    print: () => {
+                        console.log(color.red('\n✖ The rollback deployment failed to stabilize.'));
+                        console.log(`  Check service health with ${color.green('npx grada-run status')} and recent output with ${color.green('npx grada-run logs')}.\n`);
+                    },
+                    event: 'rollback_run',
+                    telemetry: { projectName, error_code: 'ROLLOUT_FAILED', targetRevision: String(targetRevisionNum) },
+                    reason: 'rollout-failed',
+                    resultExtra: { cluster, service, region },
+                });
+            }
+
+            const elapsedSec = Math.floor((Date.now() - startTime) / 1000);
+            if (!primary) {
+                s.message(`Rolling back ${service} to revision ${targetRevisionNum}... [${elapsedSec}s] (registering deployment...)`);
+            } else {
+                const runningCount = primary.runningCount ?? 0;
+                const desiredCount = primary.desiredCount ?? 0;
+                const pendingCount = primary.pendingCount ?? 0;
+                const failedTasks = primary.failedTasks ?? 0;
+                if (failedTasks > 0) {
+                    s.message(`Rolling back ${service} to revision ${targetRevisionNum}... [${elapsedSec}s] (${runningCount}/${desiredCount} running, ${pendingCount} pending, ${failedTasks} failed ⚠️ — container crashing)`);
+                } else if (runningCount >= desiredCount && desiredCount > 0 && pendingCount === 0) {
+                    s.message(`Rolling back ${service} to revision ${targetRevisionNum}... [${elapsedSec}s] (${runningCount}/${desiredCount} running — draining previous tasks)`);
+                } else {
+                    s.message(`Rolling back ${service} to revision ${targetRevisionNum}... [${elapsedSec}s] (${runningCount}/${desiredCount} running, ${pendingCount} pending)`);
+                }
+            }
+
+            if (Date.now() >= deadline) {
+                s.stop(color.yellow('⚠ Rollback timed out waiting for ECS stabilization.'));
+                return failCommand({
+                    print: () => {
+                        console.log(color.yellow('\n⚠ The rollback is still in progress.'));
+                        console.log(`  Check progress with ${color.green('npx grada-run status')}.\n`);
+                    },
+                    event: 'rollback_run',
+                    telemetry: { projectName, error_code: 'ROLLOUT_TIMEOUT', targetRevision: String(targetRevisionNum) },
+                    reason: 'rollout-timeout',
+                    resultExtra: { cluster, service, region },
+                });
+            }
+
+            await sleep(pollIntervalMs);
+        }
+    } catch (error) {
+        if (isAuthError(error)) {
+            await trackFailure('rollback_run', { projectName, error_code: 'AUTH_EXPIRED' });
+            handleAwsAuthError(error, s, options);
+            return { ok: false, reason: 'auth-error', cluster, service, region };
+        }
+        await trackFailure('rollback_run', {
+            projectName,
+            error_code: error?.name || 'UNKNOWN',
+            error_message: error?.message,
+        });
+        s.stop(color.red('❌ Rollback failed.'));
+        return failCommand({
+            message: `✖ ${error?.message || error}`,
+            hint: 'Check your AWS credentials and region, then try again.',
+            reason: 'error',
+            resultExtra: { cluster, service, region },
+        });
+    }
+}
+
+// Convenience alias mirroring the CLI verb.
+export const rollbackCommand = runRollback;
+
+export default runRollback;