Forge Your Own Reality

The requires array ensures that dependent modules are always loaded into the SpellFrame first. This guarantees that any required function context, native utilities, or initialization prerequisites from those modules are present and active before your own module manifests.

exports._spellcraft_metadata = {
  requires: [
    "@c6fc/spellcraft-aws-auth",
    "@c6fc/spellcraft-k8s-utils"
  ]
};

Register custom transmutations for specific file extensions. When the Spellcraft engine encounters a file matching your regex, it passes the raw content through these handlers, allowing you to parse complex formats into native objects that Jsonnet can consume.

exports._spellcraft_metadata = {
  fileTypeHandlers: {
    // Transform .foo files into formatted JSON strings
    '.*?\.foo': (content) => JSON.stringify(content, null, 4)
  }
};

Define properties that should be grafted onto the this context for your native functions. This is ideal for sharing heavy utility objects, configuration constants, or SDK instances across multiple exports without polluting the global scope.

const utils = require('./utils');

exports._spellcraft_metadata = {
  functionContext: { 
    helpers: utils,
    apiVersion: "v1.4.2"
  }
};

// Accessible via `this` in native functions:
exports.myFunc = [function() { 
  return this.helpers.format(this.apiVersion); 
}];

Inject custom commands and flags directly into the spellcraft terminal interface. By utilizing the provided yargs and spellframe instances, you can build specialized sub-rituals that interact with the engine's core rendering pipeline.

exports._spellcraft_metadata = {
  cliExtensions: (yargs, spellframe) => {
    yargs.command("echo ", "Print a message", 
      (yargs) => yargs.positional('msg', { describe: 'The message' }),
      async (argv) => {
        await spellframe.init();
        console.log(argv.msg);
      }
    );
  }
};

To test your new command, use the cli script provided in your module's package.json. This allows you to invoke the local engine with your module pre-loaded, verifying that your sub-command is registered and functional.

The primary lifecycle anchor for your module. The init hook is an asynchronous function called during the engine's boot sequence. Use this space to establish network connections or prepare stateful contexts needed by your functions.

exports._spellcraft_metadata = {
  init: async () => {
    // Setup environment for the engine
    process.env.ARCANE_DEBUG = "true";
    await someArcaneProvider.connect();
  }
};

Native power follows a sacred path from JavaScript to your Jsonnet spells. Any export from module.js is registered by the engine as a native function named <package>:<export_name>.

// Register a native function with the engine
exports.shout = [
  (text) => text.toUpperCase() + "!!!",
  "text" // Argument metadata
];

// Wrap the namespaced native call for consumers
{
  shout(text): std.native('my-package:shout')(text)
}

local myMod = import 'my-package/module.libsonnet';

{
  message: myMod.shout("hello world") 
} 
// Result: { "message": "HELLO WORLD!!!" }