grada-run 0.0.2 → 0.32.0

package/src/utils/addons.js

@@ -0,0 +1,126 @@
+// Single source of truth for `grada add` capabilities.
+// Imported by both src/commands/add.js and src/utils/visualizer.js.
+// Keep this module dependency-free so neither importer creates a cycle.
+export const ADDON_REGISTRY = {
+    'storage:s3': {
+        file: 's3.tf',
+        template: 's3.tf',
+        label: 'S3 + CloudFront OAC',
+        cost: {
+            model: 'usage-based',
+            monthlyFixed: 0,
+            summary: '$0/mo fixed baseline; billed per GB stored ($0.023/GB-mo), S3 PUT/GET requests, and CloudFront egress',
+        },
+    },
+    'db:dynamodb': {
+        file: 'dynamodb.tf',
+        template: 'dynamodb.tf',
+        label: 'DynamoDB (On-Demand + PITR)',
+        cost: {
+            model: 'usage-based',
+            monthlyFixed: 0,
+            summary: '$0/mo fixed instance baseline (VPC Gateway Endpoint is free); billed per read/write request, table storage ($0.25/GB-mo), and PITR continuous backups ($0.20/GB-mo once data is written)',
+        },
+    },
+    'db:redis': {
+        file: 'redis.tf',
+        template: 'redis.tf',
+        label: 'ElastiCache Valkey 8.0',
+        cost: {
+            model: 'fixed-baseline',
+            monthlyFixed: 9.49,
+            summary: '~$9.49/mo fixed baseline ($0.013/hr Valkey 8.0 cache.t4g.micro in us-east-2); $0 intra-AZ VPC transfer',
+        },
+    },
+    'queue:sqs': {
+        file: 'sqs.tf',
+        template: 'sqs.tf',
+        label: 'SQS + DLQ',
+        cost: {
+            model: 'usage-based',
+            monthlyFixed: 0,
+            summary: '$0/mo fixed baseline; first 1M requests/mo free, then $0.40 per million requests',
+        },
+    },
+    'ai:bedrock': {
+        file: 'bedrock.tf',
+        template: 'bedrock.tf',
+        label: 'Bedrock Runtime IAM',
+        cost: {
+            model: 'usage-based',
+            monthlyFixed: 0,
+            summary: '$0/mo fixed baseline; billed per 1K input/output tokens on InvokeModel calls',
+        },
+    },
+    'email:ses': {
+        file: 'ses.tf',
+        template: 'ses.tf',
+        label: 'Amazon SES (Transactional Email & DKIM)',
+        cost: {
+            model: 'usage-based',
+            monthlyFixed: 0,
+            summary: '$0/mo fixed baseline; $0.10 per 1,000 emails sent',
+        },
+    },
+    'cron': {
+        file: 'cron.tf',
+        template: 'cron.tf',
+        label: 'EventBridge Scheduler (Cron)',
+        cost: {
+            model: 'usage-based',
+            monthlyFixed: 0,
+            summary: '$0/mo fixed baseline (first 14M EventBridge Scheduler invocations/mo free); billed only for Fargate seconds while the cron task runs',
+        },
+    },
+};
+
+// Container environment variables injected into the ECS task definitions
+// per capability. Values are static HCL expressions or `(ctx) => string`
+// resolvers for dynamic values (model IDs, SES sender/region). Lone
+// "${...}" values render as bare HCL references via renderEnvValue in
+// src/commands/add.js; literals and multi-part interpolations stay quoted.
+export const ADDON_ENV_VARS = {
+    'storage:s3': [
+        { name: 'S3_BUCKET_NAME', value: '${aws_s3_bucket.storage.id}' },
+        { name: 'S3_CDN_URL', value: 'https://${aws_cloudfront_distribution.storage_cdn.domain_name}' },
+    ],
+    'db:dynamodb': [
+        { name: 'DYNAMODB_TABLE_NAME', value: '${aws_dynamodb_table.main.name}' },
+    ],
+    'db:redis': [
+        { name: 'REDIS_URL', value: 'redis://${aws_elasticache_replication_group.redis.primary_endpoint_address}:${aws_elasticache_replication_group.redis.port}' },
+    ],
+    'queue:sqs': [
+        { name: 'SQS_QUEUE_URL', value: '${aws_sqs_queue.main.id}' },
+        { name: 'SQS_DLQ_URL', value: '${aws_sqs_queue.dlq.id}' },
+    ],
+    'ai:bedrock': [
+        { name: 'BEDROCK_MODEL_ID', value: (ctx) => ctx.model },
+    ],
+    'email:ses': [
+        { name: 'SES_FROM_EMAIL', value: (ctx) => ctx.sesFromEmail },
+        { name: 'SES_REGION', value: (ctx) => ctx.region },
+    ],
+};
+
+// Keys whose values are replaced in place on reruns (Day-2 switching)
+// instead of the default skip-if-present behavior.
+export const ADDON_UPSERT_KEYS = {
+    'ai:bedrock': ['BEDROCK_MODEL_ID'],
+    'db:redis': ['REDIS_URL'],
+    'email:ses': ['SES_FROM_EMAIL', 'SES_REGION'],
+};
+
+// Resolves `{ name, value }` entries for `capability`, evaluating
+// function values against `ctx` (`{ region, model, sesFromEmail }`).
+// Entries resolving to empty values are dropped.
+export function resolveAddonEnvVars(capability, ctx = {}) {
+    const entries = ADDON_ENV_VARS[capability] || [];
+    const resolved = [];
+    for (const entry of entries) {
+        const value = typeof entry.value === 'function' ? entry.value(ctx) : entry.value;
+        if (typeof value !== 'string' || value === '') continue;
+        resolved.push({ name: entry.name, value });
+    }
+    return resolved;
+}

