@c6fc/spellcraft-gcp-terraform 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Brad Woodward
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# SpellCraft AWS Integration
+
+[![NPM version](https://img.shields.io/npm/v/@c6fc/spellcraft-gcp-terraform.svg?style=flat)](https://www.npmjs.com/package/@c6fc/spellcraft-gcp-terraform)
+[![License](https://img.shields.io/npm/l/@c6fc/spellcraft-gcp-terraform.svg?style=flat)](https://opensource.org/licenses/MIT)
+
+This module exposes common constructs for using [SpellCraft](https://github.com/@c6fc/spellcraft) SpellFrames to deploy infrastructure to AWS using Terraform.
+
+```sh
+npm install --save @c6fc/spellcraft-gcp-terraform
+```
+
+## Features
+
+This module exposes the concept of a bootstrap bucket (functionally a terraform backend), and artifacts which can contain arbitrary data and are stored alongside the terraform state in the bootstrap bucket. The former allows for dynamic configuration of Terraform providers within different environments, while the latter simplifies the storage and use of dynamic configuration details that might be environment dependent.
+
+<!-- SPELLCRAFT_DOCS_CLI_START -->
+
+<!-- SPELLCRAFT_DOCS_CLI_END -->
+
+## SpellFrame 'init()' features
+
+This plugin does not perform any distinct 'init' operations, other than to initialize credentials within the dependant plugin `@c6fc/terraform-gcp-auth`.
+
+## JavaScript context features
+
+Extends the JavaScript function context with an `awsterraform` object containing the following keys:
+
+```JSON
+{ 
+	"projectName": "<contains the name of the project specified by bootstrap()>",
+	"bootstrapBucket": "<contains the ARN for the bootstrap bucket>",
+	"bootstrapLocation": "<contains the region where the bootstrap bucket is located>"
+}
+```
+
+<!-- SPELLCRAFT_DOCS_API_START -->
+## API Reference
+
+### `bootstrap(project)`
+
+Creates a Terraform backend bucket if one doesn't already exist, then
+returns a 'backend' object referencing this bucket and a unique path
+for this project's state and artifacts.
+
+- param {string} project
+- returns {object} backend
+
+**Examples:**
+
+```jsonnet
+local gcp = import "@c6fc/spellcraft-gcp-terraform";
+
+gcp.bootstrap("myBootstrapTest");
+
+// Returns:
+{
+   "terraform": {
+       "backend": {
+           "gcs": {
+               "bucket": "spellcraft-random-0123456789",
+               "key": "spellcraft/myBootstrapTest/terraform.tfstate",
+           }
+       }
+   }
+}
+```
+
+---
+### `getArtifact(name)`
+
+Obtains the contents of a named artifact stored alongside this project in the bootstrap
+bucket. This artifact is created with 'putArtifact';
+
+- param {string} name
+- returns {object} backend
+
+**Examples:**
+
+```jsonnet
+local gcp = import "@c6fc/spellcraft-gcp-terraform";
+
+gcp.getArtifact("myArtifact");
+
+// Returns:
+<contents of your artifact>
+```
+
+---
+### `getBootstrapBucket()`
+
+Attempts to discover the bucket created through bootstrap(), returning the
+bucket name if present.
+
+- returns {string} bucketArn
+
+**Examples:**
+
+```jsonnet
+local gcp = import "@c6fc/spellcraft-gcp-terraform";
+
+gcp.getBootstrapBucket();
+
+// Returns:
+spellcraft-terraform-<project-id>
+```
+
+---
+### `getRemoteState(project)`
+
+Read the Terraform state for an adjacent SpellCraft project in the same GCP account
+
+- param {string} project
+- returns {object} state
+
+**Examples:**
+
+```jsonnet
+local gcp = import "@c6fc/spellcraft-gcp-terraform";
+
+gcp.getRemoteState("mySecondProject");
+
+// Returns:
+{ full remote state object }
+```
+
+---
+### `putArtifact(name, content)`
+
+Stores the JSON-encoded balue of 'contents' as a file in the GCS backend bucket using
+the project prefix.
+
+- param {string} name
+- param {*} contents
+- returns {boolean} true
+
+**Examples:**
+
+```jsonnet
+local gcp = import "@c6fc/spellcraft-gcp-terraform";
+
+gcp.putArtifact("myArtifact", { someData: someValue });
+
+// Returns:
+true
+```
+
+---
+### `providerAliases(default, filter="")`
+
+Stores the JSON-encoded value of 'contents' as a file in the GCS backend bucket using
+the project prefix. If 'filter' is provided, only region names that string match
+will be included.
+
+- param {string} default
+- param {string} filter
+
+**Examples:**
+
+```jsonnet
+local gcp = import "@c6fc/spellcraft-gcp-terraform";
+
+gcp.providerAliases("us-west2");
+
+// Returns:
+[{ google: {
+	region: "us-west2"
+}}, { google: {
+	region: "us-east1",
+	alias: "us-east1"
+}}, ...]
+```
+
+---
+
+<!-- SPELLCRAFT_DOCS_API_END -->
+
+
+## Installation
+
+Install the plugin as a dependency in your SpellCraft project:
+
+```bash
+npm install --save @c6fc/spellcraft-gcp-terraform
+```
+
+Once installed, you can load the module into your JSonnet files.
+
+```jsonnet
+local aws = import "@c6fc/spellcraft-gcp-terraform";
+
+{
+	'backend.tf.json': aws.bootstrap("myProjectName"),
+
+	// Generate provider list defaulting to 'us-west2' but including all 'us-' regions
+	'provider.tf.json': {
+		provider: aws.providerAliases("us-west2", "us-")
+	}
+}
+```

package/module.js

@@ -0,0 +1,189 @@
+'use strict';
+
+process.env.AWS_SDK_JS_SUPPRESS_MAINTENANCE_MODE_MESSAGE=1
+
+const fs = require("fs");
+const os = require("os");
+
+// Nab the authenticated AWS instantiation from gcp-auth
+const gcpauth = require("@c6fc/spellcraft-gcp-auth");
+const { google } = gcpauth._spellcraft_metadata.functionContext;
+const storage = google.storage('v1');
+const compute = google.compute('v1');
+
+let cachedProject = null;
+
+// Initialize caches
+const artifacts = {};
+const gcpterraform = { projectName: null, bootstrapBucket: null };
+const remoteStates = {};
+
+exports._spellcraft_metadata = {
+	functionContext: { gcpterraform }
+}
+
+exports.bootstrap = [async function (project) {
+	return await bootstrap(project);
+}, "project"];
+
+exports.getArtifact = [async function (name) {
+	return await getArtifact(name);
+}, "name"];
+
+exports.getBootstrapBucket = [async function () {
+	return await getBootstrapBucket();
+}];
+
+exports.getRemoteState = [async function (project) {
+	return await getRemoteState(project);
+}, "project"];
+
+exports.putArtifact = [async function (name, content) {
+	return await putArtifact(name, content);
+}, "name", "content"];
+
+async function bootstrap(projectName) {
+	cachedProject = await gcpauth.getProjectId[0]();
+	const targetBucket = `spellcraft-terraform-${cachedProject}`;
+    
+    if (!await getBootstrapBucket()) {
+         try {
+            console.log(`[+] Creating GCS Bootstrap Bucket: ${targetBucket}`);
+            await storage.buckets.insert({
+                project: cachedProject,
+                requestBody: {
+                    name: targetBucket,
+                    location: 'US', // Defaulting to US multi-region for high availability
+                    storageClass: 'STANDARD',
+                    versioning: { enabled: true },
+                    iamConfiguration: {
+                        uniformBucketLevelAccess: { enabled: true }
+                    }
+                }
+            });
+        } catch(e) {
+            throw new Error(`Failed to discover/create GCS bucket: ${e.message}`);
+        }
+    }
+
+    gcpterraform.bootstrapBucket = targetBucket;
+    gcpterraform.projectName = projectName;
+
+    // Return the Terraform backend configuration object
+    return {
+        terraform: {
+            backend: {
+                gcs: {
+                    bucket: gcpterraform.bootstrapBucket,
+                    prefix: `spellcraft/${projectName}`
+                }
+            }
+        }
+    };
+};
+
+async function getBootstrapBucket() {
+
+
+	if (!!gcpterraform.bootstrapBucket) {
+		return gcpterraform.bootstrapBucket;
+	}
+
+	if (!cachedProject) {
+		cachedProject = await gcpauth.getProjectId[0]();
+	}
+
+    
+    try {
+        // 1. Try to find existing bucket
+        await storage.buckets.get({ bucket: `spellcraft-terraform-${cachedProject}` });
+        gcpterraform.bootstrapBucket = `spellcraft-terraform-${cachedProject}`;
+
+        return gcpterraform.bootstrapBucket;
+    } catch (e) {
+    	return false;
+    };
+
+	return false;
+}
+
+async function getRemoteState(project) {
+
+	if (!!!remoteStates[project]) {
+		if (!gcpterraform.bootstrapBucket) throw new Error("Module not bootstrapped. Call bootstrap() first.");
+
+	    try {
+	        const res = await storage.objects.get({
+	            bucket: gcpterraform.bootstrapBucket,
+	            object: `spellcraft/${project}/default.tfstate`,
+	            alt: 'media'
+	        });
+	        return res.data;
+	    } catch (e) {
+	        throw new Error(`Could not find remote state for project: ${project}`);
+	    }
+
+		const state = JSON.parse(stateJson.Body);
+
+		const resources = state.resources.reduce((a, c) => {
+			let path;
+
+			if (c.mode == "data") {
+				a.data = (!a.data) ? {} : a.data;
+				a.data[c.type] = (!a.data[c.type]) ? {} : a.data[c.type];
+
+				path = a.data[c.type];
+			} else {
+				a[c.type] = (!a[c.type]) ? {} : a[c.type];
+
+				path = a[c.type];
+			}
+
+			path[c.name] = (c.instances.length == 1) ? c.instances[0].attributes : c.instances.map(e => e.attributes);
+
+			return a;
+		}, {});
+
+		resources.outputs = Object.keys(state.outputs).reduce((a, c) => {
+			a[c] = state.outputs[c].value;
+
+			return a;
+		}, {});
+
+		// console.log(resources.outputs);
+
+		remoteStates[project] = resources;
+	}
+
+	return resources;
+}
+
+exports.getArtifact = async function(name) {
+    if (!gcpterraform.bootstrapBucket) throw new Error("Module not bootstrapped. Call bootstrap() first.");
+
+    try {
+        const res = await storage.objects.get({
+            bucket: gcpterraform.bootstrapBucket,
+            object: `spellcraft/${gcpterraform.projectName}/artifacts/${name}.json`,
+            alt: 'media'
+        });
+        return res.data;
+    } catch (e) {
+        return null;
+    }
+};
+
+exports.putArtifact = async function(name, content) {
+    if (!gcpterraform.bootstrapBucket) throw new Error("Module not bootstrapped. Call bootstrap() first.");
+
+    const res = await storage.objects.insert({
+        bucket: gcpterraform.bootstrapBucket,
+        name: `spellcraft/${gcpterraform.projectName}/artifacts/${name}.json`,
+        media: {
+            mimeType: 'application/json',
+            body: JSON.stringify(content, null, 2)
+        }
+    });
+
+    return !!res.data;
+};

package/module.libsonnet

@@ -0,0 +1,132 @@
+// Don't try to 'import' your spellcraft native functions here.
+// Use std.native(function)(..args) instead
+
+{
+	// JS Native functions are already documented in spellcraft_modules/foo.js
+	// but need to be specified here to expose them through the import
+
+	/**
+	 * Creates a Terraform backend bucket if one doesn't already exist, then
+	 * returns a 'backend' object referencing this bucket and a unique path
+	 * for this project's state and artifacts.
+	 *
+	 * @param {string} project
+	 * @returns {object} backend
+	 * @example
+	 * local gcp = import "@c6fc/spellcraft-gcp-terraform";
+	 *
+	 * gcp.bootstrap("myBootstrapTest");
+	 *
+	 * // Returns:
+	 * {
+	 *    "terraform": {
+	 *        "backend": {
+	 *            "gcs": {
+	 *                "bucket": "spellcraft-random-0123456789",
+	 *                "key": "spellcraft/myBootstrapTest/terraform.tfstate",
+	 *            }
+	 *        }
+	 *    }
+	 * }
+	 */
+	bootstrap(project):: std.native("@c6fc/spellcraft-gcp-terraform:bootstrap")(project),
+
+	/**
+	 * Obtains the contents of a named artifact stored alongside this project in the bootstrap
+	 * bucket. This artifact is created with 'putArtifact';
+	 *
+	 * @param {string} name
+	 * @returns {object} backend
+	 * @example
+	 * local gcp = import "@c6fc/spellcraft-gcp-terraform";
+	 *
+	 * gcp.getArtifact("myArtifact");
+	 *
+	 * // Returns:
+	 * <contents of your artifact>
+	 */
+	getArtifact(name):: std.native("@c6fc/spellcraft-gcp-terraform:getArtifact")(name),
+
+	/**
+	 * Attempts to discover the bucket created through bootstrap(), returning the
+	 * bucket name if present.
+	 *
+	 * @returns {string} bucketArn
+	 * @example
+	 * local gcp = import "@c6fc/spellcraft-gcp-terraform";
+	 *
+	 * gcp.getBootstrapBucket();
+	 *
+	 * // Returns:
+	 * spellcraft-terraform-<project-id>
+	 */
+	getBootstrapBucket():: std.native("@c6fc/spellcraft-gcp-terraform:getBootstrapBucket")(),
+
+	/**
+	 * Read the Terraform state for an adjacent SpellCraft project in the same GCP account
+	 *
+	 * @param {string} project
+	 * @returns {object} state
+	 * @example
+	 * local gcp = import "@c6fc/spellcraft-gcp-terraform";
+	 *
+	 * gcp.getRemoteState("mySecondProject");
+	 *
+	 * // Returns:
+	 * { full remote state object }
+	 */
+	getRemoteState(project):: std.native("@c6fc/spellcraft-gcp-terraform:getRemoteState")(project),
+
+	/**
+	 * Stores the JSON-encoded balue of 'contents' as a file in the GCS backend bucket using
+	 * the project prefix.
+	 *
+	 * @param {string} name
+	 * @param {*} contents
+	 * @returns {boolean} true
+	 * @example
+	 * local gcp = import "@c6fc/spellcraft-gcp-terraform";
+	 *
+	 * gcp.putArtifact("myArtifact", { someData: someValue });
+	 *
+	 * // Returns:
+	 * true
+	 */
+	putArtifact(name, content):: std.native("@c6fc/spellcraft-gcp-terraform:putArtifact")(name, content),
+
+	/**
+	 * Stores the JSON-encoded value of 'contents' as a file in the GCS backend bucket using
+	 * the project prefix. If 'filter' is provided, only region names that string match
+	 * will be included.
+	 *
+	 * @param {string} default
+	 * @param {string} filter
+	 * @example
+	 * local gcp = import "@c6fc/spellcraft-gcp-terraform";
+	 *
+	 * gcp.providerAliases("us-west2");
+	 *
+	 * // Returns:
+	 * [{ google: {
+	 *		region: "us-west2"
+	 * }}, { google: {
+	 *		region: "us-east1",
+			alias: "us-east1"
+	 * }}, ...]
+	 */
+	providerAliases(default, filter=""):: [{
+		google: {
+			alias: region,
+			region: region
+		}
+	} for region in std.filterMap(
+		function(x) std.length(filter) < 1 || std.length(std.findSubstr(filter, x.name)) > 0,
+		function(x) x.name,
+		std.native("@c6fc/spellcraft-gcp-auth:api")('compute.v1.regions.list', '{"project":"%s"}' % std.native("@c6fc/spellcraft-gcp-auth:getProjectId")()).items
+	)] + [{
+		google: {
+			region: default
+		}
+	}]
+
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@c6fc/spellcraft-gcp-terraform",
+  "version": "1.0.1",
+  "main": "module.js",
+  "scripts": {
+    "cli": "utils/cli-test.js",
+    "test": "node utils/test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/c6fc/spellcraft-gcp-terraform.git"
+  },
+  "spellcraft": true,
+  "keywords": [
+    "spellcraft",
+    "aws",
+    "terraform"
+  ],
+  "author": "Brad Woodward (brad@bradwoodward.io)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/c6fc/spellcraft-gcp-terraform/issues"
+  },
+  "homepage": "https://github.com/c6fc/spellcraft-gcp-terraform#readme",
+  "description": "A plugin to empower @c6fc/spellcraft with GCP and Terraform",
+  "dependencies": {
+    "@c6fc/spellcraft-gcp-auth": "^1.0.1",
+    "@c6fc/spellcraft-terraform": "^1.1.3"
+  },
+  "devDependencies": {
+    "@c6fc/spellcraft": "~0.1.0",
+    "yargs": "^18.0.0"
+  },
+  "peerDependencies": {
+    "@c6fc/spellcraft": "~0.1.0"
+  }
+}

package/test.jsonnet

@@ -0,0 +1,34 @@
+/*
+	This file should manifest all the exposed features of your module
+	so users can see examples of how they are used, and the output they
+	generate.
+*/
+
+local gcp = import "module.libsonnet";
+
+{
+	"bootstrap.tf.json": gcp.bootstrap("spellcraft-gcp-terraform-module-test"),
+	"test.tf.json": {
+		output: {
+			putArtifact: {
+				value: gcp.putArtifact("putArtifactTest", "mytest2")
+			},
+			getBootstrapBucket: {
+				value: gcp.getBootstrapBucket()
+			},
+
+			/* These can only be used after the project is created and the contents populated.
+			getArtifact: {
+				value: gcp.getArtifact("putArtifactTest")
+			},
+			getRemoteState: {
+				value: std.parseJson(gcp.getRemoteState("spellcraft-gcp-terraform-module-test"))
+			}
+			*/
+			
+		}
+	},
+	'providers.tf.json': {
+		provider: gcp.providerAliases("us-west2", "us-")
+	}
+}

package/utils/cli-test.js

@@ -0,0 +1,78 @@
+#! /usr/bin/env node
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yargs = require('yargs');
+const { hideBin } = require('yargs/helpers');
+const { SpellFrame } = require('@c6fc/spellcraft');
+
+const spellframe = new SpellFrame();
+
+// 1. Resolve local package info to simulate a real plugin load
+const packageDir = path.resolve(__dirname, '..'); // Assuming script is in /utils
+const packageJsonPath = path.join(packageDir, 'package.json');
+
+if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(`[!] Could not find package.json at ${packageJsonPath}`);
+}
+
+const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+const jsEntry = path.join(packageDir, pkg.main || 'index.js');
+
+console.log(`[*] Loading local plugin context: ${pkg.name}`);
+
+// 2. Load the plugin into SpellFrame
+// This registers native functions (namespaced) and populates cliExtensions 
+// automatically via the _spellcraft_metadata export in module.js
+spellframe.loadPlugin(pkg.name, jsEntry);
+
+(async () => {
+	
+	let cli = yargs(hideBin(process.argv))
+		.usage("Syntax: $0 <command> [options]")
+		.scriptName("spellcraft")
+
+		.command("generate <filename>", "Generates files from a configuration", (yargsInstance) => {
+			return yargsInstance.positional('filename', {
+				describe: 'Jsonnet configuration file to consume',
+				type: 'string',
+				demandOption: true,
+			});
+		},
+		async (argv) => { 
+			try {
+				await spellframe.init();
+				console.log(`[+] Rendering configuration from: ${argv.filename}`);
+				await spellframe.render(argv.filename);
+				await spellframe.write();
+				console.log("[+] Generation complete.");
+			} catch (error) {
+				console.error(`[!] Error during generation: ${error.message}`);
+				process.exit(1);
+			}
+		});
+
+	// 3. Register CLI extensions found in the loaded plugin
+    // These were populated by loadPlugin() reading _spellcraft_metadata
+	if (spellframe.cliExtensions && spellframe.cliExtensions.length > 0) {
+		spellframe.cliExtensions.forEach((extensionFn) => {
+			if (typeof extensionFn === 'function') {
+				extensionFn(cli, spellframe);
+			}
+		});
+	}
+
+	cli
+		.demandCommand(1, 'You need to specify a command.')
+		.recommendCommands()
+		.strict()
+		.showHelpOnFail(true)
+		.help("help")
+		.alias('h', 'help')
+		.version()
+		.alias('v', 'version')
+		.epilogue('For more information, consult the SpellCraft documentation.')
+		.argv;
+})();

package/utils/test.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/*
+	This is a pre-written test-case wrapper
+	for local module development. Populate
+	../test.jsonnet with tests of your
+	module capabilities.
+
+	Run with `npm run test`
+*/
+
+const fs = require('fs');
+const path = require('path');
+const { SpellFrame } = require('@c6fc/spellcraft');
+
+const spellframe = new SpellFrame();
+
+(async () => {
+    try {
+        // 1. Read the local package.json
+        const packageJsonPath = path.resolve('./package.json');
+        if (!fs.existsSync(packageJsonPath)) {
+            throw new Error("Could not find package.json in current directory.");
+        }
+        const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+
+        // 2. Identify the entry point
+        const jsEntry = path.resolve(pkg.main || 'index.js');
+
+        console.log(`[*] Manually loading plugin: ${pkg.name}`);
+
+        // 3. Register the plugin using the current package name. 
+        // This ensures the native functions are registered as "@scope/pkg:func", 
+        // matching the std.native() calls in your libsonnet.
+        spellframe.loadPlugin(pkg.name, jsEntry);
+        
+        // 4. Initialize
+        await spellframe.init();
+
+        // 5. Render
+        // Note: Ensure your test.jsonnet imports "./module.libsonnet" directly
+        console.log("[*] Rendering test.jsonnet...");
+        await spellframe.render("test.jsonnet");
+
+        console.log(JSON.stringify(spellframe.lastRender, null, 4));
+
+    } catch (error) {
+        console.error(`[!] Test failed: ${error.message}`);
+        if (error.stack) console.error(error.stack);
+        process.exit(1);
+    }
+})();