grada-run 0.0.1 → 0.32.0

package/src/commands/drift.js

@@ -0,0 +1,243 @@
+import fsSync from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import color from 'picocolors';
+import { intro, outro, spinner } from '@clack/prompts';
+import { trackSuccess, trackFailure } from '../core/telemetry.js';
+import { failCommand, failProjectNotInitialized } from '../utils/command.js';
+import { parseFlags, normalizeOptions, normalizeArgv } from '../utils/args.js';
+import { resolveRegion, resolveProjectName, resolveCwd, readFileSafe } from '../utils/resolvers.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const DRIFT_TEMPLATE_PATH = path.join(__dirname, '../../templates/github/drift.yml');
+
+export const DRIFT_WORKFLOW_FILE = path.join('.github', 'workflows', 'drift.yml');
+export const MAX_SUMMARY_LINES = 60;
+
+export function parseDriftArgs(argv = []) {
+    const args = normalizeArgv(argv);
+    if (args[0] === 'drift') args.shift();
+    const { options, rest } = parseFlags(args, {
+        string: ['region', 'project-name'],
+        boolean: ['setup', 'force', 'headless'],
+    });
+    const positionals = rest.filter((arg) => typeof arg === 'string' && !arg.startsWith('-'));
+    // `drift init` is an alias for `drift --setup`.
+    if (positionals.includes('init') || positionals.includes('setup')) options.setup = true;
+    const others = positionals.filter((positional) => positional !== 'init' && positional !== 'setup');
+    if (others.length > 0) options.unexpectedPositionals = others;
+    return options;
+}
+
+// The OIDC role ARN the deploy workflow assumes — drift CI reuses it so no
+// extra secret is needed. Null when the anchor cannot be found.
+export function extractRoleArn(deployYmlContent) {
+    const match = /role-to-assume:\s*([^\s#]+)/.exec(String(deployYmlContent ?? ''));
+    return match ? match[1] : null;
+}
+
+// Renders `templates/github/drift.yml` into the project. Shared by
+// `drift --setup` and `--setup-ci-drift`; never exits, never tracks.
+export function scaffoldDriftWorkflow(cwd = process.cwd(), { region, roleArn, force = false } = {}) {
+    const template = fsSync.readFileSync(DRIFT_TEMPLATE_PATH, 'utf8');
+    const rendered = template
+        .replaceAll('{{REGION}}', region)
+        .replaceAll('{{ROLE_ARN}}', roleArn);
+    const targetPath = path.join(cwd, DRIFT_WORKFLOW_FILE);
+    if (fsSync.existsSync(targetPath) && force !== true && force !== 'true') {
+        return { ok: false, reason: 'exists', path: targetPath };
+    }
+    fsSync.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fsSync.writeFileSync(targetPath, rendered, 'utf8');
+    return { ok: true, path: targetPath };
+}
+
+// Condenses `terraform plan` output to the resource-change lines plus the
+// `Plan:` summary, capped so Issue bodies and terminals stay readable.
+export function extractPlanSummary(output) {
+    const lines = String(output ?? '').split('\n');
+    const picked = lines.filter((line) => /^\s*[~+-] /.test(line) || /^# \S/.test(line) || /^Plan:/.test(line));
+    const trimmed = picked.slice(0, MAX_SUMMARY_LINES);
+    if (picked.length > trimmed.length) {
+        trimmed.push(`... (${picked.length - trimmed.length} more lines)`);
+    }
+    return trimmed.join('\n');
+}
+
+function tailLines(output, count = 15) {
+    return String(output ?? '').split('\n').slice(-count).join('\n').trim();
+}
+
+export async function runDrift(input = {}) {
+    const options = normalizeOptions(input);
+    let cwd;
+    let region;
+    let projectName;
+    try {
+        cwd = resolveCwd(options);
+        region = resolveRegion(options, cwd);
+        projectName = resolveProjectName(options, cwd);
+    } catch {
+        return failProjectNotInitialized({ event: 'drift_run' });
+    }
+    const setup = options.setup === true || options.setup === 'true';
+    const force = options.force === true || options.force === 'true';
+
+    intro(color.bgCyan(color.black(' grada drift 🔍 ')));
+
+    if (Array.isArray(options.unexpectedPositionals) && options.unexpectedPositionals.length > 0) {
+        return failCommand({
+            message: `\n✖ Unexpected argument "${options.unexpectedPositionals[0]}". Run "grada drift" to check, or "grada drift --setup" to scaffold scheduled checks.\n`,
+            event: 'drift_run',
+            telemetry: { projectName },
+            errorCode: 'UNEXPECTED_POSITIONAL_ARGS',
+            reason: 'unexpected-positional-args',
+            resultExtra: { region },
+        });
+    }
+
+    if (setup) {
+        const deployYml = readFileSafe(path.join(cwd, '.github', 'workflows', 'deploy.yml'));
+        if (!deployYml) {
+            return failCommand({
+                message: `\n✖ Workflow not found at ${color.cyan('.github/workflows/deploy.yml')}. Run ${color.green('npx grada-run')} first.\n`,
+                event: 'drift_run',
+                telemetry: { projectName },
+                errorCode: 'WORKFLOW_NOT_FOUND',
+                reason: 'workflow-not-found',
+                resultExtra: { region },
+            });
+        }
+        const roleArn = extractRoleArn(deployYml);
+        if (!roleArn) {
+            return failCommand({
+                message: '\n✖ Could not find the OIDC role ARN (role-to-assume) in .github/workflows/deploy.yml.\n',
+                event: 'drift_run',
+                telemetry: { projectName },
+                errorCode: 'ROLE_ARN_NOT_FOUND',
+                reason: 'role-arn-not-found',
+                resultExtra: { region },
+            });
+        }
+        const scaffolded = scaffoldDriftWorkflow(cwd, { region, roleArn, force });
+        if (!scaffolded.ok) {
+            return failCommand({
+                message: `\n⚠ ${DRIFT_WORKFLOW_FILE} already exists. Pass --force to overwrite.\n`,
+                tone: 'yellow',
+                event: 'drift_run',
+                telemetry: { projectName, error_code: 'DRIFT_WORKFLOW_EXISTS' },
+                reason: 'drift-workflow-exists',
+                resultExtra: { projectName, region },
+                exitCode: null,
+            });
+        }
+        console.log(color.green(`\n✅ Created ${DRIFT_WORKFLOW_FILE} (daily 06:00 UTC drift check).`));
+        console.log(color.dim('  Drift opens (or updates) a GitHub Issue labeled iac-drift; set SLACK_WEBHOOK_URL for Slack alerts.\n'));
+        await trackSuccess('drift_run', { projectName, action: 'setup' });
+        outro(color.green('Done.'));
+        return { ok: true, action: 'setup', projectName, region, file: DRIFT_WORKFLOW_FILE };
+    }
+
+    const tfDir = path.join(cwd, 'terraform');
+    if (!fsSync.existsSync(path.join(tfDir, 'main.tf'))) {
+        return failCommand({
+            message: '\n✖ No terraform/main.tf found. Run "grada" first before checking drift.\n',
+            event: 'drift_run',
+            telemetry: { projectName, error_code: 'TERRAFORM_NOT_INITIALIZED' },
+            reason: 'terraform-not-initialized',
+            resultExtra: { region },
+        });
+    }
+
+    const runSync = options.spawnSyncImpl || spawnSync;
+    const s = spinner();
+    s.start('Running terraform plan...');
+
+    try {
+        const initResult = runSync('terraform', ['init', '-input=false'], { cwd: tfDir, encoding: 'utf8' });
+        if (initResult?.error?.code === 'ENOENT') {
+            s.stop(color.red('Terraform not found.'));
+            return failCommand({
+                message: '\n✖ Terraform is not installed.',
+                hint: '  Please run "npx grada-run doctor" to check your environment.\n',
+                event: 'drift_run',
+                telemetry: { projectName },
+                errorCode: 'TERRAFORM_NOT_INSTALLED',
+                reason: 'terraform-not-installed',
+                resultExtra: { region },
+            });
+        }
+        if (initResult?.status !== 0) {
+            s.stop(color.red('Terraform init failed.'));
+            return failCommand({
+                message: `\n✖ terraform init failed:\n${tailLines(initResult?.stderr || initResult?.stdout)}\n`,
+                event: 'drift_run',
+                telemetry: { projectName },
+                errorCode: 'TERRAFORM_INIT_FAILED',
+                reason: 'terraform-init-failed',
+                resultExtra: { region },
+            });
+        }
+
+        const planResult = runSync('terraform', ['plan', '-detailed-exitcode', '-no-color'], {
+            cwd: tfDir,
+            encoding: 'utf8',
+            maxBuffer: 32 * 1024 * 1024,
+        });
+        const status = planResult?.status;
+        if (status === 0) {
+            s.stop(color.green('No drift.'));
+            console.log(color.green('\n✅ No infrastructure drift detected.\n'));
+            await trackSuccess('drift_run', { projectName, action: 'check', drift: false });
+            outro(color.green('Done.'));
+            return { ok: true, action: 'check', drift: false, region };
+        }
+        if (status === 2) {
+            s.stop(color.yellow('Drift detected.'));
+            const summary = extractPlanSummary(planResult?.stdout);
+            return failCommand({
+                print: () => {
+                    console.log(color.yellow('\n⚠ Infrastructure drift detected!'));
+                    if (summary) console.log(color.dim(`\n${summary}\n`));
+                    console.log(`  Reconcile with ${color.green('npx grada-run apply')}, or adopt the live resource with ${color.green('terraform import')}.\n`);
+                },
+                event: 'drift_run',
+                telemetry: { projectName, action: 'check', drift: true },
+                errorCode: 'DRIFT_DETECTED',
+                reason: 'drift-detected',
+                resultExtra: { region },
+                exitCode: 2,
+            });
+        }
+        s.stop(color.red('Terraform plan failed.'));
+        return failCommand({
+            message: `\n✖ terraform plan failed:\n${tailLines(planResult?.stderr || planResult?.stdout)}\n`,
+            event: 'drift_run',
+            telemetry: { projectName, action: 'check' },
+            errorCode: 'TERRAFORM_PLAN_FAILED',
+            reason: 'terraform-plan-failed',
+            resultExtra: { region },
+        });
+    } catch (error) {
+        await trackFailure('drift_run', {
+            projectName,
+            action: 'check',
+            error_code: error?.name || 'UNKNOWN',
+            error_message: error?.message,
+        });
+        try { s.stop(color.red('❌ Drift check failed.')); } catch { /* spinner already stopped */ }
+        return failCommand({
+            message: `✖ ${error?.message || error}`,
+            hint: 'Check your AWS credentials and region, then try again.',
+            reason: 'error',
+            resultExtra: { region },
+        });
+    }
+}
+
+export const driftCommand = runDrift;
+
+export default runDrift;

package/src/commands/eject.js

@@ -0,0 +1,127 @@
+import fs from 'fs';
+import path from 'path';
+import { intro, outro, confirm, spinner, cancel } from '@clack/prompts';
+import color from 'picocolors';
+import { trackEvent, flushTelemetry } from '../core/telemetry.js';
+
+// Matches the `# <brand> generated infrastructure...` header line in
+// either brand variant (Lambda targets append a suffix in parentheses).
+const GENERATED_HEADER_REGEX = /# (?:grada|deploy-stack) generated infrastructure[^\n]*\n?/g;
+
+// Matches the one-line `# <brand> addon: ...` header in either variant.
+const ADDON_HEADER_REGEX = /^# (?:grada|deploy-stack) addon:[^\n]*\n?/gm;
+
+// Matches the `# Generated by \`<brand> add ...` sentence through its
+// `... overwrites this file.` tail (it wraps across lines), in either
+// brand variant. Billing docs below the header are left untouched.
+const GENERATED_BY_REGEX = /^# Generated by `?(?:grada|deploy-stack) add\b[^\n]*\n(?:^#[^\n]*\n)*?^#[^\n]*overwrites this file\.[^\n]*\n?/gm;
+
+// Matches a `default_tags` block pinning `ManagedBy` to either brand.
+const MANAGED_BY_TAGS_REGEX = /[ \t]*default_tags\s*\{\s*tags\s*=\s*\{\s*ManagedBy\s*=\s*"(?:grada|deploy-stack)"\s*\}\s*\}\n?/g;
+
+// Matches the `.bak` gitignore stanza in either brand variant.
+const BACKUPS_GITIGNORE_REGEX = /\n# (?:grada|deploy-stack) backups\n\*\.bak\.\*\n/g;
+
+// Strips tool metadata from Terraform source: the generated header,
+// addon headers, and ManagedBy tag blocks. Pure and unit-tested.
+export function stripTerraformMetadata(content) {
+    return String(content ?? '')
+        .replace(GENERATED_HEADER_REGEX, '')
+        .replace(ADDON_HEADER_REGEX, '')
+        .replace(GENERATED_BY_REGEX, '')
+        .replace(MANAGED_BY_TAGS_REGEX, '');
+}
+
+// Strips the `.bak` stanza from gitignore content. Pure and unit-tested.
+export function stripGitignoreMetadata(content) {
+    return String(content ?? '').replace(BACKUPS_GITIGNORE_REGEX, '\n');
+}
+
+function collectTerraformFiles(dir, out = []) {
+    if (!fs.existsSync(dir)) return out;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) collectTerraformFiles(fullPath, out);
+        else if (entry.isFile() && entry.name.endsWith('.tf')) out.push(fullPath);
+    }
+    return out;
+}
+
+export async function ejectStack() {
+    intro(color.bgRed(color.white(' grada eject ⏏️  ')));
+
+    console.log(color.yellow('This will permanently decouple your infrastructure from the grada CLI.'));
+    console.log(color.gray('It removes all ManagedBy tags and tool-specific metadata from your local files.'));
+    console.log(color.gray('Your infrastructure will remain fully operational as raw, standalone Terraform.'));
+
+    const shouldEject = await confirm({
+        message: 'Are you sure you want to eject? (This cannot be undone)',
+        initialValue: false,
+    });
+
+    if (!shouldEject || typeof shouldEject === 'symbol') {
+        cancel('Eject cancelled. You are still managed by grada.');
+        process.exit(0);
+    }
+
+    const s = spinner();
+    s.start('Ejecting grada metadata...');
+
+    const targetDir = process.cwd();
+    const tfDir = path.join(targetDir, 'terraform');
+    const gitignorePath = path.join(targetDir, '.gitignore');
+
+    // 1. Clean every Terraform file (main.tf headers and tag blocks,
+    // addon headers in either brand variant).
+    for (const tfPath of collectTerraformFiles(tfDir)) {
+        const content = fs.readFileSync(tfPath, 'utf8');
+        const cleaned = stripTerraformMetadata(content);
+        if (cleaned !== content) {
+            fs.writeFileSync(tfPath, cleaned.trim() + '\n');
+        }
+    }
+
+    // 2. Clean up .gitignore
+    if (fs.existsSync(gitignorePath)) {
+        let gitignore = fs.readFileSync(gitignorePath, 'utf8');
+        // Remove the exact block we injected in backup.js
+        gitignore = stripGitignoreMetadata(gitignore);
+        fs.writeFileSync(gitignorePath, gitignore.trim() + '\n');
+    }
+
+    // 3. Purge all local `.bak` files to leave a pristine directory
+    const cleanBackups = (dir) => {
+        if (!fs.existsSync(dir)) return;
+        const files = fs.readdirSync(dir);
+        for (const file of files) {
+            const fullPath = path.join(dir, file);
+            if (file.includes('.bak.')) {
+                fs.rmSync(fullPath, { recursive: true, force: true });
+            } else if (fs.statSync(fullPath).isDirectory() && file !== 'node_modules' && file !== '.git') {
+                cleanBackups(fullPath); // Recursively check subdirectories like .github/workflows
+            }
+        }
+    };
+
+    cleanBackups(targetDir);
+
+    s.stop('Ejection complete.');
+
+    const actualProjectName = path.basename(process.cwd());
+    trackEvent('project_ejected', {
+        projectName: actualProjectName
+    });
+    await flushTelemetry();
+
+    outro(`
+    ${color.green('✅ Successfully ejected from grada!')}
+    
+    Your Terraform and CI/CD files are now 100% vanilla. 
+    
+    ${color.blue('Next Step:')}
+    Run ${color.cyan('terraform apply')} inside your terraform/ folder. 
+    AWS will sync your state and automatically remove the 'ManagedBy' tags from your live cloud resources.
+
+    ${color.magenta('Godspeed! You are now the sole owner of your infrastructure.')}
+    `);
+}

package/src/commands/exec.js

@@ -0,0 +1,222 @@
+import { ECSClient, ListTasksCommand, DescribeTasksCommand } from '@aws-sdk/client-ecs';
+import { spawn } from 'child_process';
+import color from 'picocolors';
+import { intro, outro, spinner } from '@clack/prompts';
+import { trackEvent, flushTelemetry, trackSuccess, trackFailure } from '../core/telemetry.js';
+import { hasAwsCli, AWS_CLI_INSTALL_URL, handleAuthErrorBranch, resolveClient } from '../utils/aws.js';
+import { failCommand, failProjectNotInitialized } from '../utils/command.js';
+import { parseFlags, normalizeOptions, normalizeArgv } from '../utils/args.js';
+import { resolveRegion, resolveProjectName, resolveCluster, resolveService, resolveCwd, readTerraformComputeTarget } from '../utils/resolvers.js';
+import {
+    hasSessionManagerPlugin,
+    resolveContainer,
+    printAwsCliGuidance,
+    printSessionManagerGuidance,
+    printNoTasksGuidance,
+} from '../utils/ecs.js';
+
+// Re-exported from the shared ECS module for backward compatibility.
+export {
+    SESSION_MANAGER_PLUGIN_URL,
+    hasSessionManagerPlugin,
+    resolveContainer,
+} from '../utils/ecs.js';
+
+export const DEFAULT_SHELL = '/bin/sh';
+
+export function resolveShellCommand(options = {}) {
+    if (typeof options.command === 'string' && options.command.trim()) return options.command.trim();
+    if (typeof options.shell === 'string' && options.shell.trim()) return options.shell.trim();
+    return DEFAULT_SHELL;
+}
+
+export function parseExecArgs(argv = []) {
+    const args = normalizeArgv(argv);
+    if (args[0] === 'exec') args.shift();
+    const { options, rest } = parseFlags(args, {
+        string: ['cluster', 'service', 'container', 'command', 'region'],
+    });
+    const positionals = rest.filter((arg) => typeof arg === 'string' && !arg.startsWith('-'));
+    if (positionals.length > 0 && !options.service) options.service = positionals[0];
+    return options;
+}
+
+export function buildExecuteCommandArgs({ cluster, taskArn, container, command = DEFAULT_SHELL, region }) {
+    const args = [
+        'ecs', 'execute-command',
+        '--cluster', cluster,
+        '--task', taskArn,
+        '--container', container,
+        '--interactive',
+        '--command', command,
+    ];
+    if (region) args.push('--region', region);
+    return args;
+}
+
+function pickContainerName(task, fallback) {
+    const containers = task?.containers || [];
+    if (containers.length === 0) return fallback;
+    const exact = containers.find((c) => c.name === fallback);
+    if (exact) return exact.name;
+    const running = containers.find((c) => c.lastStatus === 'RUNNING');
+    if (running?.name) return running.name;
+    if (containers[0]?.name) return containers[0].name;
+    return fallback;
+}
+
+export async function findRunningTask(ecsClient, { cluster, service }) {
+    const listResp = await ecsClient.send(
+        new ListTasksCommand({ cluster, serviceName: service, desiredStatus: 'RUNNING', maxResults: 10 })
+    );
+    const taskArns = listResp.taskArns || [];
+    if (taskArns.length === 0) return null;
+    const descResp = await ecsClient.send(
+        new DescribeTasksCommand({ cluster, tasks: taskArns.slice(0, 1) })
+    );
+    const tasks = descResp.tasks || [];
+    if (tasks.length === 0) return { taskArn: taskArns[0], containerName: null };
+    return { taskArn: tasks[0].taskArn || taskArns[0], containerName: tasks[0].containers?.[0]?.name || null, task: tasks[0] };
+}
+
+export async function runExec(input = {}) {
+    const options = normalizeOptions(input);
+    let cwd;
+    let region;
+    let projectName;
+    let cluster;
+    let service;
+    let expectedContainer;
+    try {
+        cwd = resolveCwd(options);
+        region = resolveRegion(options, cwd);
+        projectName = resolveProjectName(options, cwd);
+        cluster = resolveCluster(options, cwd);
+        service = resolveService(options, cwd);
+        expectedContainer = resolveContainer(options, cwd);
+    } catch {
+        return failProjectNotInitialized({ event: 'exec_run' });
+    }
+    const shellCommand = resolveShellCommand(options);
+
+    const ecsClient = resolveClient(options.ecsClient, ECSClient, { region });
+
+    const spawnImpl = options.spawnImpl || spawn;
+    const awsCliPresent = options.hasAwsCli ?? hasAwsCli({ spawnSyncImpl: options.spawnSyncImpl });
+    const ssmPluginPresent = options.hasSsmPlugin ?? hasSessionManagerPlugin({ spawnSyncImpl: options.spawnSyncImpl });
+
+    intro(color.bgCyan(color.black(' grada exec 🐚 ')));
+
+    if (readTerraformComputeTarget(cwd) === 'lambda') {
+        return failCommand({
+            print: () => {
+                console.log(color.red(`\n✖ Exec opens a shell in a running ECS container, but "${projectName}" is a Lambda project.`));
+                console.log(`  Lambda functions have no shell to attach to — inspect recent output with ${color.green('npx grada-run logs')} instead.\n`);
+            },
+            event: 'exec_run',
+            telemetry: { projectName, error_code: 'LAMBDA_TARGET_UNSUPPORTED' },
+            reason: 'lambda-target-unsupported',
+            resultExtra: { cluster, service, region },
+        });
+    }
+
+    if (!awsCliPresent) {
+        return failCommand({
+            print: printAwsCliGuidance,
+            event: 'exec_run',
+            telemetry: { projectName, error_code: 'AWS_CLI_MISSING' },
+            reason: 'aws-cli-missing',
+            resultExtra: { cluster, service, region },
+        });
+    }
+
+    if (!ssmPluginPresent) {
+        return failCommand({
+            print: printSessionManagerGuidance,
+            event: 'exec_run',
+            telemetry: { projectName, error_code: 'SSM_PLUGIN_MISSING' },
+            reason: 'ssm-plugin-missing',
+            resultExtra: { cluster, service, region },
+        });
+    }
+
+    const s = spinner();
+    s.start('Finding a running container...');
+
+    try {
+        const found = await findRunningTask(ecsClient, { cluster, service });
+
+        if (!found) {
+            s.stop(color.yellow('No running tasks.'));
+            return failCommand({
+                print: () => printNoTasksGuidance(service, cluster),
+                event: 'exec_run',
+                telemetry: { projectName, error_code: 'NO_RUNNING_TASKS' },
+                reason: 'no-running-tasks',
+                resultExtra: { cluster, service, region },
+            });
+        }
+
+        const container = found.containerName || expectedContainer;
+        const taskArn = found.taskArn;
+        // Prefer the exact expected container name when the task actually runs it.
+        const resolvedContainer = found.task ? pickContainerName(found.task, expectedContainer) : container;
+
+        s.stop(color.green('Container found. Connecting...'));
+        console.log(`  ${color.dim('Cluster:')} ${color.cyan(cluster)}`);
+        console.log(`  ${color.dim('Task:')} ${color.dim(taskArn)}`);
+        console.log(`  ${color.dim('Container:')} ${color.yellow(resolvedContainer)}`);
+        console.log(color.dim(`  Opening ${shellCommand} — type 'exit' to leave.\n`));
+
+        const cliArgs = buildExecuteCommandArgs({
+            cluster,
+            taskArn,
+            container: resolvedContainer,
+            command: shellCommand,
+            region,
+        });
+
+        await trackSuccess('exec_run', { projectName });
+
+        await new Promise((resolve) => {
+            const child = spawnImpl('aws', cliArgs, { stdio: 'inherit' });
+            child.on('error', (err) => {
+                console.log(color.red(`\n✖ Failed to start AWS CLI: ${err?.message || err}`));
+                console.log(color.dim(`Install help: ${AWS_CLI_INSTALL_URL}`));
+                resolve({ code: 1 });
+            });
+            child.on('close', (code) => resolve({ code: code ?? 0 }));
+        }).then(async ({ code }) => {
+            if (code === 0) {
+                outro(color.green('Shell session ended. 👋'));
+            } else {
+                console.log(color.yellow(`\nShell exited with code ${code}.`));
+                console.log(color.dim(`If the connection failed, ensure ECS Exec is enabled (re-run ${color.green('npx grada-run apply')}) and the Session Manager plugin is installed.`));
+                outro(color.yellow('Exec finished.'));
+            }
+        });
+
+        return { ok: true, cluster, service, taskArn, container: resolvedContainer, region };
+    } catch (error) {
+        await trackFailure('exec_run', {
+            projectName,
+            error_code: error?.name || 'UNKNOWN',
+            error_message: error?.message,
+        });
+        if (handleAuthErrorBranch(error, s, options)) {
+            return { ok: false, reason: 'error', cluster, service, region };
+        }
+        s.stop(color.red('❌ Exec 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 execCommand = runExec;
+
+export default runExec;