@causa/workspace-terraform 0.1.0

package/LICENSE.md

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2023 Causa
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# `@causa/workspace-terraform` module

package/dist/configurations/index.d.ts

@@ -0,0 +1 @@
+export { TerraformConfiguration } from './terraform.js';

package/dist/configurations/index.js

@@ -0,0 +1 @@
+export {};

package/dist/configurations/terraform.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The schema for the Terraform configuration.
+ */
+export type TerraformConfiguration = {
+    /**
+     * Configuration for Terraform.
+     */
+    terraform?: {
+        /**
+         * The Terraform workspace that should be selected prior to performing `plan` and `apply` operations.
+         */
+        workspace?: string;
+    };
+};

package/dist/configurations/terraform.js

@@ -0,0 +1 @@
+export {};

package/dist/functions/index.d.ts

@@ -0,0 +1,2 @@
+import { ModuleRegistrationContext } from '@causa/workspace';
+export declare function registerFunctions(context: ModuleRegistrationContext): void;

package/dist/functions/index.js

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

package/dist/functions/infrastructure-deploy-terraform.d.ts

@@ -0,0 +1,10 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { InfrastructureDeploy } from '@causa/workspace-core';
+/**
+ * Implements the {@link InfrastructureDeploy} function for Infrastructure as Code defined using Terraform.
+ * This calls the `terraform apply` command for the given project.
+ */
+export declare class InfrastructureDeployForTerraform extends InfrastructureDeploy {
+    _call(context: WorkspaceContext): Promise<void>;
+    _supports(context: WorkspaceContext): boolean;
+}

package/dist/functions/infrastructure-deploy-terraform.js

@@ -0,0 +1,22 @@
+import { InfrastructureDeploy } from '@causa/workspace-core';
+import { resolve } from 'path';
+import { TerraformService } from '../services/index.js';
+/**
+ * Implements the {@link InfrastructureDeploy} function for Infrastructure as Code defined using Terraform.
+ * This calls the `terraform apply` command for the given project.
+ */
+export class InfrastructureDeployForTerraform extends InfrastructureDeploy {
+    async _call(context) {
+        context.getProjectPathOrThrow();
+        const projectName = context.getOrThrow('project.name');
+        const terraformService = context.service(TerraformService);
+        context.logger.info(`🧱 Applying Terraform plan for project '${projectName}'.`);
+        const plan = resolve(this.deployment);
+        await terraformService.wrapWorkspaceOperation(() => terraformService.apply(plan, { logging: 'info' }));
+        context.logger.info('🧱 Successfully applied Terraform plan.');
+    }
+    _supports(context) {
+        return (context.get('project.language') === 'terraform' &&
+            context.get('project.type') === 'infrastructure');
+    }
+}

package/dist/functions/infrastructure-prepare-terraform.d.ts

@@ -0,0 +1,13 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { InfrastructurePrepare } from '@causa/workspace-core';
+/**
+ * Implements the {@link InfrastructurePrepare} function for Infrastructure as Code defined using Terraform.
+ * This calls the `terraform plan` command for the given project.
+ */
+export declare class InfrastructurePrepareForTerraform extends InfrastructurePrepare {
+    _call(context: WorkspaceContext): Promise<{
+        output: string;
+        isDeploymentNeeded: boolean;
+    }>;
+    _supports(context: WorkspaceContext): boolean;
+}

package/dist/functions/infrastructure-prepare-terraform.js