package/src/utils/ai-rules.js

@@ -0,0 +1,59 @@
+import fsSync from 'fs';
+
+export const getBaseRules = (context = {}) => `
+# Grada Infrastructure Context
+
+This project's AWS infrastructure is managed strictly by the \`grada\` CLI.
+**DO NOT** generate custom Terraform, AWS CloudFormation, or raw AWS CLI commands to deploy this application or modify the architecture.
+
+### Standard Operating Procedures
+
+1. **Applying Changes:** If the user asks to deploy, provision, or update the infrastructure, instruct them to run:
+   \`npx grada-run apply\`
+
+2. **Environment Variables:** If the user adds a new environment variable and needs it available in production, instruct them to run:
+   \`npx grada-run secrets push <path-to-env-file>\`
+
+3. **Teardown:** If the user wants to destroy the AWS environment, instruct them to run:
+   \`npx grada-run destroy\`
+
+4. **Architecture Details:** 
+   - **AWS Region:** \`${context.region || 'Unknown (Check terraform/main.tf)'}\`
+   - **Container Port:** \`${context.port || 'Unknown'}\`
+   - The infrastructure is an AWS ECS Fargate cluster.
+   - It uses an Application Load Balancer (ALB).
+   - CI/CD is handled securely via GitHub Actions OIDC (no long-lived IAM keys).
+   - Preview environments (Ephemeral PRs) are managed via Terraform Workspaces.
+`;
+
+export const getCursorRules = (context = {}) => `---
+description: "Rules for deploying the application and managing AWS infrastructure"
+globs: ["terraform/*.tf", ".github/workflows/*.yml", "Dockerfile"]
+---${getBaseRules(context)}`;
+
+export function injectManagedBlock(filePath, content, isMarkdown = true) {
+    const beginMarker = isMarkdown ? '<!-- BEGIN GRADA CONTEXT -->' : '# BEGIN GRADA CONTEXT';
+    const endMarker = isMarkdown ? '<!-- END GRADA CONTEXT -->' : '# END GRADA CONTEXT';
+    const legacyBeginMarker = isMarkdown ? '<!-- BEGIN DEPLOY-STACK CONTEXT -->' : '# BEGIN DEPLOY-STACK CONTEXT';
+    const legacyEndMarker = isMarkdown ? '<!-- END DEPLOY-STACK CONTEXT -->' : '# END DEPLOY-STACK CONTEXT';
+    const block = `\n${beginMarker}\n${content.trim()}\n${endMarker}\n`;
+
+    if (fsSync.existsSync(filePath)) {
+        let fileContent = fsSync.readFileSync(filePath, 'utf8');
+        // Replace an existing block in either brand variant so re-runs
+        // refresh legacy files instead of appending a duplicate block.
+        // (Markers carry no regex metacharacters, so direct interpolation
+        // is safe.)
+        const regex = new RegExp(`\\n?(?:${beginMarker}|${legacyBeginMarker})[\\s\\S]*?(?:${endMarker}|${legacyEndMarker})\\n?`);
+
+        if (regex.test(fileContent)) {
+            fileContent = fileContent.replace(regex, block); // Replace our old rules
+        } else {
+            fileContent = fileContent.trim() + '\n' + block; // Append to bottom
+        }
+        fsSync.writeFileSync(filePath, fileContent);
+    } else {
+        // File doesn't exist, create it cleanly
+        fsSync.writeFileSync(filePath, block.trim() + '\n');
+    }
+}

