✨ create-spellcraft-module ✨

Scaffold Your SpellCraft Modules with Ease!

create-spellcraft-module is a zero-configuration command-line tool designed to quickly bootstrap the creation of new modules for the powerful SpellCraft configuration management framework. Forget about tedious setup – get straight to building innovative extensions that enhance SpellCraft's capabilities.

Installation & Usage

create-spellcraft-module is designed to be used directly with npm init. Simply navigate to an empty directory where you want to create your new module and run: npm init spellcraft-module <your-module-name>

Replace <your-module-name> with the desired name for your module (e.g., @my-org/spellcraft-custom-logic). This name will be used as the package name in your package.json.

Usage

Navigate to an empty directory:

mkdir my-new-module
cd my-new-module

Initialize your new SpellCraft module:

npm init spellcraft-module @me/my-new-module

This command will generate a pre-configured file structure and essential files within the my-new-module directory, ready for you to start building your SpellCraft extension.

What's Inside Your New Module

create-spellcraft-module sets you up with a sensible default structure and helpful utilities:

├── utils/
    ├── cli-test.json
    └── test.js
├── .gitignore
├── module.js
├── module.jsonnet
├── package.json
├── README.md
└── test.jsonnet

/utils

This directory contains development and testing tools to streamline your module creation process.

• cli-test.js: A convenient wrapper for testing your module's SpellCraft CLI extensions. Use it with the npm run cli script defined in your package.json. This allows you to simulate spellcraft commands and verify your custom CLI functionality.

• test.js: A pre-created SpellFrame for manifesting your test.jsonnet file using the capabilities of your module. You can edit this as needed to manually include module dependencies as needed. Run your tests with the npm run test script.

.gitignore

A standard .gitignore file tailored for SpellCraft modules. It automatically ignores common build artifacts and directories that SpellCraft will manage within user projects, such as docs/, node_modules/, and render/. This ensures a clean and focused repository.

module.js

This is the heart of your module's JavaScript logic. It's where you define native functions that can be called from your Jsonnet configurations and where you register your module's metadata, including CLI extensions and initialization routines.

Native Functions

Export JavaScript functions to make them available as native functions within Jsonnet. The name of your exported function will automatically be used as the namespaced, native function name in Jsonnet.

exports.multiply = [(a, b) => { return a * b }, "a", "b"];

can then be called with

local mymodule = import "@my_org/my_module.libsonnet"

{
    "test.json": {
        multiply_as_native: std.native("@my_org/my_module:multiply")(3, 4),
        multiple_as_module: mymodule.multiply(3, 4);
    }
}

Function Context (this)

When defining functions intended to interact with other SpellCraft modules or access contextual information (like an initialized AWS SDK), use standard function declarations instead of arrow functions.

exports.no = () => {
    console.log(this.some_value); // Won't work. Arrow functions have no `this`
}

exports.yes = function() {
    console.log(this.some_value); // Use this instead.
}

Module Metadata (exports._spellcraft_metadata)

This crucial object configures how your module integrates with SpellCraft. It can contain:

exports._spellcraft_metadata = {
    // Specify filetype handlers for any custom file types you need that aren't
    // already provided by Spellcraft or other plugins
    fileTypeHandlers: {
        '.*?\.foo': (content) => JSON.stringify(content, null, 4)
    },

    // Specify any properties that should be added to `this` for other functions.
    functionContext: { foo, key: "my_value" },

    // Extend the SpellCraft `yargs` to include whatever custom interactions with `spellframe` you want.
    cliExtensions: (yargs, spellframe) => {
        // Add new commands to `yargs` to extend the CLI
    },
    init: async () => {
        // Use this space to handle any logic needed by your plugin
    }
}

The template module.js provides examples to guide you in defining your module's capabilities.

module.libsonnet

This file contains the Jsonnet portion of your module. Any methods or attributes defined here will be addressable when users import your module.

Key Point: SpellCraft automatically links the JavaScript functions you export in module.js as native functions, you do not need to manually declare them. Instead, this file should focus on building higher-level, declarative abstractions that utilize these native functions for a more user-friendly experience in Jsonnet configurations.

The template module.libsonnet includes examples to demonstrate how to create these wrapper functions.

package.json

A standard NPM package.json file with some SpellCraft-specific configurations. Most notably:

{
    // Sets up the utilities so you can use `npm run test` or `npm run cli`
    "scripts": {
        "cli": "utils/cli-test.js",
        "test": "utils/test.js",
    },

    // Tells the spellcraft engine to load this package as a spellcraft module.
    "spellcraft": true, 
}

test.jsonnet

Use this file as an example of how to use the functions and features provided by your module. It's highly recommended to make this file as comprehensive as possible, showcasing the correct usage and expected output of all your module's capabilities. This acts as both a test case and a clear usage example for users of your module.

Default npm run actions

There are two scripts created in package.json that are available by default within your project:

npm run cli

This imports your project as a module into the SpellCraft engine to let you test integration with the spellcraft CLI. Below are some examples of how to use it properly:

$ npm run cli
# Outputs all currently loaded Spellcraft commands from loaded modules

$ npm run cli generate
# Invokes the 'generate' command.

$ npm run cli -- -h
# Double-dashes ensures everything after it is passed to the Spellcraft CLI rather than letting `npm run` try
# to interpret it. In this case, it passes '-h' to Spellcraft, showing the help menu.

$ npm run cli -- apply -ys
# Here we use double-dashes to invoke the 'apply' command and pass the '-y' and '-s' flags to Spellcraft.

npm run test

This will attempt to manifest test.jsonnet in-memory and display the results. You should populate test.jsonnet with examples of all your exported JavaScript functions and JSonnet methods to let users see how they are used, and the results they create.