@c6fc/spellcraft 0.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,17 @@
+# SpellCraft for JSonnet workflows
+
+Spellcraft is an opinionated approach to manifesting and applying configurations for various tools. SpellCraft is the core engine which can accept plugins like @c6fc/spellcraft-packer for Hashicorp Packer configurations, or @c6fc/spellcraft-aws for interacting with Amazon Web Services
+
+## Installation
+
+Install spellcraft with `npm install` and add plugins with `npx spellcraft importModule`
+
+```sh
+$ npm i -p spellcraft
+$ npx spellcraft importModule @c6fc/spellcraft-packer packer
+```
+
+The importModule command above will expose the methods from `@c6fc/spellcraft-packer` with `local packer = require "packer"`
+
+
+## More details to be added soon

package/bin/spellcraft.js

@@ -0,0 +1,146 @@
+#! /usr/bin/env node
+
+/**
+ * @fileOverview SpellCraft CLI tool.
+ * This script provides a command-line interface for interacting with the SpellFrame
+ * rendering engine. It allows users to generate configurations from Jsonnet files
+ * and manage SpellCraft modules.
+ * @module spellcraft-cli
+ */
+
+'use strict';
+
+const yargs = require('yargs');
+const { hideBin } = require('yargs/helpers');
+const { SpellFrame } = require('../src/index.js');
+
+const spellframe = new SpellFrame();
+
+// --- JSDoc Blocks for CLI Commands ---
+// These blocks define the commands for JSDoc.
+// They are not directly attached to yargs code but describe the CLI's public interface.
+
+/**
+ * Generates files from a Jsonnet configuration.
+ * This command processes a specified Jsonnet configuration file using the SpellFrame engine,
+ * renders the output, and writes the resulting files to the configured directory.
+ *
+ * **Usage:** `spellcraft generate <filename>`
+ *
+ * @function generate
+ * @name module:spellcraft-cli.generate
+ * @param {object} argv - The arguments object provided by yargs.
+ * @param {string} argv.filename The path to the Jsonnet configuration file to consume. (Required)
+ *
+ * @example
+ * spellcraft generate ./myconfig.jsonnet
+ */
+
+/**
+ * Links an npm package as a SpellCraft module for the current project.
+ * This command installs the specified npm package (if not already present) and
+ * registers it within the project's SpellCraft module configuration, making its
+ * functionalities available during the rendering process.
+ *
+ * **Usage:** `spellcraft importModule <npmPackage> [name]`
+ *
+ * @function importModule
+ * @name module:spellcraft-cli.importModule
+ * @param {object} argv - The arguments object provided by yargs.
+ * @param {string} argv.npmPackage The NPM package name of the SpellCraft Plugin to import. (Required)
+ * @param {string} [argv.name] An optional alias name to use for this module within SpellCraft.
+ *                             If not provided, a default name from the package may be used.
+ *
+ * @example
+ * spellcraft importModule my-spellcraft-enhancer
+ * @example
+ * spellcraft importModule @my-scope/spellcraft-utils customUtils
+ */
+
+// --- End of JSDoc Blocks for CLI Commands ---
+
+(async () => {
+    // No JSDoc for setupCli as it's an internal helper
+    function setupCli(sfInstance) {
+        let cli = yargs(hideBin(process.argv))
+            .usage("Syntax: $0 <command> [options]")
+            .scriptName("spellcraft")
+
+            .command("*", false, (yargsInstance) => { // 'false' for no yargs description
+                return yargsInstance;
+            }, (argv) => {
+                console.log("[~] That's too arcane. (Unrecognized command)");
+            })
+
+            .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) => { // No JSDoc for internal handler
+                try {
+                    await sfInstance.init();
+                    console.log(`[+] Rendering configuration from: ${argv.filename}`);
+                    await sfInstance.render(argv.filename);
+                    await sfInstance.write();
+                    console.log("[+] Generation complete.");
+                } catch (error) {
+                    console.error(`[!] Error during generation: ${error.message}`);
+                    process.exit(1);
+                }
+            })
+
+            .command("importModule <npmPackage> [name]", "Configures the current project to use a SpellCraft plugin as an import", (yargsInstance) => {
+                return yargsInstance
+                    .positional('npmPackage', {
+                        describe: 'The NPM package name of a SpellCraft Plugin to import',
+                        type: 'string',
+                        demandOption: true,
+                    })
+                    .positional('name', {
+                        describe: 'Optional alias name for the module in SpellCraft',
+                        type: 'string',
+                        default: undefined,
+                    });
+            },
+            async (argv) => { // No JSDoc for internal handler
+                try {
+                    await sfInstance.importSpellCraftModuleFromNpm(argv.npmPackage, argv.name);
+                    console.log(`[+] Module '${argv.npmPackage}' ${argv.name ? `(aliased as ${argv.name}) ` : ''}linked successfully.`);
+                } catch (error) {
+                    console.error(`[!] Error importing module: ${error.message}`);
+                    process.exit(1);
+                }
+            });
+
+        // No JSDoc for CLI extensions loop if considered internal detail
+        if (sfInstance.cliExtensions && sfInstance.cliExtensions.length > 0) {
+            sfInstance.cliExtensions.forEach((extensionFn) => {
+                if (typeof extensionFn === 'function') {
+                    extensionFn(cli, sfInstance);
+                }
+            });
+        }
+
+        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;
+    }
+
+    try {
+        setupCli(spellframe);
+    } catch (error) {
+        console.error(`[!] A critical error occurred: ${error.message}`);
+        process.exit(1);
+    }
+})();