package/src/utils/args.js

@@ -0,0 +1,91 @@
+function toKey(name) {
+    return name
+        .split('-')
+        .map((part, index) => (index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)))
+        .join('');
+}
+
+// Accepts flag entries as bare names (`'project-name'` → `projectName`) or
+// explicit `{ name, key }` pairs for keys that diverge (e.g. `--headless`).
+function normalizeEntries(entries) {
+    const map = new Map();
+    for (const entry of entries || []) {
+        if (typeof entry === 'string') {
+            map.set(entry, toKey(entry));
+        } else if (entry && typeof entry.name === 'string') {
+            map.set(entry.name, entry.key || toKey(entry.name));
+        }
+    }
+    return map;
+}
+
+// Guards module entry points against non-object options (direct programmatic
+// misuse or automated fuzzing): anything that is not an object behaves like
+// `{}`, so callers always reach structured validation instead of TypeErrors.
+export function normalizeOptions(options) {
+    return options !== null && typeof options === 'object' ? options : {};
+}
+
+// Guards argument parsers against non-array inputs: anything that is not an
+// array behaves like `[]`.
+export function normalizeArgv(argv) {
+    return Array.isArray(argv) ? [...argv] : [];
+}
+
+// Declarative CLI flag parsing shared by every command module.
+//
+// - `string`: `--name value` or `--name=value` (last one wins; a trailing
+//   `--name` with no value is dropped, matching the hand-written parsers).
+// - `number`: like `string` but coerced with `Number()`.
+// - `boolean`: bare `--name` means `true`; `--name=<v>` is `v === 'true'`.
+// - `bareBoolean`: bare `--name` only; any `=value` form is ignored.
+// - `alias`: single-dash shorthands (`{ f: 'follow' }` makes `-f` act as
+//   the bare long flag).
+//
+// Unknown `--flags` are dropped and everything else is returned in `rest`
+// so each command can apply its own positional rules.
+export function parseFlags(args, { string = [], number = [], boolean = [], bareBoolean = [], alias = {} } = {}) {
+    const options = {};
+    const rest = [];
+    const strings = normalizeEntries(string);
+    const numbers = normalizeEntries(number);
+    const booleans = normalizeEntries(boolean);
+    const bares = normalizeEntries(bareBoolean);
+    const list = Array.isArray(args) ? args : [];
+    for (let i = 0; i < list.length; i++) {
+        let arg = list[i];
+        if (typeof arg !== 'string') {
+            rest.push(arg);
+            continue;
+        }
+        if (arg.length === 2 && arg[0] === '-' && Object.prototype.hasOwnProperty.call(alias, arg[1])) {
+            arg = `--${alias[arg[1]]}`;
+        }
+        if (!arg.startsWith('--')) {
+            rest.push(arg);
+            continue;
+        }
+        const eq = arg.indexOf('=');
+        const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+        const value = eq === -1 ? undefined : arg.slice(eq + 1);
+        if (strings.has(name)) {
+            if (value !== undefined) options[strings.get(name)] = value;
+            else if (i + 1 < list.length) options[strings.get(name)] = list[++i];
+            continue;
+        }
+        if (numbers.has(name)) {
+            if (value !== undefined) options[numbers.get(name)] = Number(value);
+            else if (i + 1 < list.length) options[numbers.get(name)] = Number(list[++i]);
+            continue;
+        }
+        if (booleans.has(name)) {
+            options[booleans.get(name)] = value === undefined ? true : value === 'true';
+            continue;
+        }
+        if (bares.has(name)) {
+            if (value === undefined) options[bares.get(name)] = true;
+            continue;
+        }
+    }
+    return { options, rest };
+}

