grada-run 0.0.2 → 0.32.0

package/src/utils/prompts.js

@@ -0,0 +1,278 @@
+import path from 'path';
+import { text, select, multiselect, confirm, group, cancel } from '@clack/prompts';
+import color from 'picocolors';
+import { execSync } from 'child_process';
+
+// Sanitizes a raw project name for AWS resource compatibility (ALB names
+// allow `[a-zA-Z0-9-]` only; ECR repositories require lowercase): trim,
+// lowercase, collapse every run of characters outside `[a-z0-9-]` —
+// including dots and underscores — into a single hyphen, strip
+// leading/trailing hyphens, and fall back to `'app'` when empty.
+export function sanitizeProjectName(rawName) {
+    const sanitized = String(rawName ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return sanitized || 'app';
+}
+
+function resolveActualProjectName(rawName) {
+    const actualProjectName = sanitizeProjectName(rawName);
+    if (actualProjectName !== String(rawName ?? '').trim()) {
+        console.log(color.dim(`Project name sanitized to "${actualProjectName}" for AWS resource compatibility.`));
+    }
+    return actualProjectName;
+}
+
+export async function getTargetDirectory(isHeadless, headlessOptions) {
+    if (isHeadless) {
+        const projectName = headlessOptions.dir || '.';
+        const rawName = projectName === '.' ? path.basename(process.cwd()) : projectName;
+        return {
+            projectName,
+            actualProjectName: resolveActualProjectName(rawName),
+            targetDir: projectName === '.' ? process.cwd() : path.join(process.cwd(), projectName)
+        };
+    }
+
+    const projectName = await text({
+        message: 'Where should we generate the infrastructure? (Type "." for current directory)',
+        placeholder: '.',
+        initialValue: '.',
+        validate: (value) => {
+            if (!value) return 'Please enter a name or directory.';
+            if (value !== '.' && value.includes(' ')) return 'Name cannot contain spaces.';
+        },
+    });
+
+    if (typeof projectName === 'symbol') {
+        cancel('Operation cancelled.');
+        process.exit(0);
+    }
+
+    const rawName = projectName === '.' ? path.basename(process.cwd()) : projectName;
+    return {
+        projectName,
+        actualProjectName: resolveActualProjectName(rawName),
+        targetDir: projectName === '.' ? process.cwd() : path.join(process.cwd(), projectName)
+    };
+}
+
+export async function getProjectConfig(isHeadless, headlessOptions, targetDir, detectedFramework, hints = {}) {
+    const capabilities = hints && typeof hints === 'object' ? hints.capabilities : null;
+    const explicitDbEngine = hints && typeof hints === 'object' && typeof hints.dbEngine === 'string' && hints.dbEngine
+        ? hints.dbEngine
+        : null;
+    // Lambda functions are fixed at 512 MB with no ALB health checks or
+    // replica counts, so the ECS sizing prompts are skipped for that target.
+    const isLambda = hints && typeof hints === 'object' && hints.target === 'lambda';
+    if (isHeadless) {
+        return {
+            framework: headlessOptions.framework || (detectedFramework ? detectedFramework.id : 'static'),
+            region: headlessOptions.region || 'us-east-2',
+            port: headlessOptions.port || (headlessOptions.framework === 'static' ? '8080' : '3000'),
+            size: headlessOptions.size || 'micro',
+            healthCheckPath: headlessOptions.healthCheckPath || '/',
+            desiredCount: headlessOptions.desiredCount || '1',
+            branch: headlessOptions.branch || 'main',
+            needsDatabase: headlessOptions.needsDatabase === 'true' || headlessOptions.needsDatabase === true,
+            dbEngine: 'postgres',
+            enablePrPreviews: headlessOptions.enablePrPreviews === 'true' || headlessOptions.enablePrPreviews === true,
+            setupType: 'headless'
+        };
+    }
+
+    let finalFramework = detectedFramework ? detectedFramework.id : null;
+
+    if (!finalFramework) {
+        finalFramework = await select({
+            message: 'Which framework preset should we configure?',
+            options: [
+                { value: 'node', label: 'Node.js / Express' },
+                { value: 'nestjs', label: 'NestJS' },
+                { value: 'nextjs', label: 'Next.js (Standalone)' },
+                { value: 'nuxt', label: 'Nuxt 3 (SSR)' },
+                { value: 'svelte', label: 'SvelteKit (SSR)' },
+                { value: 'python', label: 'Python FastAPI' },
+                { value: 'django', label: 'Django (Python)' },
+                { value: 'rails', label: 'Ruby on Rails' },
+                { value: 'go', label: 'Go (Golang)' },
+                { value: 'static', label: 'Static Site (Gatsby, React, plain HTML via Nginx)' },
+            ],
+        });
+        if (typeof finalFramework === 'symbol') process.exit(0);
+    }
+
+    const setupType = await select({
+        message: 'Choose your setup mode:',
+        options: [
+            { value: 'quick', label: '⚡ Quickstart (Recommended)', hint: 'Production defaults, minimal prompts' },
+            { value: 'advanced', label: '🛠️  Advanced Configuration', hint: 'Customize health checks, task count, branch, etc.' },
+        ],
+    });
+    if (typeof setupType === 'symbol') process.exit(0);
+
+    let defaultPort = '3000';
+    if (finalFramework === 'static' || finalFramework === 'go') defaultPort = '8080';
+    if (finalFramework === 'python' || finalFramework === 'django') defaultPort = '8000';
+
+    let currentGitBranch = 'main';
+    try {
+        currentGitBranch = execSync('git symbolic-ref --short HEAD', { cwd: targetDir, stdio: 'pipe' }).toString().trim();
+    } catch (e) { }
+
+    let needsDatabase = false;
+    let dbEngine = 'postgres';
+    const isBackendFramework = ['node', 'nestjs', 'nextjs', 'nuxt', 'svelte', 'python', 'django', 'rails', 'go'].includes(finalFramework);
+
+    if (isBackendFramework) {
+        const dbEvidence = capabilities?.relationalDb?.detected === true
+            ? capabilities.relationalDb.evidence || []
+            : [];
+        const mysqlHint = capabilities?.upcomingHints?.mysql === true;
+        const dbChoice = await confirm({
+            message: dbEvidence.length > 0
+                ? `Do you need a managed AWS RDS PostgreSQL database? (Adds ~$14/month or uses AWS Free Tier) (detected: ${dbEvidence.join(', ')})`
+                : 'Do you need a managed AWS RDS PostgreSQL database? (Adds ~$14/month or uses AWS Free Tier)',
+            initialValue: dbEvidence.length > 0 || mysqlHint,
+        });
+        if (typeof dbChoice === 'symbol') process.exit(0);
+        needsDatabase = dbChoice;
+        if (needsDatabase) {
+            if (explicitDbEngine) {
+                dbEngine = explicitDbEngine;
+            } else {
+                const engineChoice = await select({
+                    message: 'Which database engine should we provision?',
+                    options: [
+                        { value: 'postgres', label: 'PostgreSQL 16 (RDS db.t4g.micro)', hint: '~$13.98/mo fixed' },
+                        { value: 'aurora-postgresql', label: 'Aurora PostgreSQL Serverless v2 (0–2 ACU)', hint: '$0/mo idle compute + storage' },
+                        { value: 'mysql', label: 'MySQL 8.0 (RDS db.t4g.micro)', hint: '~$13.98/mo fixed' },
+                    ],
+                    initialValue: mysqlHint ? 'mysql' : 'postgres',
+                });
+                if (typeof engineChoice === 'symbol') process.exit(0);
+                dbEngine = engineChoice;
+            }
+        }
+    }
+
+    let enablePrPreviews = false;
+    let aiAssistants = [];
+    if (setupType === 'advanced') {
+        const prChoice = await confirm({
+            message: `Enable Ephemeral PR Previews? (Spins up isolated, temporary AWS environments for PRs)\n  ${color.gray('📖 Learn more: https://github.com/grada-run/grada/blob/main/apps/docs/src/content/docs/guides/ephemeral-pr-previews.md')}`,
+            initialValue: false,
+        });
+        if (typeof prChoice === 'symbol') process.exit(0);
+        enablePrPreviews = prChoice;
+
+        aiAssistants = await getAiAssistants();
+    }
+
+    const project = await group({
+        region: () => select({
+            message: 'Which AWS region do you want to deploy to?',
+            options: [
+                { value: 'us-east-1', label: 'us-east-1 (N. Virginia)' },
+                { value: 'us-east-2', label: 'us-east-2 (Ohio)' },
+                { value: 'eu-west-1', label: 'eu-west-1 (Ireland)' },
+                { value: 'eu-central-1', label: 'EU (Frankfurt)' },
+                { value: 'ap-southeast-2', label: 'Asia Pacific (Sydney)' },
+            ],
+        }),
+        port: () => text({
+            message: 'What port does your container expose?',
+            placeholder: defaultPort,
+            defaultValue: defaultPort,
+        }),
+        size: () => isLambda ? undefined : select({
+            message: 'Select your Fargate compute size:',
+            options: [
+                { value: 'micro', label: 'Micro (0.25 vCPU, 512MB RAM) - Best for POCs' },
+                { value: 'small', label: 'Small (0.5 vCPU, 1GB RAM) - Best for small Projects' },
+            ],
+        }),
+        healthCheckPath: () => (setupType === 'quick' || isLambda) ? undefined : text({
+            message: 'ALB Health Check Path:',
+            placeholder: '/',
+            defaultValue: '/',
+        }),
+        desiredCount: () => (setupType === 'quick' || isLambda) ? undefined : select({
+            message: 'How many container replicas (tasks) should run?',
+            options: [
+                { value: '1', label: '1 Task (Single instance - lowest cost)' },
+                { value: '2', label: '2 Tasks (High Availability across AZs)' },
+            ],
+            defaultValue: '1',
+        }),
+        branch: () => setupType === 'quick' ? undefined : text({
+            message: 'Primary Git deployment branch for CI/CD:',
+            placeholder: currentGitBranch,
+            defaultValue: currentGitBranch,
+        }),
+    }, { onCancel: () => process.exit(0) });
+
+    return {
+        framework: finalFramework,
+        region: project.region,
+        port: project.port,
+        size: project.size || 'micro',
+        healthCheckPath: project.healthCheckPath || '/',
+        desiredCount: project.desiredCount || '1',
+        branch: project.branch || currentGitBranch,
+        needsDatabase,
+        dbEngine,
+        enablePrPreviews,
+        aiAssistants,
+        setupType
+    };
+}
+
+// Prompts for the background worker command. Pre-fills from the Procfile
+// worker process when present, otherwise from capability detection
+// (`npm run <script>`). Returns the (possibly edited) command string.
+export async function promptWorkerCommand(procfile, capabilities = null) {
+    const procfileCommand = Array.isArray(procfile?.worker) ? procfile.worker.join(' ') : '';
+    const detectedCommand = typeof capabilities?.worker?.suggestedCommand === 'string'
+        ? capabilities.worker.suggestedCommand
+        : '';
+    const answer = await text({
+        message: procfileCommand
+            ? 'What command runs your background worker? (Empty keeps the Procfile default)'
+            : 'What command runs your background worker? (Empty skips the worker service)',
+        placeholder: 'celery -A config worker',
+        initialValue: procfileCommand || detectedCommand,
+    });
+    if (typeof answer === 'symbol') {
+        cancel('Operation cancelled.');
+        process.exit(0);
+    }
+    return typeof answer === 'string' ? answer : '';
+}
+
+export async function getAiAssistants() {
+    const selected = await multiselect({
+        message: 'Which AI coding assistants does your team use?',
+        options: [
+            { value: 'cursor', label: 'Cursor', hint: 'Generates .cursor/rules/grada.mdc' },
+            { value: 'roo', label: 'Roo Code', hint: 'Generates .roo/rules/grada.md' },
+            { value: 'trae', label: 'Trae IDE', hint: 'Generates .trae/rules/project_rules.md' },
+            { value: 'windsurf', label: 'Windsurf', hint: 'Generates .windsurfrules' },
+            { value: 'copilot', label: 'GitHub Copilot', hint: 'Generates .github/copilot-instructions.md' },
+            { value: 'claude', label: 'Claude Code', hint: 'Updates CLAUDE.md' },
+            { value: 'goose', label: 'Goose', hint: 'Updates .goosehints' },
+            { value: 'aider', label: 'Aider', hint: 'Updates .aider.conf.yml' },
+            { value: 'continue', label: 'Continue.dev', hint: 'Generates .prompts/grada.prompt' }
+        ],
+        required: false,
+    });
+
+    if (typeof selected === 'symbol') {
+        cancel('Operation cancelled.');
+        process.exit(0);
+    }
+
+    return selected;
+}

package/src/utils/rds.js

@@ -0,0 +1,131 @@
+import { DescribeDBInstancesCommand, DescribeDBClustersCommand } from '@aws-sdk/client-rds';
+import { resolveProjectName, resolveWorkspaceSuffix } from './resolvers.js';
+import { normalizeOptions } from './args.js';
+
+// Error names the RDS API returns for a missing instance across SDK shapes.
+const NOT_FOUND_NAMES = new Set(['DBInstanceNotFound', 'DBInstanceNotFoundFault']);
+
+// Same convention for Aurora clusters.
+const CLUSTER_NOT_FOUND_NAMES = new Set(['DBClusterNotFound', 'DBClusterNotFoundFault']);
+
+// Shared RDS instance lookup for every `db` subcommand: exact identifier
+// match, `null` when the project has no database, unexpected errors rethrown.
+export async function findDbInstance(rdsClient, dbIdentifier) {
+    try {
+        const resp = await rdsClient.send(
+            new DescribeDBInstancesCommand({ DBInstanceIdentifier: dbIdentifier })
+        );
+        return (resp.DBInstances || [])[0] || null;
+    } catch (error) {
+        if (error && NOT_FOUND_NAMES.has(error.name)) return null;
+        throw error;
+    }
+}
+
+// Shared Aurora cluster lookup: exact identifier match, `null` when no
+// cluster exists under it, unexpected errors rethrown.
+export async function findDbCluster(rdsClient, dbClusterIdentifier) {
+    try {
+        const resp = await rdsClient.send(
+            new DescribeDBClustersCommand({ DBClusterIdentifier: dbClusterIdentifier })
+        );
+        return (resp.DBClusters || [])[0] || null;
+    } catch (error) {
+        if (error && CLUSTER_NOT_FOUND_NAMES.has(error.name)) return null;
+        throw error;
+    }
+}
+
+function isMysqlEngine(engine) {
+    return engine === 'mysql' || engine === 'aurora-mysql';
+}
+
+// Unified RDS discovery across single instances and Aurora clusters.
+// Tries the instance identifier first (zero extra API calls for the common
+// postgres/mysql case), then the cluster identifiers. Returns a normalized
+// descriptor `{ kind, id, engine, status, endpoint, port, dbName,
+// masterSecretArn, raw }` or `null` when nothing is provisioned.
+export async function findDbTarget(rdsClient, { dbIdentifier, dbClusterIdentifier } = {}) {
+    if (dbIdentifier) {
+        const instance = await findDbInstance(rdsClient, dbIdentifier);
+        if (instance) {
+            const port = instance.Endpoint?.Port ?? (isMysqlEngine(instance.Engine) ? 3306 : 5432);
+            return {
+                kind: 'instance',
+                id: dbIdentifier,
+                engine: instance.Engine,
+                status: instance.Status,
+                endpoint: instance.Endpoint?.Address,
+                port: String(port),
+                dbName: instance.DBName,
+                masterSecretArn: instance.MasterUserSecret?.SecretArn,
+                raw: instance,
+            };
+        }
+    }
+    const clusterIds = [dbClusterIdentifier, dbIdentifier].filter(
+        (id, index, list) => typeof id === 'string' && id !== '' && list.indexOf(id) === index
+    );
+    for (const clusterId of clusterIds) {
+        const cluster = await findDbCluster(rdsClient, clusterId);
+        if (cluster) {
+            const port = cluster.Port ?? (isMysqlEngine(cluster.Engine) ? 3306 : 5432);
+            return {
+                kind: 'cluster',
+                id: clusterId,
+                engine: cluster.Engine,
+                status: cluster.Status,
+                endpoint: cluster.Endpoint,
+                port: String(port),
+                dbName: cluster.DatabaseName,
+                masterSecretArn: cluster.MasterUserSecret?.SecretArn,
+                raw: cluster,
+            };
+        }
+    }
+    return null;
+}
+
+function pad2(value) {
+    return String(value).padStart(2, '0');
+}
+
+// Default manual snapshot id: `<db>-manual-YYYYMMDD-HHmmss` in UTC.
+// Lowercased so project names with uppercase stay RDS-safe.
+export function generateSnapshotId(dbIdentifier, now = new Date()) {
+    const stamp = `${now.getUTCFullYear()}${pad2(now.getUTCMonth() + 1)}${pad2(now.getUTCDate())}`
+        + `-${pad2(now.getUTCHours())}${pad2(now.getUTCMinutes())}${pad2(now.getUTCSeconds())}`;
+    return `${dbIdentifier}-manual-${stamp}`.toLowerCase();
+}
+
+// RDS snapshot identifier rules: starts with a letter, letters/digits/hyphens
+// after that, no consecutive hyphens, no trailing hyphen, max 255 chars.
+export function isValidSnapshotId(id) {
+    if (typeof id !== 'string') return false;
+    if (!/^[a-zA-Z][a-zA-Z0-9-]{0,254}$/.test(id)) return false;
+    if (id.includes('--') || id.endsWith('-')) return false;
+    return true;
+}
+
+// Database identifier for the current project/workspace. An explicit
+// `--db-identifier` override wins; otherwise `<appName>-db`.
+export function resolveDbIdentifier(options = {}, cwd = process.cwd()) {
+    const opts = normalizeOptions(options);
+    if (typeof opts.dbIdentifier === 'string' && opts.dbIdentifier.trim()) {
+        return opts.dbIdentifier.trim();
+    }
+    const base = resolveProjectName(opts, cwd);
+    return `${base}${resolveWorkspaceSuffix(opts, cwd)}-db`;
+}
+
+// Aurora cluster identifier for the current project/workspace. An explicit
+// `--db-identifier` override wins (tried as both kinds); otherwise
+// `<appName>-db-cluster`, matching the generated cluster_identifier.
+export function resolveDbClusterIdentifier(options = {}, cwd = process.cwd()) {
+    const opts = normalizeOptions(options);
+    if (typeof opts.dbIdentifier === 'string' && opts.dbIdentifier.trim()) {
+        return opts.dbIdentifier.trim();
+    }
+    const base = resolveProjectName(opts, cwd);
+    return `${base}${resolveWorkspaceSuffix(opts, cwd)}-db-cluster`;
+}

package/src/utils/resolvers.js

@@ -0,0 +1,174 @@
+import fsSync from 'fs';
+import path from 'path';
+import { normalizeOptions } from './args.js';
+
+export const FALLBACK_REGION = 'us-east-2';
+
+export function readFileSafe(filePath) {
+    if (typeof filePath !== 'string') return null;
+    try {
+        if (fsSync.existsSync(filePath)) return fsSync.readFileSync(filePath, 'utf8');
+    } catch {
+        // Fall through to defaults
+    }
+    return null;
+}
+
+// Compute targets supported by `--target`. `ecs` covers both the
+// canonical `ecs` value and its `fargate` synonym.
+export const COMPUTE_TARGETS = ['ecs', 'lambda'];
+
+// Pure target check over rendered `main.tf` content: a Lambda project is
+// any project whose main.tf provisions the serverless function.
+export function detectComputeTargetFromMainTf(mainTfContent) {
+    if (typeof mainTfContent === 'string' && mainTfContent.includes('resource "aws_lambda_function"')) {
+        return 'lambda';
+    }
+    return 'ecs';
+}
+
+// Reads the compute target of the project rooted at `cwd`. Missing or
+// unreadable Terraform falls back to `ecs` so legacy projects and
+// pre-init guards keep their historical behavior.
+export function readTerraformComputeTarget(cwd = process.cwd()) {
+    const base = resolveCwd({}, cwd);
+    return detectComputeTargetFromMainTf(readFileSafe(path.join(base, 'terraform', 'main.tf')));
+}
+
+// Working directory for file resolution: an explicit string `cwd` option,
+// otherwise the positional `fallback` when it is a usable path, otherwise
+// the process cwd. A throwing `process.cwd()` (deleted directory)
+// propagates so callers route through PROJECT_NOT_INITIALIZED.
+export function resolveCwd(options = {}, fallback) {
+    const opts = normalizeOptions(options);
+    if (typeof opts.cwd === 'string' && opts.cwd) return opts.cwd;
+    if (typeof fallback === 'string' && fallback) return fallback;
+    return process.cwd();
+}
+
+export function readTerraformRegion(cwd = process.cwd()) {
+    const base = resolveCwd({}, cwd);
+    const mainTf = readFileSafe(path.join(base, 'terraform', 'main.tf'));
+    if (!mainTf) return null;
+    const match = mainTf.match(/region\s*=\s*"([^"]+)"/);
+    if (!match || match[1].includes('{{')) return null;
+    return match[1];
+}
+
+export function resolveRegion(options = {}, cwd = process.cwd()) {
+    const opts = normalizeOptions(options);
+    if (typeof opts.region === 'string' && opts.region.trim()) {
+        return opts.region.trim();
+    }
+    if (typeof process.env.AWS_REGION === 'string' && process.env.AWS_REGION.trim()) {
+        return process.env.AWS_REGION.trim();
+    }
+    return readTerraformRegion(resolveCwd(opts, cwd)) || FALLBACK_REGION;
+}
+
+export function readTerraformProjectName(cwd = process.cwd()) {
+    const base = resolveCwd({}, cwd);
+    const mainTf = readFileSafe(path.join(base, 'terraform', 'main.tf'));
+    if (!mainTf) return null;
+    const appNameMatch = mainTf.match(/app_name\s*=\s*"([^"$]+)\$\{local\.env_suffix\}"/);
+    if (appNameMatch) return appNameMatch[1];
+    // Hand-written files may set a plain app_name (possibly with some other
+    // ${...} suffix); it still outranks the ECR heuristic below.
+    const genericMatch = mainTf.match(/app_name\s*=\s*"([^"]+)"/);
+    if (genericMatch && !genericMatch[1].includes('{{')) {
+        const stripped = genericMatch[1].replace(/\$\{.*$/, '').replace(/[-_]$/, '');
+        if (stripped) return stripped;
+    }
+    const ecrMatch = mainTf.match(/resource\s+"aws_ecr_repository"\s+"app"\s*\{[^}]*?name\s*=\s*"([^"]+)-repo"/);
+    if (ecrMatch) return ecrMatch[1];
+    return null;
+}
+
+export function resolveProjectName(options = {}, cwd = process.cwd()) {
+    const opts = normalizeOptions(options);
+    const base = resolveCwd(opts, cwd);
+    if (typeof opts.projectName === 'string' && opts.projectName.trim()) {
+        return opts.projectName.trim();
+    }
+    return readTerraformProjectName(base) || path.basename(path.resolve(base));
+}
+
+export function resolveCluster(options = {}, cwd = process.cwd()) {
+    const opts = normalizeOptions(options);
+    if (typeof opts.cluster === 'string' && opts.cluster.trim()) return opts.cluster.trim();
+    if (typeof process.env.ECS_CLUSTER === 'string' && process.env.ECS_CLUSTER.trim()) {
+        return process.env.ECS_CLUSTER.trim();
+    }
+    return `${resolveProjectName(opts, cwd)}-cluster`;
+}
+
+export function resolveService(options = {}, cwd = process.cwd()) {
+    const opts = normalizeOptions(options);
+    if (typeof opts.service === 'string' && opts.service.trim()) return opts.service.trim();
+    if (typeof opts.serviceName === 'string' && opts.serviceName.trim()) return opts.serviceName.trim();
+    if (typeof process.env.ECS_SERVICE === 'string' && process.env.ECS_SERVICE.trim()) {
+        return process.env.ECS_SERVICE.trim();
+    }
+    return `${resolveProjectName(opts, cwd)}-service`;
+}
+
+export function resolveLogGroup(options = {}, cwd = process.cwd()) {
+    const opts = normalizeOptions(options);
+    if (typeof opts.logGroup === 'string' && opts.logGroup.trim()) {
+        return opts.logGroup.trim();
+    }
+    if (typeof opts.logGroupName === 'string' && opts.logGroupName.trim()) {
+        return opts.logGroupName.trim();
+    }
+    if (typeof process.env.ECS_LOG_GROUP === 'string' && process.env.ECS_LOG_GROUP.trim()) {
+        return process.env.ECS_LOG_GROUP.trim();
+    }
+    const base = resolveCwd(opts, cwd);
+    const projectName = resolveProjectName(opts, base);
+    // Lambda functions log to /aws/lambda/<fn> (see main-lambda.tf), where
+    // the function name is `<app>-fn`.
+    if (readTerraformComputeTarget(base) === 'lambda') {
+        return `/aws/lambda/${projectName}-fn`;
+    }
+    return `/ecs/${projectName}`;
+}
+
+// True when prompts must not block: explicit headless flags, CI/test
+// environments, or non-TTY stdio. An explicit `isHeadless: false` (or
+// `headless: false`) forces interactive mode so unit tests can simulate
+// TTY prompts. `env`/`stdin`/`stdout` are injectable for tests.
+export function resolveHeadless(options = {}, env = process.env, stdin = process.stdin, stdout = process.stdout) {
+    const opts = normalizeOptions(options);
+    if (opts.isHeadless === false || opts.headless === false) return false;
+    return Boolean(
+        opts.isHeadless ||
+        opts.headless ||
+        (env && (env.CI || env.VITEST)) ||
+        (env && env.NODE_ENV === 'test') ||
+        !stdin?.isTTY ||
+        !stdout?.isTTY
+    );
+}
+
+// Workspace-namespaced application name (`myapp` or `myapp-pr-123`) shared
+// by every `db` subcommand. `workspace` is the explicit `--workspace` value
+// (or undefined to auto-detect `.terraform/environment` under `cwd`).
+export function resolveAppName(projectName, workspace, cwd = process.cwd()) {
+    return `${projectName}${resolveWorkspaceSuffix({ workspace, cwd }, cwd)}`;
+}
+
+// Reads the local Terraform workspace (e.g. a PR-preview environment).
+// Returns '' for the default workspace so names stay un-suffixed.
+export function resolveWorkspaceSuffix(options = {}, cwd = process.cwd()) {
+    const opts = normalizeOptions(options);
+    const base = resolveCwd(opts, cwd);
+    let workspace = null;
+    if (typeof opts.workspace === 'string' && opts.workspace.trim()) {
+        workspace = opts.workspace.trim();
+    } else {
+        const detected = readFileSafe(path.join(base, '.terraform', 'environment'));
+        if (typeof detected === 'string' && detected.trim()) workspace = detected.trim();
+    }
+    if (!workspace || workspace === 'default') return '';
+    return `-${workspace}`;
+}