@salte-common/terraflow 1.0.0-alpha.4 → 1.0.0-alpha.7

package/.cursor/rules/terraflow-project.mdc

@@ -0,0 +1,149 @@
+---
+description: Terraflow project rules - MANDATORY AI code tracking and development guidelines
+globs: ["*"]
+alwaysApply: true
+---
+
+# ⚠️ STOP: READ THIS FIRST
+
+**BEFORE creating or modifying ANY file, you MUST:**
+1. Read the "AI Code Tracking" section below
+2. Understand that updating `.ai-metadata.json` is MANDATORY, not optional
+3. Update metadata IMMEDIATELY after each file, before proceeding
+
+**If you create/modify a file without updating `.ai-metadata.json`, you have FAILED.**
+
+# Terraflow Development Guidelines
+
+This project follows the comprehensive specification in `SPECIFICATION.md`.
+
+Additionally, follow these ongoing guidelines:
+
+- Follow https://github.com/salte-common/standards recursively
+- **MANDATORY: Update `.ai-metadata.json` immediately after each file creation/modification**
+- Use TypeScript strict mode
+- Maintain >80% test coverage
+- Document all public APIs with JSDoc
+- Use conventional commits
+- Keep functions small and focused
+- Prefer composition over inheritance
+
+# AI Code Tracking
+
+Additionally, when you generate code, update the `.ai-metadata.json` file to track AI contributions.
+
+## Metadata File Structure
+
+```json
+{
+  "files": {
+    "path/to/file.ts": {
+      "lines_total": 100,
+      "lines_ai_generated": 75,
+      "ai_percentage": 75.0,
+      "last_updated": "2024-12-04T15:30:00Z",
+      "tool": "cursor|copilot|jetbrains-ai"
+    }
+  },
+  "metadata_version": "1.0"
+}
+```
+
+**Field definitions:**
+- `lines_total`: Total lines currently in the file (AI-generated + human-created)
+- `lines_ai_generated`: Only lines created by AI (cumulative for files modified multiple times)
+- `ai_percentage`: `(lines_ai_generated / lines_total) × 100`
+
+## Tracking Requirements
+
+1. **CRITICAL: Update immediately** - Update `.ai-metadata.json` IMMEDIATELY after creating or modifying each file, not at the end of the task. This ensures accurate line counts that only reflect AI-generated code, not user modifications.
+
+2. **Track every AI contribution** - Keep track of lines you generate or modify
+3. **Use relative paths** - Paths from repository root with forward slashes
+4. **Calculate percentages** - `(lines_ai_generated / lines_total) × 100`
+5. **ISO 8601 timestamps** - Format: `2024-12-04T15:30:00Z`
+6. **Preserve existing data** - Read the file first, merge your changes
+7. **Create if missing** - Initialize with empty files object
+
+## Required Workflow Pattern
+
+**ALWAYS follow this pattern for each file you create or modify:**
+
+1. **Before creating/modifying**: Track the starting state:
+   - If creating a new file: start with `lines_ai_generated: 0`
+   - If modifying existing file: read `.ai-metadata.json` first to get current `lines_ai_generated` value
+
+2. **While generating code**: Count lines AS YOU ADD THEM:
+   - Track each line of code, comments, blank lines, etc. that you generate
+   - Keep a running count as you write the file
+   - Count everything you add, including:
+     - Import statements
+     - Type definitions
+     - Functions and methods
+     - Comments and JSDoc
+     - Blank lines for formatting
+
+3. **After creating/modifying**: Update metadata immediately:
+   - Read `.ai-metadata.json` (or create if missing)
+   - For NEW files:
+     - `lines_total`: Read the file to get total lines (all AI-generated in this case)
+     - `lines_ai_generated`: All lines you added (same as `lines_total` for new files)
+   - For MODIFIED files:
+     - `lines_total`: Read the current file to get total lines (includes AI-generated + any human-created lines)
+     - `lines_ai_generated`: Previous `lines_ai_generated` value from metadata + lines you just added (only AI-generated lines)
+   - `ai_percentage`: Calculate `(lines_ai_generated / lines_total) × 100`
+   - `last_updated`: Current UTC timestamp
+   - `tool`: "cursor"
+   - Write the updated `.ai-metadata.json` back
+
+   **Important distinctions:**
+   - `lines_total`: Always the current total lines in the file (AI + human created)
+   - `lines_ai_generated`: Only lines created by AI (cumulative for modified files)
+
+4. Then proceed to the next file
+
+**DO NOT:**
+- Wait until the end to update metadata
+- Batch update multiple files at once
+- Include human-created lines in `lines_ai_generated` - only count AI-generated lines
+- Guess `lines_total` - always read the file to get the accurate total count
+
+## Example Workflow
+
+**Example 1: Creating a new file**
+
+User asks: "Create a feature following our standards"
+
+1. Reference salte-common/standards for service patterns
+2. **Create `src/features/my-feature.ts`**:
+   - Write the file content (tracking 50 lines as you generate them)
+   - Read the file: total lines = 50
+   - **IMMEDIATELY** read `.ai-metadata.json`
+   - Add entry: `{"src/features/my-feature.ts": {"lines_total": 50, "lines_ai_generated": 50, "ai_percentage": 100.0, ...}}`
+   - **IMMEDIATELY** write updated `.ai-metadata.json` back
+
+**Example 2: Modifying an existing file**
+
+User asks: "Add error handling to the validator"
+
+1. Read `.ai-metadata.json` - find existing entry shows `lines_ai_generated: 29`
+2. Read current `src/core/validator.ts` - file has 29 total lines
+3. Add error handling code (tracking 15 new lines as you generate them)
+4. Read the file again: now has 44 total lines
+5. **IMMEDIATELY** read `.ai-metadata.json`
+6. Update entry: `{"src/core/validator.ts": {"lines_total": 44, "lines_ai_generated": 44, "ai_percentage": 100.0, ...}}`
+   - `lines_total`: 44 (read from file - total lines currently in file)
+   - `lines_ai_generated`: 29 (previous) + 15 (new AI lines) = 44
+
+   **If user had added 10 lines between sessions:**
+   - File now has 54 total lines (29 original + 10 user-added + 15 new AI)
+   - `lines_total`: 54 (read from file)
+   - `lines_ai_generated`: 29 (previous) + 15 (new AI lines) = 44 (does NOT include user's 10 lines)
+   - `ai_percentage`: (44 / 54) × 100 = 81.5%
+7. **IMMEDIATELY** write updated `.ai-metadata.json` back
+
+**Remember:**
+- `lines_total` = current total lines in file (read the file to get this)
+- `lines_ai_generated` = only lines created by AI (track as you generate, add to previous value)
+- Track lines AS YOU GENERATE THEM, then update metadata immediately
+- Update metadata immediately after EACH file, not after all files are done

package/README.md

@@ -9,15 +9,17 @@ An opinionated Node.js CLI wrapper for Terraform that provides intelligent works
 
 ## About
 
-Terraflow was created by Dave Woodward, VP of Cloud & Enterprise Architecture with over 20 years of experience in financial services technology. Coming from a full-stack development background before evolving into cloud architecture, Dave brings a hands-on, practical approach to enterprise architecture that emphasizes solving real operational problems over theoretical ideals.
+Terraflow was created by Dave Woodward, a technologist with over 20 years of experience building and operating infrastructure in regulated enterprise environments. Coming from a full-stack development background before moving deeper into cloud architecture, Dave brings a hands-on, pragmatic approach that emphasizes solving real operational problems over theoretical ideals.
 
 ### The Problem
 
-After half a decade of managing Terraform in enterprise environments, a pattern emerged: every infrastructure repository needed the same orchestration logic. Before Terraflow, this meant writing bash scripts in every repo to handle the multi-step process of initializing Terraform, selecting the appropriate workspace, assuming cloud provider roles, retrieving secrets, and finally applying changes. These scripts were essential for testing Terraform locally before CI/CD pipelines, but they became repetitive maintenance overhead. Environment-specific and branch-specific configuration—some sensitive, some not—required careful orchestration that varied slightly across projects. Additionally, while consistent project structure proved crucial for helping developers understand resource dependencies, manually scaffolding this structure was time-consuming and error-prone.
+After half a decade of managing Terraform in enterprise environments, a clear pattern emerged: every infrastructure repository needed the same orchestration logic. Before Terraflow, this meant writing bash scripts in every repo to handle the multi-step process of initializing Terraform, selecting the appropriate workspace, assuming cloud provider roles, retrieving secrets, and finally applying changes.
+
+These scripts were essential for testing Terraform locally before CI/CD pipelines, but they quickly became repetitive maintenance overhead. Environment-specific and branch-specific configuration—some sensitive, some not—required careful orchestration that varied slightly across projects. Additionally, while consistent project structure proved crucial for helping developers understand resource dependencies, manually scaffolding this structure was time-consuming and error-prone.
 
 ### The Developer Perspective
 
-Coming from a development background rather than pure infrastructure, the importance of preview branches became immediately apparent. Developers need to see their infrastructure changes in isolation before those changes overwrite shared development environments. This preview branch support is often overlooked by infrastructure-focused practitioners, but it's critical for modern development workflows where multiple feature branches need to coexist temporarily.
+Coming from a development background rather than pure infrastructure, the importance of preview branches became immediately apparent. Developers need to see their infrastructure changes in isolation before those changes overwrite shared development environments. This preview branch support is often overlooked by infrastructure-focused practitioners, but it is critical for modern development workflows where multiple feature branches need to coexist temporarily.
 
 ### Terraflow's Approach
 
@@ -87,11 +89,16 @@ terraflow new my-infrastructure --provider gcp --language python
 ```
 
 This creates a complete project structure with:
+- **Cursor-ready** — Optimized for [Cursor](https://cursor.com/) to get up and running quickly with AI-assisted development
 - Terraform configuration files for your cloud provider
 - Application code templates in your chosen language
 - Pre-configured `.tfwconfig.yml` with backend settings
 - Example `.env.example` file
 - Complete `.gitignore` and `README.md`
+- `.ai-metadata.json` — AI code tracking (initialized with scaffold stats)
+- `.cursor/rules/terraform.mdc` — Cursor instructions for Terraflow (delete if not using Cursor)
+- `.cursor/rules/ai-metadata.mdc` — Cursor instructions for `.ai-metadata.json` maintenance
+- `.cursor/rules/development-standards.mdc` — Cursor instructions (language, platform, salte-common/standards)
 
 See [Project Scaffolding Documentation](docs/scaffolding.md) for complete details.
 
@@ -108,6 +115,9 @@ This creates a `.tfwconfig.yml` file with examples for all backends, secrets pro
 2. **Configure your backend and secrets** in `.tfwconfig.yml`:
 
 ```yaml
+# Required: Cloud provider (aws, gcp, or azure)
+provider: aws
+
 backend:
   type: s3
   config:

package/dist/commands/config.js

@@ -179,6 +179,11 @@ class ConfigCommand {
 # This file defines your Terraflow configuration
 # See https://github.com/salte-common/terraflow/blob/main/docs/configuration.md for full documentation
 
+# Cloud Provider (required)
+# ========================
+# Specify which cloud provider you are using: aws | gcp | azure
+provider: aws  # Change to 'gcp' or 'azure' as needed
+
 # Global Settings
 # ===============
 
@@ -315,9 +320,6 @@ backend:
 # Validation rules for Terraform operations
 
 # validations:
-#   # Require git commit before apply/destroy
-#   require_git_commit: true
-#
 #   # List of allowed workspace names (empty = allow all)
 #   allowed_workspaces:
 #     - development

package/dist/commands/new.js

@@ -101,6 +101,7 @@ class NewCommand {
         await (0, scaffolding_1.generateTerraformFiles)(projectDir, provider, finalProjectName);
         await (0, scaffolding_1.generateApplicationFiles)(projectDir, language, finalProjectName);
         await (0, scaffolding_1.generateConfigFiles)(projectDir, provider, language, finalProjectName);
+        await (0, scaffolding_1.generateAiMetadata)(projectDir, language);
         logger_1.Logger.info(`✅ Project "${projectName || 'current directory'}" created successfully!`);
         logger_1.Logger.info('');
         logger_1.Logger.info('Next steps:');

package/dist/core/config.js

@@ -13,6 +13,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
 const logger_1 = require("../utils/logger");
+const errors_1 = require("./errors");
 /**
  * Configuration manager for Terraflow
  * Handles loading and merging configuration from multiple sources
@@ -38,12 +39,22 @@ class ConfigManager {
                 terraform_log: false,
                 terraform_log_level: 'TRACE',
             },
+            // Note: provider is required and should be set in config file
         };
         // Load config file (higher priority than defaults)
         const configFile = ConfigManager.getConfigFilePath(cliOptions, cwd);
         const fileConfig = ConfigManager.loadConfigFile(configFile);
         // Get directory where config file is located (for .env file loading)
         const configFileDir = path_1.default.dirname(configFile);
+        // Validate that provider is set (only if config file exists)
+        if (fs_1.default.existsSync(configFile) && !fileConfig.provider) {
+            throw new errors_1.ConfigError('Configuration file must specify a "provider" (aws, gcp, or azure). ' +
+                'Run "terraflow config init" to generate a template, or add "provider: <provider>" to your .tfwconfig.yml');
+        }
+        // Validate provider value (only if provider is set)
+        if (fileConfig.provider && !['aws', 'gcp', 'azure'].includes(fileConfig.provider)) {
+            throw new errors_1.ConfigError(`Invalid provider "${fileConfig.provider}". Must be one of: aws, gcp, azure.`);
+        }
         // Load environment variables (higher priority than config file)
         const envConfig = ConfigManager.loadFromEnvironment();
         // Merge: defaults < fileConfig < envConfig < cliOptions
@@ -188,6 +199,10 @@ class ConfigManager {
             if (!config || typeof config !== 'object') {
                 continue;
             }
+            // Merge provider
+            if (config.provider !== undefined) {
+                result.provider = config.provider;
+            }
             // Merge workspace
             if (config.workspace !== undefined) {
                 result.workspace = config.workspace;

package/dist/core/context.d.ts

@@ -30,7 +30,8 @@ export declare class ContextBuilder {
     private static deriveWorkspace;
     /**
      * Build cloud provider information
-     * Detects cloud provider from environment (AWS, Azure, GCP)
+     * Detects cloud provider from configuration or environment (AWS, Azure, GCP)
+     * @param config - Terraflow configuration
      * @returns Cloud information
      */
     private static buildCloudInfo;

package/dist/core/context.js

@@ -58,7 +58,7 @@ class ContextBuilder {
     static async build(config, cwd = process.cwd()) {
         const workspace = await ContextBuilder.deriveWorkspace(config, cwd);
         const workingDir = config_1.ConfigManager.getWorkingDir(config, cwd);
-        const cloud = await ContextBuilder.buildCloudInfo();
+        const cloud = await ContextBuilder.buildCloudInfo(config);
         const vcs = await ContextBuilder.buildVcsInfo(cwd);
         const hostname = os_1.default.hostname();
         // Build template variables from environment and context
@@ -131,14 +131,15 @@ class ContextBuilder {
     }
     /**
      * Build cloud provider information
-     * Detects cloud provider from environment (AWS, Azure, GCP)
+     * Detects cloud provider from configuration or environment (AWS, Azure, GCP)
+     * @param config - Terraflow configuration
      * @returns Cloud information
      */
-    static async buildCloudInfo() {
+    static async buildCloudInfo(config) {
         // Use CloudUtils to detect cloud provider
         // This needs to happen early so validation can check it
         const { CloudUtils } = await Promise.resolve().then(() => __importStar(require('../utils/cloud')));
-        return await CloudUtils.detectCloud();
+        return await CloudUtils.detectCloud(config);
     }
     /**
      * Build VCS information

package/dist/core/environment.d.ts

@@ -19,9 +19,12 @@ export declare class EnvironmentSetup {
      * Setup cloud provider environment (AWS, Azure, GCP)
      * - Syncs AWS_REGION and AWS_DEFAULT_REGION
      * - Fetches account/subscription/project IDs
+     * @param config - Optional Terraflow configuration
      * @returns Updated cloud info
      */
-    static setupCloud(): Promise<ExecutionContext['cloud']>;
+    static setupCloud(config?: {
+        provider?: 'aws' | 'gcp' | 'azure';
+    }): Promise<ExecutionContext['cloud']>;
     /**
      * Setup VCS environment (git variables)
      * Sets generic GIT_REPOSITORY variable and GitHub Actions/GitLab CI compatible variables

package/dist/core/environment.js

@@ -50,10 +50,11 @@ class EnvironmentSetup {
      * Setup cloud provider environment (AWS, Azure, GCP)
      * - Syncs AWS_REGION and AWS_DEFAULT_REGION
      * - Fetches account/subscription/project IDs
+     * @param config - Optional Terraflow configuration
      * @returns Updated cloud info
      */
-    static async setupCloud() {
-        const cloud = await cloud_1.CloudUtils.detectCloud();
+    static async setupCloud(config) {
+        const cloud = await cloud_1.CloudUtils.detectCloud(config);
         // Sync AWS region if AWS provider detected
         if (cloud.provider === 'aws') {
             const region = cloud_1.CloudUtils.getAwsRegion();
@@ -198,7 +199,7 @@ class EnvironmentSetup {
         const envDir = projectRoot || process.cwd();
         EnvironmentSetup.loadEnvFile(envDir);
         // 2. Setup cloud environment (detect account IDs, regions)
-        const cloud = await EnvironmentSetup.setupCloud();
+        const cloud = await EnvironmentSetup.setupCloud(config);
         context.cloud = cloud;
         // 3. Setup VCS environment (git branch, commit, repository)
         await EnvironmentSetup.setupVcs(context);

package/dist/core/terraform.js

@@ -49,7 +49,7 @@ const errors_1 = require("./errors");
  * Commands that require workspace and init
  * Exported so it can be used by the CLI for command registration
  */
-exports.WORKSPACE_SENSITIVE_COMMANDS = [].concat(validator_1.FULL_VALIDATION_COMMANDS, validator_1.BACKEND_REQUIRED_COMMANDS, ['init'] // terraform init also needs backend setup
+exports.WORKSPACE_SENSITIVE_COMMANDS = [].concat(validator_1.FULL_VALIDATION_COMMANDS, validator_1.BACKEND_REQUIRED_COMMANDS, ['init', 'validate'] // terraform init and validate also need backend setup (providers initialized)
 );
 /**
  * Terraform executor for running terraform commands
@@ -70,7 +70,7 @@ class TerraformExecutor {
         environment_1.EnvironmentSetup.loadEnvFile(configFileDir);
         // Re-detect cloud after .env is loaded (credentials might be in .env)
         const { CloudUtils } = await Promise.resolve().then(() => __importStar(require('../utils/cloud')));
-        context.cloud = await CloudUtils.detectCloud();
+        context.cloud = await CloudUtils.detectCloud(config);
         // 1. Run validations
         logger_1.Logger.info('🔍 Running validations...');
         const validationResult = await validator_1.Validator.validate(command, config, context, {
@@ -259,11 +259,18 @@ class TerraformExecutor {
         }
         try {
             logger_1.Logger.debug(`Executing: terraform ${args.join(' ')} in ${workingDir}`);
-            (0, child_process_1.execSync)(`terraform ${args.join(' ')}`, {
+            // Use spawnSync with array to avoid shell interpretation of special characters
+            const result = (0, child_process_1.spawnSync)('terraform', args, {
                 cwd: workingDir,
                 stdio: 'inherit',
                 encoding: 'utf8',
             });
+            if (result.error) {
+                throw result.error;
+            }
+            if (result.status !== 0) {
+                throw new Error(`Terraform init failed with exit code ${result.status}`);
+            }
             logger_1.Logger.info('✅ Terraform initialized successfully');
         }
         catch (error) {
@@ -280,28 +287,34 @@ class TerraformExecutor {
         try {
             // Try to select existing workspace
             logger_1.Logger.debug(`Selecting workspace: ${workspaceName}`);
-            (0, child_process_1.execSync)(`terraform workspace select ${workspaceName}`, {
+            // Use spawnSync with array to avoid shell interpretation
+            const selectResult = (0, child_process_1.spawnSync)('terraform', ['workspace', 'select', workspaceName], {
                 cwd: workingDir,
                 stdio: 'pipe',
                 encoding: 'utf8',
             });
-            logger_1.Logger.debug(`Workspace ${workspaceName} selected`);
-        }
-        catch {
+            if (selectResult.status === 0) {
+                logger_1.Logger.debug(`Workspace ${workspaceName} selected`);
+                return;
+            }
             // Workspace doesn't exist, create it
-            try {
-                logger_1.Logger.debug(`Creating workspace: ${workspaceName}`);
-                (0, child_process_1.execSync)(`terraform workspace new ${workspaceName}`, {
-                    cwd: workingDir,
-                    stdio: 'inherit',
-                    encoding: 'utf8',
-                });
-                logger_1.Logger.info(`✅ Workspace ${workspaceName} created and selected`);
+            logger_1.Logger.debug(`Creating workspace: ${workspaceName}`);
+            const createResult = (0, child_process_1.spawnSync)('terraform', ['workspace', 'new', workspaceName], {
+                cwd: workingDir,
+                stdio: 'inherit',
+                encoding: 'utf8',
+            });
+            if (createResult.error) {
+                throw createResult.error;
             }
-            catch (error) {
-                logger_1.Logger.error(`Failed to create workspace ${workspaceName}: ${error instanceof Error ? error.message : String(error)}`);
-                throw error;
+            if (createResult.status !== 0) {
+                throw new Error(`Failed to create workspace: ${createResult.stderr?.toString() || 'Unknown error'}`);
             }
+            logger_1.Logger.info(`✅ Workspace ${workspaceName} created and selected`);
+        }
+        catch (error) {
+            logger_1.Logger.error(`Failed to select/create workspace ${workspaceName}: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
         }
     }
     /**
@@ -314,17 +327,35 @@ class TerraformExecutor {
         const terraformArgs = [command, ...args];
         try {
             logger_1.Logger.info(`🚀 Executing: terraform ${terraformArgs.join(' ')}`);
-            (0, child_process_1.execSync)(`terraform ${terraformArgs.join(' ')}`, {
+            // Use spawnSync with array to avoid shell interpretation of special characters
+            // This ensures arguments with brackets, quotes, etc. are passed correctly to terraform
+            const result = (0, child_process_1.spawnSync)('terraform', terraformArgs, {
                 cwd: workingDir,
                 stdio: 'inherit',
                 encoding: 'utf8',
             });
+            if (result.error) {
+                throw result.error;
+            }
+            if (result.status !== 0) {
+                // Check if this is a user cancellation
+                // Terraform exits with code 1 when cancelled and prints "Apply cancelled." etc.
+                // Since we use stdio: 'inherit', terraform's message is already shown to the user
+                // For interactive commands (apply, plan, destroy), exit code 1 often means cancellation
+                const isInteractiveCommand = ['apply', 'plan', 'destroy'].includes(command);
+                if (isInteractiveCommand && result.status === 1) {
+                    // Likely a user cancellation - terraform already printed the message
+                    // Just exit without adding our own error messages
+                    process.exit(1);
+                }
+                // For other errors, throw with status code
+                const error = new Error(`Terraform command failed with exit code ${result.status ?? 'unknown'}`);
+                error.status = result.status ?? undefined;
+                throw error;
+            }
         }
         catch (error) {
             // Check if this is a user cancellation
-            // Terraform exits with code 1 when cancelled and prints "Apply cancelled." etc.
-            // Since we use stdio: 'inherit', terraform's message is already shown to the user
-            // For interactive commands (apply, plan, destroy), exit code 1 often means cancellation
             const exitCode = error.status;
             const isInteractiveCommand = ['apply', 'plan', 'destroy'].includes(command);
             if (isInteractiveCommand && exitCode === 1) {

package/dist/templates/config/README.md.template

@@ -2,6 +2,8 @@
 
 Infrastructure as Code project managed with [Terraflow](https://github.com/salte-common/terraflow).
 
+**Cursor-ready:** This project is scaffolded for [Cursor](https://cursor.com/) with rules for Terraflow, development standards, and AI code tracking. Open in Cursor to get up and running quickly with AI-assisted development.
+
 ## Prerequisites
 
 - [Terraform](https://www.terraform.io/downloads) >= 1.0
@@ -11,7 +13,12 @@ Infrastructure as Code project managed with [Terraflow](https://github.com/salte
 
 ## Getting Started
 
-1. Copy `.env.example` to `.env` and configure your credentials:
+1. **Credentials** (optional if using standard locations):
+   - **AWS:** `~/.aws/credentials` and `~/.aws/config` — no `.env` needed
+   - **Azure:** `az login` — no `.env` needed
+   - **GCP:** `gcloud auth application-default login` — no `.env` needed
+   
+   Otherwise, copy `.env.example` to `.env` and configure your credentials:
    ```bash
    cp .env.example .env
    # Edit .env with your credentials
@@ -19,10 +26,11 @@ Infrastructure as Code project managed with [Terraflow](https://github.com/salte
 
 2. Review and update `.tfwconfig.yml` with your backend configuration
 
-3. Initialize Terraform:
+3. **Initialize Terraform** (optional — runs automatically before plan/apply):
    ```bash
    terraflow init
    ```
+   You can skip this step; Terraflow runs init automatically when needed.
 
 4. Plan your infrastructure:
    ```bash
@@ -67,15 +75,28 @@ terraflow config show
 
 ## Workspace Management
 
-Terraflow automatically derives workspace names from your git branch:
-- Main branch → `main` workspace
-- Feature branches (e.g., `feature/new-api`) → hostname-based workspace
-- Can be overridden with `--workspace` flag
+Terraflow derives workspace names in this order (first match wins):
+
+1. **CLI override** — `--workspace` or `-w`
+2. **Environment variable** — `TERRAFLOW_WORKSPACE`
+3. **Git tag** — if checked out on a tag (e.g. `v1.0.0` → `v1-0-0`)
+4. **Git branch** — if non-ephemeral (e.g. `main`, `my-preview-branch`). Ephemeral branches (`feature/foo`, `fix/bar`) fall through to hostname.
+5. **Hostname** — when none of the above apply (no git repo, no tag, or ephemeral branch)
+
+Examples:
+- `main` → `main` workspace
+- `my-preview-branch` → `my-preview-branch` workspace
+- `feature/new-api` → hostname
+- No git repo → hostname
 
 ## Configuration
 
 See `.tfwconfig.yml` for all available options and the [documentation](https://github.com/salte-common/terraflow/blob/main/docs/configuration.md) for detailed configuration reference.
 
+## Project Specification
+
+You can create a `SPECIFICATION.md` file in the project root to define project-specific requirements, architecture, and conventions. Cursor and other AI tools will read this file to inform code suggestions and maintain consistency with your specification.
+
 ## License
 
 MIT

package/dist/templates/config/cursor-ai-metadata.mdc.template

@@ -0,0 +1,58 @@
+---
+description: How to maintain .ai-metadata.json - MANDATORY AI code tracking
+globs: [".ai-metadata.json", "**/*"]
+alwaysApply: true
+---
+
+# AI Code Tracking — .ai-metadata.json Maintenance
+
+**When you create or modify any file that is checked into source control, you MUST update `.ai-metadata.json` immediately.**
+
+## Scope: Source-Controlled Files Only
+
+**Only track files that are committed to git.** Do NOT add entries for:
+
+- `node_modules/`, `dist/`, `build/`
+- `.env`, `.env.local`, `.env.*.local`
+- `__pycache__/`, `venv/`, `.pytest_cache/`, `*.pyc`
+- `vendor/`, `*.exe`, `*.dylib`
+- `.terraform/`, `*.tfstate`, `*.tfstate.*`
+- `.cursor/` (if excluded from git)
+- Any path listed in `.gitignore`
+
+## Metadata File Structure
+
+```json
+{
+  "files": {
+    "path/to/file.ts": {
+      "lines_total": 100,
+      "lines_ai_generated": 75,
+      "ai_percentage": 75.0,
+      "last_updated": "2024-12-04T15:30:00Z",
+      "tool": "cursor"
+    }
+  },
+  "metadata_version": "1.0"
+}
+```
+
+- `lines_total`: Total lines in the file (read the file to get this)
+- `lines_ai_generated`: Only lines created by AI (cumulative for modified files)
+- `ai_percentage`: `(lines_ai_generated / lines_total) × 100`
+- `last_updated`: ISO 8601 UTC timestamp
+- `tool`: `"cursor"`
+
+## Required Workflow
+
+1. **After creating a new file**: Add entry with `lines_total` = file line count, `lines_ai_generated` = same, `ai_percentage` = 100
+2. **After modifying an existing file**: Read `.ai-metadata.json` for current `lines_ai_generated`, add new AI lines, update `lines_total` from file, recalculate `ai_percentage`
+3. **Preserve existing data**: Merge your changes; do not overwrite other file entries
+4. **Create if missing**: Initialize with `{"files": {}, "metadata_version": "1.0"}`
+
+## DO NOT
+
+- Wait until the end of a task to update metadata
+- Include human-created lines in `lines_ai_generated`
+- Guess `lines_total` — always read the file
+- Track files that are gitignored

package/dist/templates/config/cursor-development-standards.mdc.template

@@ -0,0 +1,57 @@
+---
+description: Development standards — language, runtime, and platform context from scaffold
+globs: ["**/*"]
+alwaysApply: true
+---
+
+# Development Standards
+
+This project was scaffolded with **<language-display>**, **<provider-display>**, and **<test-framework>** as the test framework. Assume these as the default context when suggesting code, tests, or architecture.
+
+## ⚠️ MANDATORY: External Standards Preflight
+
+**Before performing any task, you MUST:**
+
+1. Read [salte-common/standards](https://github.com/salte-common/standards) recursively and confirm compliance.
+2. **Do not proceed until done.** This is a blocking prerequisite.
+3. In your response, cite the specific standards section(s) you applied (e.g. "Per Architecture Standards: ...", "Per Development Standards §X: ...") to prove you reviewed them.
+
+**Required checklist — hard stop if not completed:**
+- [ ] I have reviewed salte-common/standards and confirmed compliance
+- [ ] I have cited the relevant standards section(s) in my response
+
+If you cannot access or read the standards, stop and inform the user. Do not proceed without this confirmation.
+
+## Assumed Context (from `terraflow new`)
+
+| Setting | Value |
+|---------|-------|
+| Language | <language-display> |
+| Runtime | <runtime> |
+| Target Platform | <provider-display> |
+| Test Framework | <test-framework> |
+
+## Project Specification
+
+**Before making significant changes, check for `SPECIFICATION.md` in the project root.** If it exists, read it and apply its requirements. Project-specific specifications override generic standards when they conflict.
+
+## External Standards (salte-common/standards)
+
+Apply as appropriate for the task:
+
+- **Architecture Standards** — Twelve-Factor App, modular design, testing pyramid
+- **Development Standards** — Code formatting, quality, security
+- **<language-standards>** — Language-specific guidelines
+- **<platform-standards>** — Platform-specific deployment and architecture
+- **Deployment Standards** — IaC, CI/CD, environment config
+- **Security Standards** — OWASP Top 10, data protection, API security
+- **Documentation Standards** — README, API docs, code comments
+- **Git Workflow Standards** — Branch strategy, tagging, release process
+
+## When Suggesting Code
+
+1. Use **<language-display>** conventions (runtime: **<runtime>**)
+2. Write tests with **<test-framework>**
+3. Target **<provider-display>** for deployment and infrastructure
+4. Cite the specific salte-common/standards section(s) you applied in your response
+5. Honor `SPECIFICATION.md` if present

package/dist/templates/config/cursor-terraflow-instructions.mdc.template

@@ -0,0 +1,71 @@
+---
+description: How to use Terraflow in this project
+globs: ["**/*.tf", "**/.tfwconfig.yml", "**/terraform/**", "**/.env.example"]
+alwaysApply: false
+---
+
+# Terraflow — Using This Project
+
+This project uses [Terraflow](https://github.com/salte-common/terraflow), an opinionated Terraform CLI wrapper. Use `terraflow` instead of raw `terraform` for plan/apply/destroy — it handles init and workspace selection automatically.
+
+## First-Time Setup
+
+1. `cp .env.example .env` and add your cloud credentials
+2. Edit `.tfwconfig.yml` with your backend bucket/storage and secrets
+3. `terraflow init` — initialize Terraform
+4. `terraflow plan` — verify configuration
+
+## Day-to-Day Commands
+
+```bash
+terraflow plan              # Plan changes (auto init + workspace)
+terraflow apply             # Apply changes
+terraflow destroy           # Destroy infrastructure
+terraflow fmt               # Format Terraform files (no init)
+terraflow config show       # Show resolved config with sources
+terraflow --dry-run plan    # Preview without executing
+```
+
+Prefer `terraflow` over `terraform` for plan/apply/destroy — it runs init and workspace selection when needed.
+
+## Workspace Derivation
+
+Terraflow derives workspaces in this order (first match wins):
+
+1. **CLI** — `--workspace` or `-w`
+2. **Environment** — `TERRAFLOW_WORKSPACE`
+3. **Git tag** — e.g. `v1.0.0` → `v1-0-0`
+4. **Git branch** — if non-ephemeral (e.g. `main`, `my-preview-branch`). Ephemeral branches (`feature/foo`, `fix/bar`) fall through to hostname.
+5. **Hostname** — when none of the above apply (no git repo, no tag, or ephemeral branch)
+
+Override explicitly:
+
+```bash
+terraflow --workspace production plan
+```
+
+## Configuration
+
+- **File:** `.tfwconfig.yml` — backend, secrets, auth, workspace strategy
+- **Hierarchy:** defaults → `.tfwconfig.yml` → `TERRAFLOW_*` env vars → CLI args
+- **Template variables:** `${AWS_REGION}`, `${GITHUB_REPOSITORY}`, `${WORKSPACE}`, etc.
+
+Point users to `.tfwconfig.yml` for backend, secrets, and auth configuration.
+
+## Optional Cleanup
+
+If the project doesn't need certain generated artifacts, you may delete them:
+
+| Delete if... | Files/Directories |
+|--------------|-------------------|
+| No application code (pure Terraform) | `src/` directory |
+| No serverless/lambda functions | Application-specific resources in `terraform/main.tf` |
+| Different structure preferred | `terraform/modules/` (move or inline as needed) |
+
+**Always keep:** `.tfwconfig.yml`, `terraform/_init.tf`, `terraform/inputs.tf` (or equivalent variables).
+
+## When Suggesting Terraflow Usage
+
+- Prefer `terraflow` over raw `terraform` for plan/apply/destroy
+- If generated `src/` or application code is irrelevant, suggest deleting it
+- Point users to `.tfwconfig.yml` for configuration changes

package/dist/templates/config/tfwconfig.yml.template

@@ -12,6 +12,9 @@
 #
 # Environment variables take precedence over this config file.
 
+# Cloud provider (required): aws | gcp | azure
+provider: <cloud-provider>
+
 # Working directory for terraform files (optional - defaults to ./terraform)
 # working-dir: ./terraform
 
@@ -89,7 +92,6 @@
 
 # Validations (optional)
 # validations:
-#   require_git_commit: true
 #   allowed_workspaces:
 #     - development
 #     - staging

package/dist/templates/terraform/aws/_init.tf.template

@@ -12,14 +12,14 @@ terraform {
     }
   }
   
-  backend "s3" {
-    # Backend configuration provided via:
-    # - terraflow CLI flags
-    # - environment variables (TERRAFLOW_*)
-    # - .tfwconfig.yml
-    # 
-    # Do not hardcode values here
-  }
+  # Uncomment when ready for remote state. Configure in .tfwconfig.yml
+  # backend "s3" {
+  #   # Backend configuration provided via:
+  #   # - terraflow CLI flags
+  #   # - environment variables (TERRAFLOW_*)
+  #   # - .tfwconfig.yml
+  #   # Do not hardcode values here
+  # }
 }
 
 provider "aws" {

package/dist/templates/terraform/azure/_init.tf.template

@@ -12,9 +12,10 @@ terraform {
     }
   }
   
-  backend "azurerm" {
-    # Backend configuration provided via terraflow
-  }
+  # Uncomment when ready for remote state. Configure in .tfwconfig.yml
+  # backend "azurerm" {
+  #   # Backend configuration provided via terraflow
+  # }
 }
 
 provider "azurerm" {

package/dist/templates/terraform/gcp/_init.tf.template

@@ -12,9 +12,10 @@ terraform {
     }
   }
   
-  backend "gcs" {
-    # Backend configuration provided via terraflow
-  }
+  # Uncomment when ready for remote state. Configure in .tfwconfig.yml
+  # backend "gcs" {
+  #   # Backend configuration provided via terraflow
+  # }
 }
 
 provider "google" {

package/dist/templates/terraform/gcp/main.tf.template

@@ -1,9 +1,11 @@
 # Service Account for Cloud Function
 resource "google_service_account" "function" {
-  account_id   = "${replace(local.project_name, "-", "")}-${replace(terraform.workspace, "-", "")}-sa"
+  # account_id must match regex: ^[a-z](?:[-a-z0-9]{4,28}[a-z0-9])$
+  # Must start with lowercase letter, 6-30 chars, end with letter/number
+  account_id   = "${replace(local.sanitized_project_name, "-", "")}${replace(local.sanitized_workspace, "-", "")}sa"
   display_name = "${local.project_name} ${terraform.workspace} Function Service Account"
 
-  labels = local.common_tags
+  # Note: google_service_account does not support labels
 }
 
 # IAM binding for service account to invoke Cloud Functions
@@ -15,7 +17,7 @@ resource "google_project_iam_member" "function_invoker" {
 
 # Storage bucket for function source code
 resource "google_storage_bucket" "function_source" {
-  name     = "${replace(local.project_name, "-", "")}-${replace(terraform.workspace, "-", "")}-funcs-source"
+  name     = "${replace(local.sanitized_project_name, "-", "")}-${replace(local.sanitized_workspace, "-", "")}-funcs-source"
   location = var.gcp_region
 
   uniform_bucket_level_access = true
@@ -38,7 +40,7 @@ resource "google_storage_bucket_object" "function_source" {
   source = data.archive_file.function_zip.output_path
 }
 
-# Cloud Function
+# Cloud Function (HTTP-triggered)
 resource "google_cloudfunctions_function" "main" {
   name        = "${local.project_name}-${terraform.workspace}-function"
   description = "Serverless function for ${local.project_name}"
@@ -47,9 +49,9 @@ resource "google_cloudfunctions_function" "main" {
   available_memory_mb   = 256
   source_archive_bucket = google_storage_bucket.function_source.name
   source_archive_object = google_storage_bucket_object.function_source.name
-  trigger {
-    http_trigger {}
-  }
+  
+  # HTTP-triggered (default when no event_trigger is specified)
+  # No https_trigger block needed for v1 - function is HTTP-triggered by default
 
   entry_point = "handler"
 

package/dist/templates/terraform/locals.tf.template

@@ -2,6 +2,11 @@ locals {
   # Project name for resource naming
   project_name = "<project-name>"
   
+  # Sanitized names for GCP resources (lowercase, hyphens replaced with dashes)
+  # GCP requires lowercase alphanumeric with dashes for many resource names
+  sanitized_project_name = lower(replace("<project-name>", "_", "-"))
+  sanitized_workspace    = lower(replace(terraform.workspace, "_", "-"))
+  
   # Common tags/labels for all resources
   common_tags = {
     Workspace   = terraform.workspace

package/dist/types/config.d.ts

@@ -59,8 +59,6 @@ export interface LoggingConfig {
  * Validation configuration
  */
 export interface ValidationConfig {
-    /** Require git commit before apply/destroy */
-    require_git_commit?: boolean;
     /** List of allowed workspace names (empty = allow all) */
     allowed_workspaces?: string[];
 }
@@ -68,6 +66,8 @@ export interface ValidationConfig {
  * Main Terraflow configuration file structure
  */
 export interface TerraflowConfig {
+    /** Cloud provider: aws | gcp | azure (required) */
+    provider: 'aws' | 'gcp' | 'azure';
     /** Workspace name */
     workspace?: string;
     /** Terraform working directory */

package/dist/utils/cloud.d.ts

@@ -8,10 +8,13 @@ import type { CloudInfo } from '../types/context.js';
  */
 export declare class CloudUtils {
     /**
-     * Detect cloud provider from environment
+     * Detect cloud provider from configuration or environment
+     * @param config - Optional Terraflow configuration
      * @returns Cloud information
      */
-    static detectCloud(): Promise<CloudInfo>;
+    static detectCloud(config?: {
+        provider?: 'aws' | 'gcp' | 'azure';
+    }): Promise<CloudInfo>;
     /**
      * Get AWS account ID via `aws sts get-caller-identity`
      * @returns AWS account ID or undefined

package/dist/utils/cloud.js

@@ -11,13 +11,48 @@ const child_process_1 = require("child_process");
  */
 class CloudUtils {
     /**
-     * Detect cloud provider from environment
+     * Detect cloud provider from configuration or environment
+     * @param config - Optional Terraflow configuration
      * @returns Cloud information
      */
-    static async detectCloud() {
+    static async detectCloud(config) {
         const cloud = {
             provider: 'none',
         };
+        // If provider is specified in config, use it as primary source
+        if (config?.provider) {
+            cloud.provider = config.provider;
+            if (config.provider === 'aws') {
+                cloud.awsRegion = CloudUtils.getAwsRegion();
+                try {
+                    cloud.awsAccountId = await CloudUtils.getAwsAccountId();
+                }
+                catch {
+                    // Account ID fetch failed, continue without it
+                }
+                return cloud;
+            }
+            else if (config.provider === 'azure') {
+                try {
+                    cloud.azureSubscriptionId = await CloudUtils.getAzureSubscriptionId();
+                    cloud.azureTenantId = await CloudUtils.getAzureTenantId();
+                }
+                catch {
+                    // Subscription/Tenant ID fetch failed, continue without it
+                }
+                return cloud;
+            }
+            else if (config.provider === 'gcp') {
+                try {
+                    cloud.gcpProjectId = await CloudUtils.getGcpProjectId();
+                }
+                catch {
+                    // Project ID fetch failed, continue without it
+                }
+                return cloud;
+            }
+        }
+        // Fallback to environment-based detection (for backwards compatibility)
         // Check for AWS
         if (process.env.AWS_ACCESS_KEY_ID || process.env.AWS_PROFILE || process.env.AWS_REGION) {
             cloud.provider = 'aws';

package/dist/utils/scaffolding.d.ts

@@ -43,6 +43,14 @@ export declare function generateApplicationFiles(projectDir: string, language: s
  * @param projectName - Name of the project
  */
 export declare function generateConfigFiles(projectDir: string, provider: string, language: string, projectName: string): Promise<void>;
+/**
+ * Generate initial .ai-metadata.json with stats for all scaffolded files
+ * All scaffolded files are treated as 100% AI-authored (from templates)
+ * Only tracks files that are checked into source control
+ * @param projectDir - Root directory of the project
+ * @param language - Programming language (javascript, typescript, python, go)
+ */
+export declare function generateAiMetadata(projectDir: string, language: string): Promise<void>;
 /**
  * Project structure creation
  */

package/dist/utils/scaffolding.js

@@ -9,6 +9,7 @@ exports.processTemplate = processTemplate;
 exports.generateTerraformFiles = generateTerraformFiles;
 exports.generateApplicationFiles = generateApplicationFiles;
 exports.generateConfigFiles = generateConfigFiles;
+exports.generateAiMetadata = generateAiMetadata;
 exports.createProjectStructure = createProjectStructure;
 exports.validateProjectName = validateProjectName;
 exports.validateProvider = validateProvider;
@@ -254,6 +255,72 @@ function getBackendType(provider) {
             return 'local';
     }
 }
+/**
+ * Build template variables for development standards Cursor rules
+ * @param language - Programming language (javascript, typescript, python, go)
+ * @param provider - Cloud provider (aws, azure, gcp)
+ * @returns Variables for cursor-development-standards.mdc.template
+ */
+function getDevelopmentStandardsVariables(language, provider) {
+    const languageMap = {
+        javascript: {
+            display: 'JavaScript',
+            testFramework: 'Jest',
+            runtime: 'Node.js',
+            standards: 'JavaScript Standards',
+        },
+        typescript: {
+            display: 'TypeScript',
+            testFramework: 'Jest',
+            runtime: 'Node.js',
+            standards: 'JavaScript Standards',
+        },
+        python: {
+            display: 'Python',
+            testFramework: 'pytest',
+            runtime: 'Python',
+            standards: 'Python Standards',
+        },
+        go: {
+            display: 'Go',
+            testFramework: 'go test',
+            runtime: 'Go',
+            standards: 'Development Standards',
+        },
+    };
+    const providerMap = {
+        aws: {
+            display: 'AWS',
+            platformStandards: 'AWS Architecture Standards',
+        },
+        azure: {
+            display: 'Azure',
+            platformStandards: 'Azure deployment and architecture patterns',
+        },
+        gcp: {
+            display: 'GCP',
+            platformStandards: 'GCP deployment and architecture patterns',
+        },
+    };
+    const lang = languageMap[language] ?? {
+        display: language,
+        testFramework: 'tests',
+        runtime: language,
+        standards: 'Development Standards',
+    };
+    const prov = providerMap[provider] ?? {
+        display: provider,
+        platformStandards: 'platform-specific standards',
+    };
+    return {
+        'language-display': lang.display,
+        'provider-display': prov.display,
+        'test-framework': lang.testFramework,
+        runtime: lang.runtime,
+        'language-standards': lang.standards,
+        'platform-standards': prov.platformStandards,
+    };
+}
 /**
  * Generate configuration files for the project
  * @param projectDir - Root directory of the project
@@ -270,6 +337,7 @@ async function generateConfigFiles(projectDir, provider, language, projectName)
     const tfwconfigContent = processTemplate(tfwconfigTemplate, {
         'project-name': projectName,
         provider: backendType,
+        'cloud-provider': provider, // Add provider field
     });
     (0, fs_1.writeFileSync)((0, path_1.join)(projectDir, '.tfwconfig.yml'), tfwconfigContent);
     // .env.example
@@ -286,8 +354,106 @@ async function generateConfigFiles(projectDir, provider, language, projectName)
         provider: provider, // Use original provider name for README
     });
     (0, fs_1.writeFileSync)((0, path_1.join)(projectDir, 'README.md'), readmeContent);
+    // .cursor/rules/terraform.mdc - Cursor instructions for Terraflow usage
+    const cursorRulesDir = (0, path_1.join)(projectDir, '.cursor', 'rules');
+    (0, fs_1.mkdirSync)(cursorRulesDir, { recursive: true });
+    const cursorRulesTemplate = loadTemplate((0, path_1.join)(templatesDir, 'cursor-terraflow-instructions.mdc.template'));
+    (0, fs_1.writeFileSync)((0, path_1.join)(cursorRulesDir, 'terraform.mdc'), cursorRulesTemplate);
+    // .cursor/rules/ai-metadata.mdc - Cursor instructions for .ai-metadata.json maintenance
+    const aiMetadataRulesTemplate = loadTemplate((0, path_1.join)(templatesDir, 'cursor-ai-metadata.mdc.template'));
+    (0, fs_1.writeFileSync)((0, path_1.join)(cursorRulesDir, 'ai-metadata.mdc'), aiMetadataRulesTemplate);
+    // .cursor/rules/development-standards.mdc - Cursor instructions for development standards
+    const devStandardsTemplate = loadTemplate((0, path_1.join)(templatesDir, 'cursor-development-standards.mdc.template'));
+    const devStandardsVars = getDevelopmentStandardsVariables(language, provider);
+    const devStandardsContent = processTemplate(devStandardsTemplate, devStandardsVars);
+    (0, fs_1.writeFileSync)((0, path_1.join)(cursorRulesDir, 'development-standards.mdc'), devStandardsContent);
     logger_1.Logger.debug('Configuration files generated successfully');
 }
+/**
+ * Get list of scaffolded file paths (relative to project root) for AI metadata
+ * Only includes files that are checked into source control
+ * @param language - Programming language (javascript, typescript, python, go)
+ * @returns Array of relative file paths
+ */
+function getScaffoldedFilePaths(language) {
+    const common = [
+        '.tfwconfig.yml',
+        '.env.example',
+        '.gitignore',
+        'README.md',
+        '.cursor/rules/terraform.mdc',
+        '.cursor/rules/ai-metadata.mdc',
+        '.cursor/rules/development-standards.mdc',
+        'terraform/_init.tf',
+        'terraform/inputs.tf',
+        'terraform/locals.tf',
+        'terraform/main.tf',
+        'terraform/outputs.tf',
+        'terraform/modules/inputs.tf',
+        'terraform/modules/main.tf',
+        'terraform/modules/outputs.tf',
+    ];
+    const languageFiles = {
+        javascript: [
+            'src/main/index.js',
+            'src/test/index.spec.js',
+            'package.json',
+            '.eslintrc.json',
+            'jest.config.js',
+            '.prettierrc',
+        ],
+        typescript: [
+            'src/main/index.ts',
+            'src/test/index.spec.ts',
+            'package.json',
+            'tsconfig.json',
+            '.eslintrc.json',
+            'jest.config.js',
+            '.prettierrc',
+        ],
+        python: [
+            'src/main/index.py',
+            'src/test/test_main.py',
+            'requirements.txt',
+            'pytest.ini',
+            '.pylintrc',
+        ],
+        go: ['src/main/index.go', 'src/test/main_test.go', 'go.mod', '.golangci.yml'],
+    };
+    return [...common, ...(languageFiles[language] ?? [])];
+}
+/**
+ * Generate initial .ai-metadata.json with stats for all scaffolded files
+ * All scaffolded files are treated as 100% AI-authored (from templates)
+ * Only tracks files that are checked into source control
+ * @param projectDir - Root directory of the project
+ * @param language - Programming language (javascript, typescript, python, go)
+ */
+async function generateAiMetadata(projectDir, language) {
+    const filePaths = getScaffoldedFilePaths(language);
+    const files = {};
+    const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+    for (const relPath of filePaths) {
+        const fullPath = (0, path_1.join)(projectDir, relPath);
+        if (!(0, fs_1.existsSync)(fullPath))
+            continue;
+        const content = (0, fs_1.readFileSync)(fullPath, 'utf8');
+        const linesTotal = content.split(/\r?\n/).length;
+        files[relPath] = {
+            lines_total: linesTotal,
+            lines_ai_generated: linesTotal,
+            ai_percentage: 100,
+            last_updated: timestamp,
+            tool: 'cursor',
+        };
+    }
+    const metadata = {
+        files,
+        metadata_version: '1.0',
+    };
+    (0, fs_1.writeFileSync)((0, path_1.join)(projectDir, '.ai-metadata.json'), JSON.stringify(metadata, null, 2));
+    logger_1.Logger.debug('Initial .ai-metadata.json generated');
+}
 /**
  * Project structure creation
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salte-common/terraflow",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.7",
   "description": "Opinionated Terraform workflow CLI with multi-cloud support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",