@@ -0,0 +1,38 @@
+import { InfrastructurePrepare, } from '@causa/workspace-core';
+import { resolve } from 'path';
+import { TerraformService } from '../services/index.js';
+/**
+ * The default name of the output Terraform plan file.
+ */
+const DEFAULT_PLAN_FILE = 'plan.out';
+/**
+ * Implements the {@link InfrastructurePrepare} function for Infrastructure as Code defined using Terraform.
+ * This calls the `terraform plan` command for the given project.
+ */
+export class InfrastructurePrepareForTerraform extends InfrastructurePrepare {
+    async _call(context) {
+        context.getProjectPathOrThrow();
+        const infrastructureConf = context.asConfiguration();
+        const projectName = infrastructureConf.getOrThrow('project.name');
+        const terraformService = context.service(TerraformService);
+        const variables = (await infrastructureConf.getAndRender('infrastructure.variables')) ?? {};
+        const output = resolve(this.output ?? DEFAULT_PLAN_FILE);
+        context.logger.info(`🧱 Planning Terraform deployment for project '${projectName}'.`);
+        const isDeploymentNeeded = await terraformService.wrapWorkspaceOperation({ createWorkspaceIfNeeded: true }, () => terraformService.plan(output, { variables }));
+        if (isDeploymentNeeded) {
+            context.logger.info('🧱 Terraform plan has changes that can be deployed.');
+            if (this.print) {
+                const show = await terraformService.show(output);
+                console.log(show);
+            }
+        }
+        else {
+            context.logger.info('🧱 Terraform plan has no change.');
+        }
+        return { output, isDeploymentNeeded };
+    }
+    _supports(context) {
+        return (context.get('project.language') === 'terraform' &&
+            context.get('project.type') === 'infrastructure');
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { ModuleRegistrationFunction } from '@causa/workspace';
+export * from './configurations/index.js';
+export * from './services/index.js';
+declare const registerModule: ModuleRegistrationFunction;
+export default registerModule;

package/dist/index.js

@@ -0,0 +1,7 @@
+import { registerFunctions } from './functions/index.js';
+export * from './configurations/index.js';
+export * from './services/index.js';
+const registerModule = async (context) => {
+    registerFunctions(context);
+};
+export default registerModule;

package/dist/services/index.d.ts

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

package/dist/services/index.js

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

package/dist/services/terraform.d.ts

@@ -0,0 +1,125 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { SpawnOptions, SpawnedProcessResult } from '@causa/workspace-core';
+/**
+ * Options for the {@link TerraformService.wrapWorkspaceOperation} method.
+ */
+type WrapWorkspaceOperationOptions = {
+    /**
+     * The Terraform workspace to select, instead of {@link TerraformService.defaultTerraformWorkspace}.
+     */
+    workspace?: string;
+    /**
+     * Whether the Terraform workspace should be created if it does not already exists.
+     */
+    createWorkspaceIfNeeded?: boolean;
+    /**
+     * Whether the `terraform init` step should be skipped.
+     */
+    skipInit?: boolean;
+} & SpawnOptions;
+/**
+ * A service exposing the Terraform CLI.
+ */
+export declare class TerraformService {
+    /**
+     * The underlying {@link ProcessService} spawning the Terraform CLI.
+     */
+    private readonly processService;
+    /**
+     * Default options when spawning a `terraform` process.
+     * The {@link SpawnOptions.workingDirectory} will be set to the project's root (if it is defined).
+     */
+    private readonly defaultSpawnOptions;
+    /**
+     * The logger to use.
+     */
+    private readonly logger;
+    /**
+     * The default Terraform workspace, obtained from the configuration at `terraform.workspace`.
+     * This is used by {@link TerraformService.wrapWorkspaceOperation} if no workspace is specified.
+     */
+    private readonly defaultTerraformWorkspace;
+    constructor(context: WorkspaceContext);
+    /**
+     * Runs `terraform init`.
+     *
+     * @param options Options when initializing Terraform.
+     */
+    init(options?: SpawnOptions): Promise<void>;
+    /**
+     * Runs `terraform workspace show` and returns the currently selected workspace.
+     *
+     * @param options Options when running the command.
+     * @returns The name of the currently selected workspace.
+     */
+    workspaceShow(options?: SpawnOptions): Promise<string>;
+    /**
+     * Runs `terraform workspace select` to change the active workspace.
+     *
+     * @param workspace The workspace to select.
+     * @param options Options when running the command.
+     */
+    workspaceSelect(workspace: string, options?: {
+        orCreate?: boolean;
+    } & SpawnOptions): Promise<void>;
+    /**
+     * Runs `terraform plan` and writes the corresponding plan to a file.
+     *
+     * @param out The path to the output file plan.
+     * @param options Options for the `plan` command.
+     * @returns `true` if the plan contains changes, `false` otherwise.
+     */
+    plan(out: string, options?: {
+        /**
+         * Whether destruction of the workspace should be planned, instead of comparing it with the infrastructure
+         * definition.
+         */
+        destroy?: boolean;
+        /**
+         * A map of Terraform variables to forward to `terraform plan`.
+         */
+        variables?: Record<string, string>;
+    } & SpawnOptions): Promise<boolean>;
+    /**
+     * Runs `terraform apply` to perform the changes described in the given plan.
+     *
+     * @param plan The path to the plan file to apply.
+     * @param options Options when running the command.
+     */
+    apply(plan: string, options?: SpawnOptions): Promise<void>;
+    /**
+     * Runs `terraform show` on the given plan and returns the output of the command.
+     *
+     * @param path The path to the plan to describe.
+     * @param options Options when running the command. `capture` is enabled automatically.
+     * @returns The standard output of the command, describing the plan.
+     */
+    show(path: string, options?: Omit<SpawnOptions, 'capture'>): Promise<string>;
+    /**
+     * 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.
+     *
+     * @param fn The function to run after Terraform has been initialized and the workspace selected.
+     * @returns The result of `fn`.
+     */
+    wrapWorkspaceOperation<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 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.
+     *
+     * @param options Options when performing the operation.
+     * @param fn The function to run after Terraform has been initialized and the workspace selected.
+     * @returns The result of `fn`.
+     */
+    wrapWorkspaceOperation<T>(options: WrapWorkspaceOperationOptions, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Runs an arbitrary Terraform command.
+     *
+     * @param command The Terraform command to run.
+     * @param args Arguments to place after the command name.
+     * @param options {@link SpawnOptions} for the process.
+     * @returns The result of the spawned process.
+     */
+    terraform(command: string, args: string[], options?: SpawnOptions): Promise<SpawnedProcessResult>;
+}
+export {};

package/dist/services/terraform.js

@@ -0,0 +1,164 @@
+import { ProcessService, ProcessServiceExitCodeError, } from '@causa/workspace-core';
+/**
+ * A service exposing the Terraform CLI.
+ */
+export class TerraformService {
+    /**
+     * The underlying {@link ProcessService} spawning the Terraform CLI.
+     */
+    processService;
+    /**
+     * Default options when spawning a `terraform` process.
+     * The {@link SpawnOptions.workingDirectory} will be set to the project's root (if it is defined).
+     */
+    defaultSpawnOptions;
+    /**
+     * The logger to use.
+     */
+    logger;
+    /**
+     * The default Terraform workspace, obtained from the configuration at `terraform.workspace`.
+     * This is used by {@link TerraformService.wrapWorkspaceOperation} if no workspace is specified.
+     */
+    defaultTerraformWorkspace;
+    constructor(context) {
+        this.processService = context.service(ProcessService);
+        this.defaultSpawnOptions = {
+            workingDirectory: context.projectPath ?? undefined,
+        };
+        this.logger = context.logger;
+        this.defaultTerraformWorkspace = context
+            .asConfiguration()
+            .getOrThrow('terraform.workspace');
+    }
+    /**
+     * Runs `terraform init`.
+     *
+     * @param options Options when initializing Terraform.
+     */
+    async init(options = {}) {
+        await this.terraform('init', ['-input=false'], options);
+    }
+    /**
+     * Runs `terraform workspace show` and returns the currently selected workspace.
+     *
+     * @param options Options when running the command.
+     * @returns The name of the currently selected workspace.
+     */
+    async workspaceShow(options = {}) {
+        const result = await this.terraform('workspace', ['show'], {
+            logging: { stdout: null, stderr: 'debug' },
+            ...options,
+            capture: { ...options.capture, stdout: true },
+        });
+        return result.stdout?.trim() ?? '';
+    }
+    /**
+     * Runs `terraform workspace select` to change the active workspace.
+     *
+     * @param workspace The workspace to select.
+     * @param options Options when running the command.
+     */
+    async workspaceSelect(workspace, options = {}) {
+        const { orCreate, ...spawnOptions } = options;
+        await this.terraform('workspace', ['select', ...(orCreate ? ['-or-create=true'] : []), workspace], spawnOptions);
+    }
+    /**
+     * Runs `terraform plan` and writes the corresponding plan to a file.
+     *
+     * @param out The path to the output file plan.
+     * @param options Options for the `plan` command.
+     * @returns `true` if the plan contains changes, `false` otherwise.
+     */
+    async plan(out, options = {}) {
+        const { destroy, variables, ...spawnOptions } = options;
+        const args = ['-input=false', `-out=${out}`, '-detailed-exitcode'];
+        if (destroy) {
+            args.push('-destroy');
+        }
+        Object.entries(variables ?? {}).forEach(([varName, varValue]) => args.push('-var', `${varName}=${varValue}`));
+        try {
+            await this.terraform('plan', args, spawnOptions);
+            // When specifying `-detailed-exitcode`, a return code of `0` means that the plan does not contain any change.
+            return false;
+        }
+        catch (error) {
+            // When specifying `-detailed-exitcode`, a return code of `2` means that the plan contains changes.
+            if (error instanceof ProcessServiceExitCodeError &&
+                error.result.code === 2) {
+                return true;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Runs `terraform apply` to perform the changes described in the given plan.
+     *
+     * @param plan The path to the plan file to apply.
+     * @param options Options when running the command.
+     */
+    async apply(plan, options = {}) {
+        await this.terraform('apply', ['-input=false', plan], options);
+    }
+    /**
+     * Runs `terraform show` on the given plan and returns the output of the command.
+     *
+     * @param path The path to the plan to describe.
+     * @param options Options when running the command. `capture` is enabled automatically.
+     * @returns The standard output of the command, describing the plan.
+     */
+    async show(path, options = {}) {
+        const result = await this.terraform('show', [path], {
+            ...options,
+            capture: { stdout: true, stderr: true },
+            logging: options.logging ?? null,
+        });
+        return result.stdout ?? '';
+    }
+    async wrapWorkspaceOperation(optionsOrFn, fn) {
+        const options = fn ? optionsOrFn : {};
+        const func = fn ?? optionsOrFn;
+        const { skipInit, createWorkspaceIfNeeded, workspace, ...spawnOptions } = options;
+        if (!skipInit) {
+            await this.init(spawnOptions);
+        }
+        const workspaceToSelect = workspace ?? this.defaultTerraformWorkspace;
+        let workspaceToRestore = null;
+        try {
+            const currentWorkspace = await this.workspaceShow(spawnOptions);
+            if (workspaceToSelect !== currentWorkspace) {
+                this.logger.debug(`🔧 Changing Terraform workspace from '${currentWorkspace}' to '${workspaceToSelect}'.`);
+                await this.workspaceSelect(workspaceToSelect, {
+                    orCreate: createWorkspaceIfNeeded,
+                    ...spawnOptions,
+                });
+                workspaceToRestore = currentWorkspace;
+            }
+            else {
+                this.logger.debug(`🔧 Terraform workspace '${workspaceToSelect}' is already configured.`);
+            }
+            return await func();
+        }
+        finally {
+            if (workspaceToRestore) {
+                this.logger.debug(`🔧 Switching back to Terraform workspace '${workspaceToRestore}'.`);
+                await this.workspaceSelect(workspaceToRestore, spawnOptions);
+            }
+        }
+    }
+    /**
+     * Runs an arbitrary Terraform command.
+     *
+     * @param command The Terraform command to run.
+     * @param args Arguments to place after the command name.
+     * @param options {@link SpawnOptions} for the process.
+     * @returns The result of the spawned process.
+     */
+    async terraform(command, args, options = {}) {
+        const p = this.processService.spawn('terraform', [command, ...args], {
+            ...this.defaultSpawnOptions,
+            ...options,
+        });
+        return await p.result;
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@causa/workspace-terraform",
+  "version": "0.1.0",
+  "description": "The Causa workspace module providing functionalities for infrastructure projects coded in Terraform.",
+  "repository": "github:causa-io/workspace-module-terraform",
+  "license": "ISC",
+  "type": "module",
+  "engines": {
+    "node": ">=16"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "LICENSE.md",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "prebuild": "rimraf ./dist",
+    "build": "tsc -p tsconfig.build.json",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "NODE_OPTIONS=\"--experimental-vm-modules --no-warnings=ExperimentalWarning\" jest",
+    "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"
+  },
+  "devDependencies": {
+    "@tsconfig/node18": "^2.0.1",
+    "@types/jest": "^29.5.1",
+    "eslint": "^8.40.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",
+    "ts-jest": "^29.1.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.4"
+  }
+}