@causa/workspace-terraform 0.1.0 → 0.2.0

package/README.md

@@ -1 +1,35 @@
 # `@causa/workspace-terraform` module
+
+This repository contains the source code for the `@causa/workspace-terraform` Causa module. It provides Causa features and implementations of `cs` commands for Terraform infrastructure projects. For more information about the Causa CLI `cs`, checkout [its repository](https://github.com/causa-io/cli).
+
+## ➕ Requirements
+
+The Causa Terraform module requires [Terraform](https://www.terraform.io/) to be installed.
+
+## 🎉 Installation
+
+Add `@causa/workspace-terraform` to your Causa configuration in `causa.modules`.
+
+## 🔧 Configuration
+
+For all the configuration in your Causa files related to Terraform, look at [the schema for the `TerraformConfiguration`](./src/configurations/terraform.ts).
+
+## ✨ Supported project types and commands
+
+This module supports Causa projects with `project.type` set to `infrastructure` and `project.language` set to `terraform`.
+
+### Infrastructure commands
+
+- `cs infrastructure prepare`: Runs `terraform plan`.
+- `cs infrastructure deploy`: Runs `terraform apply` using a previously computed plan.
+
+The dictionary defined in the `infrastructure.variables` configuration can be used to pass input Terraform variables. This dictionary is rendered before being used, meaning it can contain formatting templates referencing other configuration values and secrets.
+
+The `terraform.workspace` configuration determines the Terraform workspace set prior to running any operation. Combined with Causa environments, this can be a powerful feature to manage the infrastructure of several deployment environments.
+
+### Project commands
+
+The Terraform module also supports some of the project-level commands, namely:
+
+- `cs init`: Runs `terraform init`.
+- `cs lint`: Runs `terraform validate` and `terraform fmt`. The format operation is run with the `-check` argument, such that it only lints the code without fixing it. This operation applies supports the `project.additionalDirectories` configuration.

package/dist/configurations/terraform.d.ts

@@ -10,5 +10,12 @@ export type TerraformConfiguration = {
          * The Terraform workspace that should be selected prior to performing `plan` and `apply` operations.
          */
         workspace?: string;
+        /**
+         * The version of Terraform to use.
+         * Can be a semver version, or `latest`.
+         * The installed version is considered compatible if it is greater than or equal to the configured version, within
+         * the same major version.
+         */
+        version?: string;
     };
 };

package/dist/functions/index.js

@@ -1,5 +1,7 @@
 import { InfrastructureDeployForTerraform } from './infrastructure-deploy-terraform.js';
 import { InfrastructurePrepareForTerraform } from './infrastructure-prepare-terraform.js';
+import { ProjectInitForTerraform } from './project-init-terraform.js';
+import { ProjectLintForTerraform } from './project-lint-terraform.js';
 export function registerFunctions(context) {
-    context.registerFunctionImplementations(InfrastructureDeployForTerraform, InfrastructurePrepareForTerraform);
+    context.registerFunctionImplementations(InfrastructureDeployForTerraform, InfrastructurePrepareForTerraform, ProjectInitForTerraform, ProjectLintForTerraform);
 }

package/dist/functions/project-init-terraform.d.ts

@@ -0,0 +1,9 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { ProjectInit } from '@causa/workspace-core';
+/**
+ * Implements the {@link ProjectInit} function for Terraform projects, by running `terraform init`.
+ */
+export declare class ProjectInitForTerraform extends ProjectInit {
+    _call(context: WorkspaceContext): Promise<void>;
+    _supports(context: WorkspaceContext): boolean;
+}

package/dist/functions/project-init-terraform.js

@@ -0,0 +1,28 @@
+import { ProjectInit } from '@causa/workspace-core';
+import { rm } from 'fs/promises';
+import { join } from 'path';
+import { TerraformService } from '../services/index.js';
+/**
+ * The name of the folder automatically created by Terraform during initialization.
+ */
+const TERRAFORM_DIR = '.terraform';
+/**
+ * Implements the {@link ProjectInit} function for Terraform projects, by running `terraform init`.
+ */
+export class ProjectInitForTerraform extends ProjectInit {
+    async _call(context) {
+        const projectName = context.get('project.name');
+        if (this.force) {
+            context.logger.info('🔥 Removing Terraform folder.');
+            const terraformDir = join(context.getProjectPathOrThrow(), TERRAFORM_DIR);
+            await rm(terraformDir, { recursive: true, force: true });
+        }
+        context.logger.info(`️🎉 Initializing Terraform for project '${projectName}'.`);
+        await context.service(TerraformService).init({ logging: 'debug' });
+        context.logger.info(`️✅ Successfully initialized Terraform.`);
+    }
+    _supports(context) {
+        return (context.get('project.language') === 'terraform' &&
+            context.get('project.type') === 'infrastructure');
+    }
+}

package/dist/functions/project-lint-terraform.d.ts

@@ -0,0 +1,11 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { ProjectLint } from '@causa/workspace-core';
+/**
+ * Implements the {@link ProjectLint} function for Terraform projects, by running `terraform validate` and
+ * `terraform fmt`.
+ * The Terraform format check is also run on any additional directories listed in the project configuration.
+ */
+export declare class ProjectLintForTerraform extends ProjectLint {
+    _call(context: WorkspaceContext): Promise<void>;
+    _supports(context: WorkspaceContext): boolean;
+}

package/dist/functions/project-lint-terraform.js

@@ -0,0 +1,41 @@
+import { ProcessServiceExitCodeError, ProjectLint, } from '@causa/workspace-core';
+import { TerraformService } from '../services/index.js';
+/**
+ * Implements the {@link ProjectLint} function for Terraform projects, by running `terraform validate` and
+ * `terraform fmt`.
+ * The Terraform format check is also run on any additional directories listed in the project configuration.
+ */
+export class ProjectLintForTerraform extends ProjectLint {
+    async _call(context) {
+        const projectPath = context.getProjectPathOrThrow();
+        const projectName = context.get('project.name');
+        const terraformService = context.service(TerraformService);
+        const targets = [
+            projectPath,
+            ...(await context.getProjectAdditionalDirectories()),
+        ];
+        try {
+            context.logger.info(`🚨 Validating Terraform code for project '${projectName}'.`);
+            await terraformService.validate({
+                logging: { stdout: null, stderr: 'info' },
+            });
+            context.logger.info(`🎨 Checking format of Terraform code for project '${projectName}'.`);
+            await terraformService.fmt({
+                check: true,
+                recursive: true,
+                targets,
+                logging: 'info',
+            });
+        }
+        catch (error) {
+            if (error instanceof ProcessServiceExitCodeError) {
+                throw new Error('Linting the Terraform project failed.');
+            }
+            throw error;
+        }
+    }
+    _supports(context) {
+        return (context.get('project.language') === 'terraform' &&
+            context.get('project.type') === 'infrastructure');
+    }
+}

package/dist/services/index.d.ts

@@ -1 +1,2 @@
+export * from './terraform.errors.js';
 export { TerraformService } from './terraform.js';

package/dist/services/index.js

@@ -1 +1,2 @@
+export * from './terraform.errors.js';
 export { TerraformService } from './terraform.js';

package/dist/services/terraform.d.ts

@@ -39,6 +39,11 @@ export declare class TerraformService {
      * This is used by {@link TerraformService.wrapWorkspaceOperation} if no workspace is specified.
      */
     private readonly defaultTerraformWorkspace;
+    /**
+     * The required Terraform version set in the configuration.
+     * Defaults to `latest`.
+     */
+    readonly requiredVersion: string;
     constructor(context: WorkspaceContext);
     /**
      * Runs `terraform init`.
@@ -95,6 +100,32 @@ export declare class TerraformService {
      * @returns The standard output of the command, describing the plan.
      */
     show(path: string, options?: Omit<SpawnOptions, 'capture'>): Promise<string>;
+    /**
+     * Runs `terraform validate`.
+     *
+     * @param options Options when running the command.
+     */
+    validate(options?: SpawnOptions): Promise<void>;
+    /**
+     * Runs `terraform fmt`.
+     *
+     * @param options Options when running the command.
+     * @returns The result of the Terraform process.
+     */
+    fmt(options?: {
+        /**
+         * Whether to check if the files are formatted correctly, instead of formatting them.
+         */
+        check?: boolean;
+        /**
+         * Whether to recursively format all files in the current directory and its subdirectories.
+         */
+        recursive?: boolean;
+        /**
+         * The list of files or directories to format.
+         */
+        targets?: string[];
+    } & SpawnOptions): Promise<SpawnedProcessResult>;
     /**
      * Wrap the `fn` function and ensures Terraform is initialized and that the correct Terraform workspace is selected.
      * After `fn` has run, the workspace is reverted back to the previous workspace if necessary.
@@ -121,5 +152,23 @@ export declare class TerraformService {
      * @returns The result of the spawned process.
      */
     terraform(command: string, args: string[], options?: SpawnOptions): Promise<SpawnedProcessResult>;
+    /**
+     * Whether the installed Terraform version is compatible with the required version set in the configuration.
+     * It is `undefined` before the first call to {@link TerraformService.checkTerraformVersion}.
+     */
+    private hasCompatibleTerraformVersion;
+    /**
+     * A promise that resolves when the installed Terraform version has been checked.
+     * It is `undefined` before the first call to {@link TerraformService.checkTerraformVersion}, or if the actual check
+     * is not needed.
+     */
+    private terraformVersionCheck;
+    /**
+     * Checks whether the installed Terraform version is compatible with the required version set in the configuration.
+     * If the required version is `latest`, the check is skipped.
+     * If the installed version is not compatible, an {@link IncompatibleTerraformVersionError} is thrown.
+     * The result of the check is cached, and this returns synchronously on subsequent calls.
+     */
+    private checkTerraformVersion;
 }
 export {};

package/dist/services/terraform.errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * An error thrown when the installed Terraform version is incompatible with the required version set in the
+ * configuration.
+ */
+export declare class IncompatibleTerraformVersionError extends Error {
+    readonly installedVersion: string;
+    readonly requiredVersion: string;
+    constructor(installedVersion: string, requiredVersion: string);
+}

package/dist/services/terraform.errors.js

@@ -0,0 +1,13 @@
+/**
+ * An error thrown when the installed Terraform version is incompatible with the required version set in the
+ * configuration.
+ */
+export class IncompatibleTerraformVersionError extends Error {
+    installedVersion;
+    requiredVersion;
+    constructor(installedVersion, requiredVersion) {
+        super(`Installed Terraform version ${installedVersion} is incompatible with required version ${requiredVersion}.`);
+        this.installedVersion = installedVersion;
+        this.requiredVersion = requiredVersion;
+    }
+}

package/dist/services/terraform.js

@@ -1,4 +1,6 @@
 import { ProcessService, ProcessServiceExitCodeError, } from '@causa/workspace-core';
+import { satisfies } from 'semver';
+import { IncompatibleTerraformVersionError } from './terraform.errors.js';
 /**
  * A service exposing the Terraform CLI.
  */
@@ -21,15 +23,20 @@ export class TerraformService {
      * This is used by {@link TerraformService.wrapWorkspaceOperation} if no workspace is specified.
      */
     defaultTerraformWorkspace;
+    /**
+     * The required Terraform version set in the configuration.
+     * Defaults to `latest`.
+     */
+    requiredVersion;
     constructor(context) {
         this.processService = context.service(ProcessService);
         this.defaultSpawnOptions = {
             workingDirectory: context.projectPath ?? undefined,
         };
         this.logger = context.logger;
-        this.defaultTerraformWorkspace = context
-            .asConfiguration()
-            .getOrThrow('terraform.workspace');
+        const conf = context.asConfiguration();
+        this.defaultTerraformWorkspace = conf.get('terraform.workspace');
+        this.requiredVersion = conf.get('terraform.version') ?? 'latest';
     }
     /**
      * Runs `terraform init`.
@@ -115,14 +122,44 @@ export class TerraformService {
         });
         return result.stdout ?? '';
     }
+    /**
+     * Runs `terraform validate`.
+     *
+     * @param options Options when running the command.
+     */
+    async validate(options = {}) {
+        await this.terraform('validate', [], options);
+    }
+    /**
+     * Runs `terraform fmt`.
+     *
+     * @param options Options when running the command.
+     * @returns The result of the Terraform process.
+     */
+    async fmt(options = {}) {
+        const args = [];
+        if (options.check) {
+            args.push('-check');
+        }
+        if (options.recursive) {
+            args.push('-recursive');
+        }
+        if (options.targets) {
+            args.push(...options.targets);
+        }
+        return await this.terraform('fmt', args, options);
+    }
     async wrapWorkspaceOperation(optionsOrFn, fn) {
         const options = fn ? optionsOrFn : {};
         const func = fn ?? optionsOrFn;
         const { skipInit, createWorkspaceIfNeeded, workspace, ...spawnOptions } = options;
+        const workspaceToSelect = workspace ?? this.defaultTerraformWorkspace;
+        if (workspaceToSelect === undefined) {
+            throw new Error('The Terraform workspace for the operation is not configured.');
+        }
         if (!skipInit) {
             await this.init(spawnOptions);
         }
-        const workspaceToSelect = workspace ?? this.defaultTerraformWorkspace;
         let workspaceToRestore = null;
         try {
             const currentWorkspace = await this.workspaceShow(spawnOptions);
@@ -155,10 +192,48 @@ export class TerraformService {
      * @returns The result of the spawned process.
      */
     async terraform(command, args, options = {}) {
+        await this.checkTerraformVersion();
         const p = this.processService.spawn('terraform', [command, ...args], {
             ...this.defaultSpawnOptions,
             ...options,
         });
         return await p.result;
     }
+    /**
+     * Whether the installed Terraform version is compatible with the required version set in the configuration.
+     * It is `undefined` before the first call to {@link TerraformService.checkTerraformVersion}.
+     */
+    hasCompatibleTerraformVersion;
+    /**
+     * A promise that resolves when the installed Terraform version has been checked.
+     * It is `undefined` before the first call to {@link TerraformService.checkTerraformVersion}, or if the actual check
+     * is not needed.
+     */
+    terraformVersionCheck;
+    /**
+     * Checks whether the installed Terraform version is compatible with the required version set in the configuration.
+     * If the required version is `latest`, the check is skipped.
+     * If the installed version is not compatible, an {@link IncompatibleTerraformVersionError} is thrown.
+     * The result of the check is cached, and this returns synchronously on subsequent calls.
+     */
+    async checkTerraformVersion() {
+        if (this.hasCompatibleTerraformVersion === true) {
+            return;
+        }
+        if (this.requiredVersion === 'latest') {
+            this.hasCompatibleTerraformVersion = true;
+            return;
+        }
+        if (!this.terraformVersionCheck) {
+            this.terraformVersionCheck = (async () => {
+                const result = await this.processService.spawn('terraform', ['-version', '-json'], { capture: { stdout: true } }).result;
+                const version = JSON.parse(result.stdout ?? '').terraform_version;
+                this.hasCompatibleTerraformVersion = satisfies(version, `^${this.requiredVersion}`);
+                if (!this.hasCompatibleTerraformVersion) {
+                    throw new IncompatibleTerraformVersionError(version, this.requiredVersion);
+                }
+            })();
+        }
+        await this.terraformVersionCheck;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causa/workspace-terraform",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The Causa workspace module providing functionalities for infrastructure projects coded in Terraform.",
   "repository": "github:causa-io/workspace-module-terraform",
   "license": "ISC",
@@ -28,22 +28,24 @@
     "test:cov": "npm run test -- --coverage"
   },
   "dependencies": {
-    "@causa/cli": ">= 0.2.1 < 1.0.0",
-    "@causa/workspace": ">= 0.4.0 < 1.0.0",
-    "@causa/workspace-core": ">= 0.1.0 < 1.0.0",
-    "pino": "^8.14.1"
+    "@causa/workspace": ">= 0.10.0 < 1.0.0",
+    "@causa/workspace-core": ">= 0.7.0 < 1.0.0",
+    "pino": "^8.14.1",
+    "semver": "^7.5.1"
   },
   "devDependencies": {
     "@tsconfig/node18": "^2.0.1",
-    "@types/jest": "^29.5.1",
-    "eslint": "^8.40.0",
+    "@types/jest": "^29.5.2",
+    "@types/node": "^18.16.14",
+    "@typescript-eslint/eslint-plugin": "^5.59.9",
+    "eslint": "^8.42.0",
     "eslint-config-prettier": "^8.8.0",
     "eslint-plugin-prettier": "^4.2.1",
     "jest": "^29.5.0",
-    "jest-extended": "^3.2.4",
-    "rimraf": "^5.0.0",
+    "jest-extended": "^4.0.0",
+    "rimraf": "^5.0.1",
     "ts-jest": "^29.1.0",
     "ts-node": "^10.9.1",
-    "typescript": "^5.0.4"
+    "typescript": "^5.1.3"
   }
 }