@c6fc/spellcraft 0.1.2 → 0.1.4

package/README.md

@@ -2,192 +2,169 @@
 
 **The Sorcerer's Toolkit for Unified Configuration Management.**
 
-SpellCraft is a powerful framework for generating and managing configurations across a diverse toolchain. It was born from the challenge of orchestrating tools like Terraform, Packer, Kubernetes, and Ansible, each with its own fragmented and isolated configuration format (YAML, JSON, HCL, etc.).
+SpellCraft is a plugin framework for [Jsonnet](https://jsonnet.org/) that bridges the gap between declarative configuration and the Node.js ecosystem. It allows you to import NPM packages directly into your Jsonnet logic, execute native JavaScript functions during configuration generation, and manage complex infrastructure-as-code requirements from a single, gnostic workflow.
 
-SpellCraft provides a single, unified source of truth, allowing you to generate tightly-integrated, context-aware configurations for any tool, all from one place.
+SpellCraft provides a single, unified source of truth, letting you orchestrate any tool that needs machine-readable configurations (like Terraform, Packer, Kubernetes, or Ansible) from one place.
 
 [![NPM Version](https://img.shields.io/npm/v/@c6fc/spellcraft.svg)](https://www.npmjs.com/package/@c6fc/spellcraft)
-[![License](https://img.shields.io/npm/l/@c6fc/spellcraft.svg)](https://github.com/your-repo/spellcraft/blob/main/LICENSE)
+[![License](https://img.shields.io/npm/l/@c6fc/spellcraft.svg)](https://github.com/c6fc/spellcraft/blob/main/LICENSE)
 
 ---
 
 ## The SpellCraft Philosophy
 
-SpellCraft is built on three core principles to provide a superior Infrastructure-as-Code experience:
-
-1.  **Declarative Power (Jsonnet):** Configurations are written in [Jsonnet](https://jsonnet.org/), a superset of JSON. This gives you the power of variables, functions, conditionals, loops, and inheritance, eliminating the endless copy-pasting and structural limitations of plain YAML or JSON. Define a component once, and reuse it everywhere.
-
-2.  **Seamless Extensibility (Node.js):** Sometimes, declarative logic isn't enough. SpellCraft allows you to "escape" the confines of Jsonnet by writing custom logic in Node.js. Need to fetch a secret from a vault, call a third-party API, or perform complex data manipulation? Simply write a JavaScript function and expose it directly to your Jsonnet code as a `std.native()` function.
-
-3.  **Robust Modularity (NPM):** SpellCraft's module system is built on the battle-tested foundation of NPM. This means you can version, share, and manage your infrastructure modules just like any other software dependency. Leverage public or private NPM registries to build a reusable, maintainable, and collaborative infrastructure codebase.
+1.  **Declarative Power (Jsonnet):** Configurations are written in Jsonnet. Variables, functions, and inheritance allow you to define components once and reuse them everywhere.
+2.  **Native Node.js Resolution:** No custom registries. No hidden magic. SpellCraft modules are just NPM packages. If you can `npm install` it, SpellCraft can load it.
+3.  **Scoped Extensibility:** Native JavaScript functions are automatically namespaced based on their package name, ensuring that dependencies never clash, even if multiple modules use different versions of the same library.
 
 ## Quick Start
 
-Get up and running with SpellCraft in minutes.
-
 ### 1. Installation
 
-Install the SpellCraft CLI and core library into your project.
+Install the CLI and core library.
 
 ```sh
 npm install --save @c6fc/spellcraft
 ```
 
-### 2. Import a Module
+### 2. Install a Plugin
 
-Modules are the building blocks of SpellCraft. Let's import a module for interacting with AWS. The `importModule` command will install the package from NPM and link it into your project.
+Install a SpellCraft-compatible plugin using standard NPM.
 
 ```sh
-npx spellcraft importModule @c6fc/spellcraft-aws-auth
-
-# Expected Output:
-# [*] Attempting to install @c6fc/spellcraft-aws-auth...
-# [+] Successfully installed @c6fc/spellcraft-aws-auth.
-# [+] Linked @c6fc/spellcraft-aws-auth as SpellCraft module 'awsauth'
+npm install --save @c6fc/spellcraft-aws-auth
 ```
-This makes the `@c6fc/spellcraft-aws-auth` package available in your Jsonnet files under the name `awsauth`.
 
-### 3. Create Your First Spell
+### 3. Write Your Spell
 
-A "Spell" is a `.jsonnet` file that defines the files you want to create. The top-level keys of the output object become filenames.
+Create a `manifest.jsonnet` file. Unlike previous versions of SpellCraft, you import modules explicitly using standard Node resolution.
 
-Create a file named `manifest.jsonnet`:
 ```jsonnet
-// manifest.jsonnet
-local modules = import 'modules';
+// Import the library directly from node_modules
+local aws = import '@c6fc/spellcraft-aws-auth/module.libsonnet';
 
 {
-  // The 'awsauth' module provides a native function `getCallerIdentity()`.
-  // We call it here and direct its output to a file named 'aws-identity.json'.
-  'aws-identity.json': modules.awsauth.getCallerIdentity(),
+  // Use functions provided by the module
+  'aws-identity.json': aws.getCallerIdentity(),
 
-  // We can also create YAML files. SpellCraft has built-in handlers for common types.
   'config.yaml': {
     apiVersion: 'v1',
     kind: 'ConfigMap',
-    metadata: {
-      name: 'my-app-config',
-    },
+    metadata: { name: 'my-app-config' },
     data: {
+      // Use built-in native functions
       region: std.native('envvar')('AWS_REGION') || 'us-east-1',
-      // The result of the native function is just data. We can reuse it!
-      callerArn: modules.awsauth.getCallerIdentity().Arn,
+      callerArn: aws.getCallerIdentity().Arn,
     },
   },
 }
 ```
 
-### 4. Generate the Artifacts
+### 4. Generate Artifacts
 
-Use the `generate` command to render your `.jsonnet` file into the `render/` directory.
+Run the generator. SpellCraft automatically detects installed plugins in your `package.json`, registers their native functions, and renders your configuration.
 
 ```sh
 npx spellcraft generate manifest.jsonnet
 
 # Expected Output:
-# [+] Linked @c6fc/spellcraft-aws-auth as awsauth.libsonnet
-# ...
-# [+] Registered native functions [getCallerIdentity, ...] to modules.awsauth
-# [+] Evaluating Jsonnet file manifest.jsonnet
+# [+] Evaluating Jsonnet file: .../manifest.jsonnet
 # [+] Writing files to: render
 #   -> aws-identity.json
 #   -> config.yaml
 # [+] Generation complete.
 ```
 
-Check your `render/` directory. You will find two files created from your single source of truth!
-
-```
-.
-├── manifest.jsonnet
-├── node_modules/
-├── package.json
-└── render/
-    ├── aws-identity.json
-    └── config.yaml
-```
+---
 
-## The SpellCraft CLI
+## Rapid Prototyping (Local Modules)
 
-The `spellcraft` CLI is your primary interface for managing modules and generating files.
+Sometimes you need a custom function just for your current project, and you don't want to publish a full NPM package. SpellCraft provides a **Local Magic** folder for this.
 
-### Core Commands
+1.  Create a folder named `spellcraft_modules` in your project root.
+2.  Create a JavaScript file, e.g., `spellcraft_modules/utils.js`:
 
--   `generate <filename>`: Renders a `.jsonnet` file and writes the output to the `render/` directory.
--   `importModule <npmPackage> [name]`: Installs an NPM package and links it as a SpellCraft module. If `[name]` is omitted, it uses the default name defined by the module.
+```javascript
+// spellcraft_modules/utils.js
+exports.shout = (text) => text.toUpperCase() + "!!!";
+exports.add = (a, b) => a + b;
 
-### Extensible CLI
+// Use standard functions to access 'this', which is extended by plugins:
+exports.know_thyself = function() {
+  this.aws.getCallerIdentity()
+}
+```
 
-Modules can extend the SpellCraft CLI with their own custom commands. For example, after importing `@c6fc/spellcraft-aws-auth`, you gain new AWS-related commands.
+3.  In your Jsonnet file, import `modules` to access your exported functions:
 
-Run `npx spellcraft --help` to see all available commands, including those added by modules.
+```jsonnet
+// Import the automatically generated local module aggregator
+local modules = import 'modules';
 
-```sh
-$ npx spellcraft --help
-
-# ... output showing core commands and module-added commands ...
-Commands:
-  spellcraft generate <filename>                Generates files from a configuration
-  spellcraft importModule <npmPackage> [name]   Configures the current project to use a SpellCraft module
-  spellcraft aws-identity                       Display the AWS IAM identity of the SpellCraft context	# Added by a module
-  spellcraft aws-exportcredentials              Export the current credentials as environment variables	# Added by a module
+{
+  'test.json': {
+    // Access your local JS functions here
+    // Our file was named 'utils.js', so the exported
+    // functions are accessed via 'modules.utils'.
+    message: modules.utils.shout("hello world"),
+    sum: modules.utils.add(10, 5)
+  }
+}
 ```
 
-## Programmatic Usage (API)
+---
+
+## The SpellCraft CLI
+
+The CLI is automatically extended by installed modules.
 
-For more advanced workflows, such as integration into larger automation scripts, you can use the `SpellFrame` class directly in your Node.js code.
+*   `spellcraft generate <filename>`: Renders a Jsonnet file to the `render/` directory.
+*   `spellcraft --help`: Lists all available commands, including those added by plugins (e.g., `spellcraft aws-identity`).
 
-The typical flow is:
-1.  Instantiate `SpellFrame`.
-2.  Run module initializers with `init()`.
-3.  Render the Jsonnet file with `render()`.
-4.  Write the resulting object to disk with `write()`.
+---
+
+## Programmatic API
+
+You can embed SpellCraft into your own Node.js scripts for advanced automation.
 
 ```javascript
-// my-automation-script.js
 const { SpellFrame } = require('@c6fc/spellcraft');
 const path = require('path');
 
-// 1. Instantiate the SpellFrame
-// Options allow you to customize output paths, cleaning behavior, etc.
-const frame = new SpellFrame({
-  renderPath: "dist", // Output to 'dist/' instead of 'render/'
-  cleanBeforeRender: true,
-});
+const frame = new SpellFrame();
 
 (async () => {
-    
-    // 2. Initialize modules before rendering.
+    // 1. Initialize: Scans package.json for plugins and loads them
     await frame.init();
 
-    // 3. Render the master Jsonnet file
-    const manifest = await frame.render(path.resolve('./manifest.jsonnet'));
-
-    // The result is available in memory
-    console.log('Rendered Manifest:', JSON.stringify(manifest, null, 2));
+    // 2. Render: Evaluates the Jsonnet
+    // Note: The result is a pure JS object
+    const result = await frame.render(path.resolve('./manifest.jsonnet'));
+    console.log(result);
 
-    // 4. Write the manifest object to the filesystem. Defaults to the contents of
-    // the most recent 'render'.
+    // 3. Write: Outputs files to disk (applying JSON/YAML transformations)
     frame.write();
+})();
+```
 
-    console.log('Successfully wrote files to the dist/ directory!');
+## Creating Modules
 
-})();
+A SpellCraft module is simply an NPM package with specific metadata. You can get a head-start with:
+```bash
+npm init spellcraft-module @your_org/your_module
 ```
 
-## Top-tier spellframe extensions by SpellCraft authors:
+Learn more at [**create-spellcraft-module**](https://www.npmjs.com/package/create-spellcraft-module)
 
-It can be hard to conceptualize what SpellCraft is capable of by just looking at the engine itself. Here are a set of SpellCraft modules that demonstrate the extensibility of the engine:
+## Community Modules
 
-|Package|Description|
+| Package | Description |
 |---|---|
-|[**@c6fc/spellcraft-aws-auth**](https://www.npmjs.com/package/@c6fc/spellcraft-aws-auth)|Exposes the full power of the AWS SDK for JavaScript to your SpellFrames, including native support for common AWS credential sources and role-chaining.|
-|[**@c6fc/spellcraft-terraform**](https://www.npmjs.com/package/@c6fc/spellcraft-terraform)|Brings Terraform into your SpellCraft CLI and SpellFrames, allowing you to directly deploy the results of your Spells.|
-|[**@c6fc/spellcraft-packer**](https://www.npmjs.com/package/@c6fc/spellcraft-packer)|Brings Packer into SpellCraft CLI and SpellFrames, allowing you to run builds against the results of your Spells.|
-|[**@c6fc/spellcraft-aws-terraform**](https://www.npmjs.com/package/@c6fc/spellcraft-aws-terraform)|Contains shortcuts for common use-cases when using Terraform to deploy configurations to AWS. Including backend bootstrapping, artifact repositories, and remote state access. It also demonstrates how modules can build on the capabilities of other modules.|
-|[**@c6fc/spellcraft-aws-s3**](https://www.npmjs.com/package/@c6fc/spellcraft-aws-s3)|A simple but powerful module for creating AWS S3 buckets. It uses secure defaults, exposes common use-cases as optional 'types', and grants extensive control with minimal code.|
+| [**@c6fc/spellcraft-aws-auth**](https://www.npmjs.com/package/@c6fc/spellcraft-aws-auth) | AWS SDK authentication and API calls directly from Jsonnet. |
+| [**@c6fc/spellcraft-terraform**](https://www.npmjs.com/package/@c6fc/spellcraft-terraform) | Terraform integration and state management. |
 
+---
 
-## Creating Your Own Modules
+## License
 
-When you're ready to start writing your own modules and unleashing the true power of SpellCraft, check out **[create-spellcraft-module](https://www.npmjs.com/package/@c6fc/spellcraft)**
+MIT © [Brad Woodward](https://github.com/c6fc)

package/bin/spellcraft.js

@@ -1,46 +1,16 @@
 #! /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 colors = require('@colors/colors');
 const { hideBin } = require('yargs/helpers');
 const { SpellFrame } = require('../src/index.js');
+const DocGenerator = require('../src/doc-generator');
 
 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
- */
-
-// --- 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]")
@@ -52,6 +22,12 @@ const spellframe = new SpellFrame();
                 console.log("[~] That's too arcane. (Unrecognized command)");
             })
 
+            .command("doc", "Generates Markdown documentation for the current module and updates README.md", () => {}, 
+            (argv) => {
+                const generator = new DocGenerator(process.cwd());
+                generator.generate();
+            })
+
             .command("generate <filename>", "Generates files from a configuration", (yargsInstance) => {
                 return yargsInstance.positional('filename', {
                     describe: 'Jsonnet configuration file to consume',
@@ -63,23 +39,17 @@ const spellframe = new SpellFrame();
                     description: 'Leave temporary modules intact after rendering'
                 });
             },
-            async (argv) => { // No JSDoc for internal handler
-                // try {
-                    if (argv['s']) {
-                        sfInstance.cleanModulesAfterRender = false;
-                    }
+            async (argv) => {
+                if (argv['s']) {
+                    sfInstance.cleanModulesAfterRender = false;
+                }
 
-                    await sfInstance.init();
-                    await sfInstance.render(argv.filename);
-                    await sfInstance.write();
-                    console.log("[+] Generation complete.");
-                /*} catch (error) {
-                    console.error(`[!] Error during generation: ${error.message.red}`);
-                    process.exit(1);
-                }*/
+                await sfInstance.init();
+                await sfInstance.render(argv.filename);
+                await sfInstance.write();
+                console.log("[+] Generation complete.");
             })
 
-        // 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') {

package/lib/spellcraft

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

package/package.json

@@ -3,11 +3,11 @@
     "@colors/colors": "^1.6.0",
     "@hanazuki/node-jsonnet": "^0.4.2",
     "js-yaml": "^4.1.0",
-    "yargs": "^17.2.1"
+    "yargs": "^18.0.0"
   },
   "name": "@c6fc/spellcraft",
   "description": "Extensible JSonnet CLI platform",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "main": "src/index.js",
   "directories": {
     "lib": "lib"
@@ -16,24 +16,20 @@
     "spellcraft": "bin/spellcraft.js"
   },
   "scripts": {
-    "test": "node src/test.js",
-    "doc": "jsdoc -c jsdoc.json --verbose"
+    "test": "node src/test.js"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/c6fc/spellcraft.git"
   },
   "keywords": [
-    "jsonnet"
+    "jsonnet",
+    "spellcraft"
   ],
   "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"
-  }
-}
+  "homepage": "https://github.com/c6fc/spellcraft#readme"
+}

package/src/doc-generator.js

@@ -0,0 +1,208 @@
+const fs = require('fs');
+const path = require('path');
+
+class DocGenerator {
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+
+    generate() {
+        const readmePath = path.join(this.baseDir, 'README.md');
+        if (!fs.existsSync(readmePath)) {
+            console.error("[!] No README.md found.");
+            return;
+        }
+
+        let readmeContent = fs.readFileSync(readmePath, 'utf-8');
+        const apiDocs = this.parseJsonnetDocs();
+        const cliDocs = this.parseCliDocs();
+
+        readmeContent = this.replaceSection(readmeContent, 'API', apiDocs);
+        readmeContent = this.replaceSection(readmeContent, 'CLI', cliDocs);
+
+        fs.writeFileSync(readmePath, readmeContent);
+        console.log("[+] README.md updated with generated documentation.");
+    }
+
+    // Helper to replace content between <!-- SPELLCRAFT_DOCS_XYZ_START --> tags
+    replaceSection(content, sectionName, newContent) {
+        const startTag = `<!-- SPELLCRAFT_DOCS_${sectionName}_START -->`;
+        const endTag = `<!-- SPELLCRAFT_DOCS_${sectionName}_END -->`;
+        const regex = new RegExp(`${startTag}[\\s\\S]*?${endTag}`, 'g');
+        
+        if (!regex.test(content)) {
+            console.log(`[-] No tags exist for ${sectionName}. Skipping.`);
+            // Do nothing if the tags don't exist.
+            return content;
+        }
+
+        return content.replace(regex, `${startTag}\n${newContent}\n${endTag}`);
+    }
+
+    parseJsonnetDocs() {
+        const libPath = path.join(this.baseDir, 'module.libsonnet');
+        if (!fs.existsSync(libPath)) return '';
+
+        const content = fs.readFileSync(libPath, 'utf-8');
+        // Regex to find /** comments */ followed by a function definition
+        // Captures: 1=Comment content, 2=FunctionName, 3=Args
+        const regex = /\/\*\*([\s\S]*?)\*\/\s*\n\s*([\w]+)\(([^)]*)\)/g;
+        
+        let match;
+        let markdown = "## API Reference\n\n";
+
+        while ((match = regex.exec(content)) !== null) {
+            const rawCommentLines = match[1].split('\n').map(line => 
+                // Remove the "   * " from the start of lines
+                line.replace(/^\s*\*\s?/, '')
+            );
+
+            const funcName = match[2];
+            const args = match[3];
+
+            let description = [];
+            let params = [];
+            let examples = []; // Array of arrays (one per example block)
+            let currentExampleBlock = null;
+            let mode = 'description'; 
+
+            rawCommentLines.forEach(line => {
+                const trimmed = line.trim();
+
+                // 1. Detect new @example block
+                if (trimmed.startsWith('@example')) {
+                    mode = 'example';
+                    currentExampleBlock = []; // Start a new container
+                    examples.push(currentExampleBlock);
+                    return; // Skip the tag line itself
+                }
+
+                // 2. Detect Metadata tags (@param, @return)
+                // We handle these regardless of mode, assuming they aren't part of the code example
+                if (trimmed.startsWith('@param') || trimmed.startsWith('@return')) {
+                    // Strip the @ and format as a list item
+                    params.push(`- ${trimmed.substring(1)}`);
+                    return; 
+                }
+
+                // 3. Capture Content
+                if (mode === 'example') {
+                    // Add line to the currently active example block
+                    if (currentExampleBlock) {
+                        currentExampleBlock.push(line);
+                    }
+                } else {
+                    // Add line to general description
+                    description.push(line);
+                }
+            });
+
+            // --- Build Markdown Output ---
+
+            markdown += `### \`${funcName}(${args})\`\n\n`;
+
+            // 1. Description
+            if (description.length > 0) {
+                markdown += description.join('\n').trim() + "\n\n";
+            }
+
+            // 2. Parameters / Returns
+            if (params.length > 0) {
+                markdown += params.join('\n') + "\n\n";
+            }
+
+            // 3. Examples (Loop through the array)
+            if (examples.length > 0) {
+                markdown += "**Examples:**\n\n";
+                examples.forEach(exBlock => {
+                    // Polish: Join lines and trim empty leading/trailing newlines
+                    const code = exBlock.join('\n').trim();
+                    if (code.length > 0) {
+                        markdown += "```jsonnet\n";
+                        markdown += code + "\n";
+                        markdown += "```\n\n";
+                    }
+                });
+            }
+
+            markdown += "---\n";
+        }
+        return markdown;
+    }
+
+    parseCliDocs() {
+        const jsPath = path.join(this.baseDir, 'module.js');
+        if (!fs.existsSync(jsPath)) return '';
+
+        try {
+            // Load the module (Bypass cache to ensure fresh read)
+            delete require.cache[require.resolve(jsPath)];
+            const moduleExports = require(jsPath);
+            const meta = moduleExports._spellcraft_metadata;
+
+            // Guard clauses
+            if (!meta || !meta.cliExtensions || typeof meta.cliExtensions !== 'function') {
+                return '';
+            }
+
+            const capturedCommands = [];
+
+            // Create a Proxy/Mock object to intercept yargs calls
+            const mockYargs = {
+                command: (command, description, ...args) => {
+                    // Capture the essential info
+                    capturedCommands.push({ command, description });
+                    return mockYargs; // Return self to allow chaining .command().command()
+                },
+                
+                // Stub out other common yargs methods so the script doesn't crash
+                // if the module uses .usage(), .option(), etc.
+                usage: () => mockYargs,
+                scriptName: () => mockYargs,
+                demandCommand: () => mockYargs,
+                recommendCommands: () => mockYargs,
+                strict: () => mockYargs,
+                showHelpOnFail: () => mockYargs,
+                help: () => mockYargs,
+                alias: () => mockYargs,
+                version: () => mockYargs,
+                epilogue: () => mockYargs,
+                option: () => mockYargs,
+                positional: () => mockYargs,
+                group: () => mockYargs,
+            };
+
+            // Mock SpellFrame (The second argument passed to cliExtensions)
+            // We mock this just in case the extension tries to read properties from it immediately
+            const mockSpellFrame = {
+                init: async () => {},
+                render: async () => {},
+                write: () => {},
+            };
+
+            // Execute the function!
+            meta.cliExtensions(mockYargs, mockSpellFrame);
+
+            // Generate Markdown
+            if (capturedCommands.length === 0) return '';
+
+            let markdown = "## CLI Commands\n\n";
+            
+            capturedCommands.forEach(c => {
+                // If description is explicitly false (hidden command), skip it
+                if (c.description === false) return;
+
+                markdown += `- **\`spellcraft ${c.command}\`**\n`;
+                markdown += `  ${c.description}\n`;
+            });
+
+            return markdown;
+
+        } catch (e) {
+            console.warn(`[!] Failed to parse CLI docs from module.js: ${e.message}`);
+            return '';
+        }
+    }
+}
+
+module.exports = DocGenerator;

package/src/index.js

@@ -60,6 +60,9 @@ exports.SpellFrame = class SpellFrame {
         this.functionContext = {};
         this.lastRender = null;
         this.activePath = null;
+        this.visitedPlugins = new Set();
+        this.loadedPlugins = new Map();
+        this.isInitialized = false;
 
         this.jsonnet = new Jsonnet()
             .addJpath(path.join(__dirname, '../lib'))
@@ -73,6 +76,8 @@ exports.SpellFrame = class SpellFrame {
 
         // REFACTOR: Automatically find and register plugins from package.json
         this.loadPluginsFromDependencies();
+        this.loadPluginsRecursively(baseDir);
+        this.validatePluginRequirements();
 
         // 2. Load Local Magic Modules (Rapid Prototyping Mode)
         this.loadLocalMagicModules();
@@ -117,27 +122,29 @@ exports.SpellFrame = class SpellFrame {
                 this.addFileTypeHandler(pattern, handler);
             });
         }
+
         if (metadata.cliExtensions) {
             this.cliExtensions.push(...(Array.isArray(metadata.cliExtensions) ? metadata.cliExtensions : [metadata.cliExtensions]));
         }
-        if (metadata.initFn) {
-            this.initFn.push(...(Array.isArray(metadata.initFn) ? metadata.initFn : [metadata.initFn]));
+
+        if (metadata.init) {
+            this.initFn.push(...(Array.isArray(metadata.init) ? metadata.init : [metadata.init]));
         }
+
         Object.assign(this.functionContext, metadata.functionContext || {});
         return this;
     }
 
     async init() {
+        if (this.isInitialized) return;
+
         for (const step of this.initFn) {
             await step.call();
         }
+
+        this.isInitialized = true;
     }
 
-    /**
-     * REFACTOR: Scans the project's package.json for dependencies.
-     * If a dependency has a 'spellcraft' key in its package.json, 
-     * load its JS entrypoint and register native functions safely.
-     */
     loadPluginsFromDependencies() {
         const packageJsonPath = path.join(baseDir, 'package.json');
         if (!fs.existsSync(packageJsonPath)) return;
@@ -175,11 +182,6 @@ exports.SpellFrame = class SpellFrame {
         });
     }
 
-    /**
-     * Scans the local 'spellcraft_modules' directory.
-     * 1. Registers JS exports as native functions (prefixed with 'local_<filename>_').
-     * 2. Generates a .spellcraft/modules.libsonnet file to allow `import 'modules'`.
-     */
     loadLocalMagicModules() {
         const localModulesDir = path.join(baseDir, 'spellcraft_modules');
         const generatedDir = path.join(baseDir, '.spellcraft');
@@ -251,14 +253,13 @@ exports.SpellFrame = class SpellFrame {
         fs.writeFileSync(aggregateFile, finalContent, 'utf-8');
     }
 
-    /**
-     * REFACTOR: Loads a specific plugin JS file.
-     * Namespaces native functions using the package name to prevent collisions.
-     * e.g., @c6fc/spellcraft-aws-auth exports 'aws' -> registered as '@c6fc/spellcraft-aws-auth:aws'
-     */
     loadPlugin(packageName, jsMainPath) {
         if (!jsMainPath || !fs.existsSync(jsMainPath)) return;
 
+        if (this.loadedPlugins.has(packageName)) {
+            return;
+        }
+
         let moduleExports;
         try {
             moduleExports = require(jsMainPath);
@@ -269,6 +270,11 @@ exports.SpellFrame = class SpellFrame {
 
         if (moduleExports._spellcraft_metadata) {
             this.extendWithModuleMetadata(moduleExports._spellcraft_metadata);
+
+            this.loadedPlugins.set(packageName, {
+                name: packageName,
+                requires: moduleExports._spellcraft_metadata.requires || []
+            });
         }
 
         Object.keys(moduleExports).forEach(key => {
@@ -294,7 +300,63 @@ exports.SpellFrame = class SpellFrame {
         });
     }
 
+    loadPluginsRecursively(currentDir) {
+        const packageJsonPath = path.join(currentDir, 'package.json');
+        
+        // If we've already scanned this specific directory, stop (Circular Dep protection)
+        if (this.visitedPlugins.has(packageJsonPath)) return;
+        this.visitedPlugins.add(packageJsonPath);
+
+        if (!fs.existsSync(packageJsonPath)) return;
+
+        let pkg;
+        try {
+            pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        } catch (e) { return; }
+
+        // Combine dependencies (devDeps are usually only relevant at the root, 
+        // but we scan both for completeness at the root level).
+        // For sub-dependencies, standard 'dependencies' is usually what matters.
+        const deps = { ...pkg.dependencies, ...(currentDir === baseDir ? pkg.devDependencies : {}) };
+
+        // Create a resolver anchored to the CURRENT directory.
+        // This is crucial: it tells Node "Find dependencies relative to THIS module",
+        // not relative to the root project.
+        const localResolver = require('module').createRequire(packageJsonPath);
+
+        Object.keys(deps).forEach(depName => {
+            try {
+                // 1. Resolve where this dependency actually lives on disk
+                const depManifestPath = localResolver.resolve(`${depName}/package.json`);
+                const depDir = path.dirname(depManifestPath);
+
+                // 2. Load its package.json
+                const depPkg = require(depManifestPath);
+
+                // 3. Check if it is a SpellCraft module
+                if (depPkg.spellcraft) {
+                    
+                    // A. Load the Plugin Logic
+                    const jsMainPath = path.join(depDir, depPkg.main || 'index.js');
+                    this.loadPlugin(depPkg.name, jsMainPath);
+
+                    // B. Recurse!
+                    // Now scan *this* dependency's dependencies
+                    this.loadPluginsRecursively(depDir);
+                }
+            } catch (e) {
+                // Dependency might be optional or failed to resolve; skip gracefully
+                // console.warn(`Debug: Skipped ${depName} from ${currentDir}: ${e.message}`);
+            }
+        });
+    }
+
     async render(file) {
+
+        if (!this.isInitialized) {
+            await this.init();
+        }
+
         const absoluteFilePath = path.resolve(file);
         if (!fs.existsSync(absoluteFilePath)) {
             throw new Error(`SpellCraft Render Error: Input file ${absoluteFilePath} does not exist.`);
@@ -329,11 +391,22 @@ exports.SpellFrame = class SpellFrame {
         return this.lastRender;
     }
 
-    // Removed: importSpellCraftModuleFromNpm
-    // Removed: loadModulesFromModuleDirectory
-    // Removed: loadModulesFromPackageList
-    // Removed: loadModuleByName (file copier)
-
+    validatePluginRequirements() {
+        for (const [pluginName, data] of this.loadedPlugins.entries()) {
+            if (!data.requires || data.requires.length === 0) continue;
+
+            data.requires.forEach(req => {
+                if (!this.loadedPlugins.has(req)) {
+                    throw new Error(
+                        `[SpellCraft Dependency Error] The module '${pluginName}' requires '${req}', ` +
+                        `but '${req}' was not found or failed to load. \n` +
+                        `    -> Try running: npm install --save ${req}`
+                    );
+                }
+            });
+        }
+    }
+    
     write(filesToWrite = this.lastRender) {
         if (!filesToWrite || typeof filesToWrite !== 'object') return this;
 

package/jsdoc.json

@@ -1,32 +0,0 @@
-{
-    "tags": {
-        "allowUnknownTags": true
-    },
-    "plugins": ["plugins/markdown"],
-    "opts": {
-        "destination": "./docs"
-    },
-    "source": {
-        "include": [
-            "src/",
-            "bin/"
-        ],
-        "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"
-    }
-}