package/bin/spellcraft.js.bak

@@ -0,0 +1,47 @@
+#! /usr/bin/env node
+
+const fs = require('fs');
+const yargs = require('yargs')
+const { SpellFrame } = require('../src/index.js');
+
+const spellframe = new SpellFrame();
+
+(async () => {
+
+	yargs
+		.usage("Syntax: $0 <command> [options]")
+		.command("*", "That's too arcane", (yargs) => {
+			yargs
+		}, (argv) => {
+			console.log("[~] That's too arcane. (Unrecognized command)");
+		})
+		.command("generate <filename>", "Generates files from a configuration", (yargs) => {
+			return yargs.positional('filename', {
+				describe: 'Jsonnet configuration file to consume'
+			})
+		}, async (argv) => {
+
+			await spellframe.init();
+			await spellframe.render(argv.filename);
+			await spellframe.write();
+
+		})
+		.command("importModule <npmPackage> [name]", "Configures the current project to use a SpellCraft plugin as an import", (yargs) => {
+			return yargs.positional('npmPackage', {
+				describe: 'The NPM package name of a SpellCraft Plugin to import'
+			}).positional('name', {
+				describe: 'What name to use as the import namespace for this plugin'
+			})
+		}, async (argv) => {
+
+			await spellframe.importSpellCraftModuleFromNpm(argv['npmPackage'], argv['name']);
+
+		});
+
+	spellframe.cliExtensions.forEach((e, i) => e(yargs, spellframe));
+
+	yargs
+		.showHelpOnFail(false)
+		.help("help")
+		.argv;
+})();

package/jsdoc.json

@@ -0,0 +1,33 @@
+{
+    "tags": {
+        "allowUnknownTags": true
+    },
+    "plugins": ["plugins/markdown"],
+    "opts": {
+        "destination": "./docs"
+    },
+    "source": {
+        "include": [
+            "src/",
+            "bin/",
+            "lib/"
+        ],
+        "includePattern": ".",
+        "excludePattern": "\\.bak$"
+    },
+    "opts": {
+        "destination": "./docs/",
+        "encoding": "utf8",
+        "private": true,
+        "recurse": false,
+        "readme": "README.md",
+        "template": "node_modules/clean-jsdoc-theme"
+    },
+    "markdown": {
+        "hardwrap": false,
+        "idInHeadings": true
+    },
+    "theme_opts": {
+      "default_theme": "dark"
+    }
+}

package/lib/spellcraft

@@ -0,0 +1,6 @@
+{
+	local sonnetry = self,
+
+	envvar(name):: std.native("envvar")(name),	
+	path():: std.native("path")()
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "dependencies": {
+    "@hanazuki/node-jsonnet": "^0.4.2",
+    "ini": "^5.0.0",
+    "js-yaml": "^4.1.0",
+    "yargs": "^17.2.1"
+  },
+  "name": "@c6fc/spellcraft",
+  "description": "Extensible JSonnet CLI platform",
+  "version": "0.0.1",
+  "main": "src/index.js",
+  "directories": {
+    "lib": "lib"
+  },
+  "bin": {
+    "spellcraft": "bin/spellcraft.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "doc": "jsdoc -c jsdoc.json --verbose"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/c6fc/spellcraft.git"
+  },
+  "keywords": [
+    "jsonnet"
+  ],
+  "author": "Brad Woodward (brad@bradwoodward.io)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/c6fc/spellcraft/issues"
+  },
+  "homepage": "https://github.com/c6fc/spellcraft#readme",
+  "devDependencies": {
+    "clean-jsdoc-theme": "^4.3.0",
+    "jsdoc": "^4.0.4"
+  }
+}