package/src/utils/aws.js

@@ -0,0 +1,178 @@
+import { STSClient, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
+import { S3Client, CreateBucketCommand, PutBucketVersioningCommand, PutBucketTaggingCommand } from '@aws-sdk/client-s3';
+import { DeleteBucketCommand, ListObjectVersionsCommand, DeleteObjectsCommand } from "@aws-sdk/client-s3";
+import { spawnSync } from 'child_process';
+import color from 'picocolors';
+
+export const AWS_CLI_INSTALL_URL = 'https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html';
+export const AWS_CLI_CACHE_TTL_MS = 5000;
+
+const TROUBLESHOOTING_URL = 'https://github.com/grada-run/grada/blob/main/apps/docs/src/content/docs/guides/aws-credentials.md';
+
+let cachedAwsCliResult = null;
+
+export function resetAwsCliCache() {
+    cachedAwsCliResult = null;
+}
+
+function checkAwsCli(runSync) {
+    try {
+        const result = runSync('aws', ['--version'], { stdio: 'ignore' });
+        if (result && typeof result.status === 'number') return result.status === 0;
+        if (result && result.error) return false;
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export function hasAwsCli(options = {}) {
+    // Custom implementations (injected by tests) always execute directly so
+    // they never read or pollute the shared cache.
+    if (options.spawnSyncImpl !== undefined) {
+        return checkAwsCli(options.spawnSyncImpl);
+    }
+    const now = Date.now();
+    if (cachedAwsCliResult && cachedAwsCliResult.expiresAt > now) {
+        return cachedAwsCliResult.value;
+    }
+    const value = checkAwsCli(spawnSync);
+    cachedAwsCliResult = { value, expiresAt: now + AWS_CLI_CACHE_TTL_MS };
+    return value;
+}
+
+// AWS SDK errors that mean "credentials expired or invalid" rather than a
+// command-specific failure. Single definition shared by every command's
+// catch block.
+export function isAuthError(error) {
+    return !!error && (error.name === 'UnrecognizedClientException' || error.name === 'ExpiredTokenException');
+}
+
+// The shared auth-failure branch for command catch blocks: prints the
+// credential-recovery hint (and exits). Returns true when the error was an
+// auth failure that has been fully handled — the caller should `return` its
+// own auth result immediately. Call only after tracking failure telemetry,
+// matching the order every catch block uses today.
+export function handleAuthErrorBranch(error, clackSpinner = null, options = {}) {
+    if (!isAuthError(error)) return false;
+    handleAwsAuthError(error, clackSpinner, options);
+    return true;
+}
+
+// Returns an injected mock client when it quacks like an SDK client,
+// otherwise constructs the real one. Single definition for the
+// options-injection pattern every AWS command uses for testability.
+export function resolveClient(injected, ClientClass, clientOptions = {}) {
+    if (injected && typeof injected.send === 'function') return injected;
+    return new ClientClass(clientOptions);
+}
+
+export function handleAwsAuthError(error, clackSpinner = null, options = {}) {
+    if (clackSpinner) {
+        clackSpinner.stop(color.red('❌ AWS session expired or invalid credentials.'));
+    }
+    if (!hasAwsCli(options)) {
+        console.log(color.red('\n✖ AWS CLI not found.'));
+        console.log(`  Install the AWS CLI: ${color.blue(color.underline(AWS_CLI_INSTALL_URL))}`);
+        console.log(`  Then run ${color.cyan('aws sso login')} (or ${color.cyan('aws configure')}) and try again.`);
+    } else {
+        console.log(color.yellow('\n⚠️  AWS Session Expired / Invalid Credentials'));
+        console.log(`Run ${color.cyan('aws sso login')} or ${color.cyan('aws configure')} to refresh your credentials.`);
+    }
+    console.log(color.blue(`\n📘 Troubleshooting Guide: ${color.underline(TROUBLESHOOTING_URL)}\n`));
+    process.exit(1);
+    return;
+}
+
+export async function checkAwsCredentials(region) {
+    const resolvedRegion = region || process.env.AWS_REGION || 'us-east-2';
+    if (process.env.CI_MOCK_AWS === 'true') {
+        return { accountId: '123456789012', awsAccountId: '123456789012', region: resolvedRegion };
+    }
+    const stsClient = new STSClient({ region: resolvedRegion });
+    const { Account } = await stsClient.send(new GetCallerIdentityCommand({}));
+    return { accountId: Account, awsAccountId: Account, region: resolvedRegion };
+}
+
+export async function provisionStateBucket(region, projectName) {
+    if (process.env.CI_MOCK_AWS === 'true') {
+        return { awsAccountId: '123456789012', stateBucketName: 'mock-tf-state-bucket' };
+    }
+    const stsClient = new STSClient({ region });
+    let awsAccountId;
+
+    // 1. Get AWS Account ID
+    const { Account } = await stsClient.send(new GetCallerIdentityCommand({}));
+    awsAccountId = Account;
+
+    // 2. Format Bucket Name
+    let stateBucketName = `${projectName}-tfstate-${awsAccountId}`.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+    if (stateBucketName.length > 63) {
+        stateBucketName = stateBucketName.substring(0, 63).replace(/-$/, '');
+    }
+
+    // 3. Create S3 Bucket & Enable Versioning
+    const s3Client = new S3Client({ region });
+    try {
+        await s3Client.send(new CreateBucketCommand({
+            Bucket: stateBucketName,
+            CreateBucketConfiguration: region === 'us-east-1' ? undefined : { LocationConstraint: region }
+        }));
+
+        await s3Client.send(new PutBucketTaggingCommand({
+            Bucket: stateBucketName,
+            Tagging: {
+                TagSet: [
+                    { Key: "ManagedBy", Value: "grada" }
+                ]
+            }
+        }));
+
+        await s3Client.send(new PutBucketVersioningCommand({
+            Bucket: stateBucketName,
+            VersioningConfiguration: { Status: 'Enabled' }
+        }));
+    } catch (error) {
+        // Ignore if the bucket already exists and is owned by the user
+        if (error.name !== 'BucketAlreadyOwnedByYou') {
+            throw error;
+        }
+    }
+
+    return { awsAccountId, stateBucketName };
+}
+
+export async function teardownStateBucket(region, bucketName) {
+    if (process.env.CI_MOCK_AWS === 'true') {
+        return true;
+    }
+    const client = new S3Client({ region });
+
+    try {
+        // 1. Fetch all object versions and delete markers
+        const listCommand = new ListObjectVersionsCommand({ Bucket: bucketName });
+        const { Versions, DeleteMarkers } = await client.send(listCommand);
+
+        const objectsToDelete = [];
+        if (Versions) objectsToDelete.push(...Versions.map(v => ({ Key: v.Key, VersionId: v.VersionId })));
+        if (DeleteMarkers) objectsToDelete.push(...DeleteMarkers.map(v => ({ Key: v.Key, VersionId: v.VersionId })));
+
+        // 2. Delete all contents if any exist
+        if (objectsToDelete.length > 0) {
+            const deleteCommand = new DeleteObjectsCommand({
+                Bucket: bucketName,
+                Delete: { Objects: objectsToDelete }
+            });
+            await client.send(deleteCommand);
+        }
+
+        // 3. Delete the now-empty bucket
+        const deleteBucketCommand = new DeleteBucketCommand({ Bucket: bucketName });
+        await client.send(deleteBucketCommand);
+
+        return true;
+    } catch (error) {
+        if (error.name === 'NoSuchBucket') return true; // Already deleted
+        throw error;
+    }
+}

package/src/utils/backup.js

@@ -0,0 +1,69 @@
+import fs from 'fs';
+import path from 'path';
+import { select, isCancel, cancel } from '@clack/prompts';
+import color from 'picocolors';
+
+export async function handleExistingFiles(targetDir, isHeadless = false) {
+    const tfPath = path.join(targetDir, 'terraform');
+    const dockerfilePath = path.join(targetDir, 'Dockerfile');
+    const wfDir = path.join(targetDir, '.github', 'workflows');
+    const wfPath = path.join(wfDir, 'deploy.yml');
+
+    const tfExists = fs.existsSync(tfPath);
+    const dockerfileExists = fs.existsSync(dockerfilePath);
+    const wfExists = fs.existsSync(wfPath);
+
+    if (!tfExists && !dockerfileExists && !wfExists) {
+        return; // Clean slate
+    }
+
+    const foundFiles = [];
+    if (tfExists) foundFiles.push('terraform/');
+    if (dockerfileExists) foundFiles.push('Dockerfile');
+    if (wfExists) foundFiles.push('.github/workflows/deploy.yml');
+
+    let overwriteDecision = 'backup';
+
+    if (!isHeadless) {
+        overwriteDecision = await select({
+            message: color.yellow(`⚠️  Conflicting files found (${foundFiles.join(', ')}). To guarantee a secure, 0-CVE deployment, we must use our optimized configurations.`),
+            options: [
+                { value: 'backup', label: 'Backup & Regenerate', hint: 'Move old configs to .bak and generate secure templates' },
+                { value: 'cancel', label: 'Cancel', hint: 'Exit without making changes' }
+            ]
+        });
+
+        if (isCancel(overwriteDecision) || overwriteDecision === 'cancel') {
+            cancel('Operation cancelled to protect existing files.');
+            process.exit(0);
+        }
+    }
+
+    // Execute the safe backup
+    const timestamp = Date.now();
+
+    if (tfExists) fs.renameSync(tfPath, `${tfPath}.bak.${timestamp}`);
+    if (dockerfileExists) fs.renameSync(dockerfilePath, `${dockerfilePath}.bak.${timestamp}`);
+    if (wfExists) fs.renameSync(wfPath, `${wfPath}.bak.${timestamp}`);
+
+    ensureGitIgnore(targetDir);
+
+    console.log(color.cyan(`ℹ️  Existing configuration files were safely backed up locally.`));
+}
+
+/**
+ * Appends backup patterns to .gitignore so local clutter never reaches GitHub.
+ */
+function ensureGitIgnore(targetDir) {
+    const gitignorePath = path.join(targetDir, '.gitignore');
+    const ignoreRules = '\n# grada backups\n*.bak.*\n';
+
+    if (fs.existsSync(gitignorePath)) {
+        const content = fs.readFileSync(gitignorePath, 'utf8');
+        if (!content.includes('*.bak.*')) {
+            fs.appendFileSync(gitignorePath, ignoreRules);
+        }
+    } else {
+        fs.writeFileSync(gitignorePath, ignoreRules);
+    }
+}