@vizualmodel/vmblu-cli 0.1.0 → 0.2.0

package/bin/vmblu.js

@@ -1,47 +1,65 @@
 #!/usr/bin/env node
-/* Minimal subcommand router: vmblu <command> [args] */
-const fs = require('fs');
-const path = require('path');
-
-const root = path.join(__dirname, '..');
-const commandsDir = path.join(root, 'commands');
-
-function printGlobalHelp() {
-  const cmds = fs.readdirSync(commandsDir)
-    .filter(n => fs.existsSync(path.join(commandsDir, n, 'index.js')));
-  console.log(`vmblu <command> [options]
-
-Commands:
-  ${cmds.map(c => `- ${c}`).join('\n  ')}
-
-Run "vmblu <command> --help" for details.`);
-}
-
-async function run() {
-  const [,, cmd, ...rest] = process.argv;
-
-  if (!cmd || ['-h','--help','help'].includes(cmd)) {
-    printGlobalHelp(); process.exit(0);
-  }
-  if (['-v','--version','version'].includes(cmd)) {
-    console.log(require(path.join(root, 'package.json')).version); process.exit(0);
-  }
-
-  const entry = path.join(commandsDir, cmd, 'index.js');
-  if (!fs.existsSync(entry)) {
-    console.error(`Unknown command: ${cmd}\n`); printGlobalHelp(); process.exit(1);
-  }
-
-  const mod = require(entry);
-  // Optional per-command help
-  if (rest.includes('--help') || rest.includes('-h')) {
-    console.log(`vmblu ${mod.command}\n\n${mod.describe}\n\nOptions:\n${(mod.builder || []).map(o => `  ${o.flag}\t${o.desc}`).join('\n')}`);
-    process.exit(0);
-  }
-  await mod.handler(rest);
-}
-
-run().catch(err => {
-  console.error(err?.stack || String(err));
-  process.exit(1);
-});
+/* Minimal subcommand router: vmblu <command> [args] */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const root = path.join(__dirname, '..');
+const commandsDir = path.join(root, 'commands');
+
+function printGlobalHelp() {
+  const cmds = fs.readdirSync(commandsDir)
+    .filter((name) => fs.existsSync(path.join(commandsDir, name, 'index.js')));
+  console.log(`vmblu <command> [options]
+
+Commands:
+  ${cmds.map((c) => `- ${c}`).join('\n  ')}
+
+Run "vmblu <command> --help" for details.`);
+}
+
+async function run() {
+  const [, , cmd, ...rest] = process.argv;
+
+  if (!cmd || ['-h', '--help', 'help'].includes(cmd)) {
+    printGlobalHelp();
+    process.exit(0);
+  }
+
+  if (['-v', '--version', 'version'].includes(cmd)) {
+    const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
+  const entry = path.join(commandsDir, cmd, 'index.js');
+  if (!fs.existsSync(entry)) {
+    console.error(`Unknown command: ${cmd}\n`);
+    printGlobalHelp();
+    process.exit(1);
+  }
+
+  const mod = await import(pathToFileURL(entry));
+  const handler = mod.handler ?? mod.default;
+  if (typeof handler !== 'function') {
+    console.error(`Command "${cmd}" does not export a runnable handler.`);
+    process.exit(1);
+  }
+
+  if (rest.includes('--help') || rest.includes('-h')) {
+    const command = mod.command ?? cmd;
+    const describe = mod.describe ?? '';
+    const builder = Array.isArray(mod.builder) ? mod.builder : [];
+    console.log(`vmblu ${command}\n\n${describe}\n\nOptions:\n${builder.map((o) => `  ${o.flag}\t${o.desc}`).join('\n')}`);
+    process.exit(0);
+  }
+
+  await handler(rest);
+}
+
+run().catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});

package/commands/init/index.js

@@ -1,20 +1,23 @@
-// vmblu init [targetDir] --name <project> --schema <ver> --force --dry-run
-const path = require('path');
-const { initProject } = require('./init-project');
+// vmblu init [targetDir] --name <project> --schema <ver> --force --dry-run
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { initProject } from './init-project.js';
 
-exports.command = 'init';
-exports.describe = 'Scaffold an empty vmblu project';
-exports.builder = [
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const command = 'init <folder name>';
+export const describe = 'Scaffold an empty vmblu project';
+export const builder = [
   { flag: '--name <project>', desc: 'Project name (default: folder name)' },
   { flag: '--schema <ver>',   desc: 'Schema version (default: 0.8.2)' },
   { flag: '--force',          desc: 'Overwrite existing files' },
   { flag: '--dry-run',        desc: 'Show actions without writing' }
 ];
 
-exports.handler = async (argv) => {
+export const handler = async (argv) => {
   // tiny arg parse (no deps)
   const args = { _: [] };
-  for (let i=0;i<argv.length;i++) {
+  for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--force') args.force = true;
     else if (a === '--dry-run') args.dryRun = true;
@@ -31,8 +34,8 @@ exports.handler = async (argv) => {
     targetDir,
     projectName,
     schemaVersion,
-    force: !!args.force,
-    dryRun: !!args.dryRun,
+    force: Boolean(args.force),
+    dryRun: Boolean(args.dryRun),
     templatesDir: path.join(__dirname, '..', '..', 'templates'),
     ui: {
       info: (m) => console.log(m),
@@ -41,5 +44,6 @@ exports.handler = async (argv) => {
     }
   });
 
-  console.log(`✔ vmblu project scaffolded in ${targetDir}`);
+  console.log(`vmblu project scaffolded in ${targetDir}`);
 };
+

package/commands/init/init-project.js

@@ -1,10 +1,10 @@
 // core/initProject.js
 // Node 18+ (fs/promises, crypto). No external deps.
-const fs = require('fs/promises');
-const fssync = require('fs');
-const path = require('path');
-//const crypto = require('crypto');
-const pckg = require('./make-package-json');
+import * as fs from 'fs/promises';
+import * as fssync from 'fs';
+import path from 'path';
+//import crypto from 'crypto';
+import { makePackageJson } from './make-package-json.js';
 
 function rel(from, to) {
   return path.posix.join(...path.relative(from, to).split(path.sep));
@@ -251,7 +251,7 @@ async function initProject(opts) {
   }
 
   // 5) Make the package file
-  pckg.makePackageJson(  {absTarget, projectName, force, dryRun, addCliDep: true, cliVersion: "^0.1.0"}, ui);
+  makePackageJson({ absTarget, projectName, force, dryRun, addCliDep: true, cliVersion: "^0.1.0" }, ui);
 
   // 6) Final tree hint
   ui.info(`\nScaffold complete${dryRun ? ' (dry run)' : ''}:\n` +
@@ -285,4 +285,4 @@ async function initProject(opts) {
   };
 }
 
-module.exports = { initProject };
+export { initProject };

package/commands/init/make-package-json.js

@@ -1,7 +1,7 @@
-const fs = require('fs/promises');
-const path = require('path');
-
-async function readJsonIfExists(file) {
+import * as fs from 'fs/promises';
+import path from 'path';
+
+async function readJsonIfExists(file) {
   try { return JSON.parse(await fs.readFile(file, 'utf8')); } catch { return null; }
 }
 
@@ -9,10 +9,10 @@ function sortKeys(obj) {
   return Object.fromEntries(Object.entries(obj).sort(([a],[b]) => a.localeCompare(b)));
 }
 
-async function makePackageJson({
-  absTarget, projectName, force, dryRun,
-  addCliDep = true, cliVersion = "^0.1.0"
-}, ui) {
+export async function makePackageJson({
+  absTarget, projectName, force, dryRun,
+  addCliDep = true, cliVersion = "^0.1.0"
+}, ui) {
   const pkgPath = path.join(absTarget, 'package.json');
   const existing = await readJsonIfExists(pkgPath);
 
@@ -54,6 +54,5 @@ async function makePackageJson({
     await fs.writeFile(pkgPath, JSON.stringify(ordered, null, 2) + '\n', 'utf8');
   }
 
-  return pkgPath;
-}
-module.exports = { makePackageJson };
+  return pkgPath;
+}

package/commands/profile/find-handlers.js

@@ -0,0 +1,351 @@
+// extractHandlersFromFile.js
+
+import ts from 'typescript';
+
+export let currentNode = null;
+export let topLevelClass = null
+let nodeMap = null
+let filePath = null
+
+export function findHandlers(sourceFile, _filePath, _nodeMap) {
+  
+    // Reset any node context carried over from previous files.
+    currentNode = null;
+
+    // The fallback name is the top-level class
+    topLevelClass = sourceFile.getClasses()[0]?.getName?.() || null;
+    nodeMap = _nodeMap
+    filePath = _filePath
+
+    // Check all the functions in the sourcefile - typically generator functions
+    sourceFile.getFunctions().forEach(fn => {
+
+        // Capture node annotations on generator-style functions and harvest handlers returned from them.
+        const jsdoc = getFullJsDoc(fn);
+        updateNodeFromJsdoc(jsdoc);
+
+        const name = fn.getName();
+
+        if (isHandler(name)) {
+
+            const line = fn.getNameNode()?.getStartLineNumber() ?? fn.getStartLineNumber();
+            const docTags = getParamDocs(fn);
+            const params = fn.getParameters().flatMap(p => describeParam(p, docTags));
+
+            collect(name, params, line, jsdoc);
+        }
+
+        collectHandlersFromFunctionReturns(fn);
+    });
+
+    // Check the variable declarations in the sourcefile
+    sourceFile.getVariableDeclarations().forEach(decl => {
+
+        // check the name
+        const name = decl.getName();
+        const init = decl.getInitializer();
+        const line = decl.getStartLineNumber();
+        const jsdoc = getFullJsDoc(decl);
+        updateNodeFromJsdoc(jsdoc);
+
+        // check if the name is a handler and initialised with a function
+        if (isHandler(name) && init && init.getKindName().includes('Function')) {
+
+            const docTags = getParamDocs(decl);
+            const params = init.getParameters().flatMap(p => describeParam(p, docTags));
+
+            collect(name, params, line, jsdoc);
+        }
+
+        if (init && init.getKind() === ts.SyntaxKind.ObjectLiteralExpression) {
+            collectObjectLiteralHandlers(init);
+        }
+    });
+
+    // check all the classes in the file
+    sourceFile.getClasses().forEach(cls => {
+
+        // get the name of the node
+        const nodeName = cls.getName?.() || topLevelClass;
+
+        // check all the methods
+        cls.getMethods().forEach(method => {
+
+            // check the name
+            const name = method.getName();
+            if (!isHandler(name)) return;
+
+            // extract
+            const line = method.getNameNode()?.getStartLineNumber() ?? method.getStartLineNumber();
+            const jsdoc = getFullJsDoc(method);
+            const docTags = getParamDocs(method);
+            const params = method.getParameters().flatMap(p => describeParam(p, docTags));
+
+            // and collect
+            collect(name, params, line, jsdoc, nodeName);
+        });
+    });
+
+    // check all the statements
+    sourceFile.getStatements().forEach(stmt => {
+
+        // only binary expressions
+        if (!stmt.isKind(ts.SyntaxKind.ExpressionStatement)) return;
+        const expr = stmt.getExpression();
+        if (!expr.isKind(ts.SyntaxKind.BinaryExpression)) return;
+
+        // get the two parts of the statement
+        const left = expr.getLeft().getText();
+        const right = expr.getRight();
+
+        // check for protype
+        if (left.includes('.prototype.') && right.isKind(ts.SyntaxKind.FunctionExpression)) {
+
+            // get the name and check
+            const parts = left.split('.');
+            const name = parts[parts.length - 1];
+            if (!isHandler(name)) return;
+
+            // extract
+            const line = expr.getStartLineNumber();
+            const params = right.getParameters().flatMap(p => describeParam(p));
+            const jsdoc = getFullJsDoc(expr);
+
+            // and save in nodemap
+            collect(name, params, line, jsdoc);
+        }
+
+        if (left.endsWith('.prototype') && right.isKind(ts.SyntaxKind.ObjectLiteralExpression)) {
+            collectObjectLiteralHandlers(right);
+        }
+    });
+}
+
+
+function collectHandlersFromFunctionReturns(fn) {
+
+    // Look for factory-style returns that expose handlers via object literals.
+    fn.getDescendantsOfKind(ts.SyntaxKind.ReturnStatement).forEach(ret => {
+        const expr = ret.getExpression();
+        if (!expr || expr.getKind() !== ts.SyntaxKind.ObjectLiteralExpression) return;
+
+        collectObjectLiteralHandlers(expr);
+    });
+}
+
+function collectObjectLiteralHandlers(objectLiteral) {
+
+    // Reuse the same extraction logic for any handler stored on an object literal shape.
+    objectLiteral.getProperties().forEach(prop => {
+
+        const propName = prop.getName?.();
+        if (!isHandler(propName)) return;
+
+        let params = [];
+        if (prop.getKind() === ts.SyntaxKind.MethodDeclaration) {
+            const docTags = getParamDocs(prop);
+            params = prop.getParameters().flatMap(p => describeParam(p, docTags));
+        } else if (prop.getKind() === ts.SyntaxKind.PropertyAssignment) {
+            const fn = prop.getInitializerIfKind(ts.SyntaxKind.FunctionExpression) || prop.getInitializerIfKind(ts.SyntaxKind.ArrowFunction);
+            if (fn) {
+                const docTags = getParamDocs(fn);
+                params = fn.getParameters().flatMap(p => describeParam(p, docTags));
+            }
+        }
+
+        const jsdoc = getFullJsDoc(prop);
+        const line = prop.getStartLineNumber();
+
+        collect(propName, params, line, jsdoc);
+    });
+}
+
+function updateNodeFromJsdoc(jsdoc = {}) {
+
+    const nodeTag = jsdoc.tags?.find(t => t.tagName === 'node')?.comment;
+    if (nodeTag) currentNode = nodeTag.trim();
+}
+
+function collect(rawName, params, line, jsdoc = {}) {
+
+    //if (!isHandler(rawName)) return;
+    const cleanHandler = rawName.replace(/^['"]|['"]$/g, '');
+
+    let pin = null;
+    let node = null;
+
+    const pinTag = jsdoc.tags?.find(t => t.tagName === 'pin')?.comment;
+    const nodeTag = jsdoc.tags?.find(t => t.tagName === 'node')?.comment;
+    const mcpTag = jsdoc.tags?.find(t => t.tagName === 'mcp')?.comment ?? null;
+
+    // if there is a node tag, change the name of the current node
+    if (nodeTag) currentNode = nodeTag.trim();
+
+    // check the pin tag to get a pin name and node name
+    if (pinTag) {
+
+        if (pinTag.includes('@')) {
+            const [p, n] = pinTag.split('@').map(s => s.trim());
+            pin = p;
+            node = n;
+        }
+        else pin = pinTag.trim();
+
+        // Use the current context when the pin tag does not specify a node.
+        if (!node) node = currentNode || topLevelClass || null;
+    }
+
+    // check the pin tag to get a pin name and node name
+    // if (pinTag && pinTag.includes('@')) {
+    //     const [p, n] = pinTag.split('@').map(s => s.trim());
+    //     pin = p;
+    //     node = n;
+    // } 
+    else {
+
+        // no explicit tag - try these...
+        node = currentNode || topLevelClass || null;
+
+        // deduct the pin name from the handler name
+        if (cleanHandler.startsWith('on')) {
+            pin = cleanHandler.slice(2).replace(/([A-Z])/g, ' $1').trim().toLowerCase();
+        } else if (cleanHandler.startsWith('->')) {
+            pin = cleanHandler.slice(2).trim();
+        }
+    }
+
+    // if there is no node we just don't save the data
+    if (!node) return
+
+    // check if we have an entry for the node
+    if (!nodeMap.has(node)) nodeMap.set(node, { handles: [], transmits: [] });
+
+    // The handler data to save
+    const handlerData = {
+        pin,
+        handler: cleanHandler,
+        file: filePath,
+        line,
+        summary: jsdoc.summary || '',
+        returns: jsdoc.returns || '',
+        examples: jsdoc.examples || [],
+        params
+    };
+
+    // extract the data from an mcp tag if present
+    if (mcpTag !== null) {
+        handlerData.mcp = true;
+        if (mcpTag.includes('name:') || mcpTag.includes('description:')) {
+            const nameMatch = /name:\s*\"?([^\"]+)\"?/.exec(mcpTag);
+            const descMatch = /description:\s*\"?([^\"]+)\"?/.exec(mcpTag);
+            if (nameMatch) handlerData.mcpName = nameMatch[1];
+            if (descMatch) handlerData.mcpDescription = descMatch[1];
+        }
+    }
+
+    // and put it in the nodemap
+    nodeMap.get(node).handles.push(handlerData);
+  };
+
+// determines if a name is the name for a handler
+function isHandler(name) {
+    // must be a string
+    if (typeof name !== 'string') return false;
+
+    // get rid of " and '
+    const clean = name.replace(/^['"]|['"]$/g, '');
+
+    // check that it starts with the right symbols...
+    return clean.startsWith('on') || clean.startsWith('->');
+}
+
+// Get the parameter description from the function or method
+function getParamDocs(fnOrMethod) {
+
+    // extract
+    const docs = fnOrMethod.getJsDocs?.() ?? [];
+    const tags = docs.flatMap(d => d.getTags());
+    const paramDocs = {};
+
+    // check the tags
+    for (const tag of tags) {
+        if (tag.getTagName() === 'param') {
+            const name = tag.getNameNode()?.getText?.() || tag.getName();
+            const desc = tag.getComment() ?? '';
+            const type = tag.getTypeNode?.()?.getText?.() || tag.getTypeExpression()?.getTypeNode()?.getText();
+            paramDocs[name] = { description: desc, type };
+        }
+    }
+    return paramDocs;
+}
+
+// Get the jsdoc 
+function getFullJsDoc(node) {
+
+    const docs = node.getJsDocs?.() ?? [];
+    const summary = docs.map(d => d.getComment()).filter(Boolean).join('\n');
+    const tags = docs.flatMap(d => d.getTags()).map(t => ({
+        tagName: t.getTagName(),
+        comment: t.getComment() || ''
+    }));
+
+    const returns = tags.find(t => t.tagName === 'returns')?.comment || '';
+    const examples = tags.filter(t => t.tagName === 'example').map(t => t.comment);
+
+    return { summary, returns, examples, tags };
+}
+
+// make a parameter description
+function describeParam(p, docTags = {}) {
+
+    const nameNode = p.getNameNode();
+
+// const func = p.getParent();
+// const funcName = func.getName?.() || '<anonymous>';
+// console.log(funcName)
+
+    if (nameNode.getKindName() === 'ObjectBindingPattern') {
+
+        const objType = p.getType();
+        const properties = objType.getProperties();
+        const isTSFallback = objType.getText() === 'any' || objType.getText() === 'string' || properties.length === 0;
+
+        return nameNode.getElements().map(el => {
+
+            const subName = el.getName();
+            const doc = docTags[subName] ?? {};
+            let tsType = null;
+
+            if (!isTSFallback) {
+                const symbol = objType.getProperty(subName);
+                if (symbol) {
+                    const resolvedType = symbol.getTypeAtLocation(el);
+                    const text = resolvedType.getText();
+                    if (text && text !== 'any') {
+                        tsType = text;
+                    }
+                }
+            }
+
+            const type = tsType || doc.type || 'string';
+            const description = doc.description || '';
+            return { name: subName, type, description };
+        });
+    }
+
+    const name = p.getName();
+    const doc = docTags[name] ?? {};
+    const tsType = p.getType().getText();
+
+    // const isTSFallback = tsType === 'any' || tsType === 'string';
+    // if (isTSFallback && !doc.type) {
+    //   console.warn(`⚠️ No type info for param "${name}" in function "${funcName}"`);
+    // }
+
+    return {
+        name,
+        type: doc.type || tsType || 'string',
+        description: doc.description || '',
+    };
+}
+

package/commands/profile/find-transmissions.js

@@ -0,0 +1,54 @@
+import { SyntaxKind } from 'ts-morph';
+import {currentNode, topLevelClass} from './find-handlers.js'
+
+/**
+ * Finds tx.send or this.tx.send calls and maps them to their node context.
+ * 
+ * @param {import('ts-morph').SourceFile} sourceFile - The source file being analyzed
+ * @param {string} filePath - The (relative) path of the source file
+ * @param {Map} nodeMap - Map from node name to metadata
+ * @param {string|null} currentNode - Explicitly set node name (takes priority)
+ */
+export function findTransmissions(sourceFile, filePath, nodeMap) {
+
+    // Search all call expressions
+    sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression).forEach(node => {
+        const expr = node.getExpression();
+
+        // check
+        if (expr.getKind() !== SyntaxKind.PropertyAccessExpression) return
+
+        // Match tx.send or this.tx.send - regular expression could be : expr.getText().match(/\w+\.tx\.send/)
+        const text = expr.getText()
+
+        // check
+        if (! (text === 'tx.send' || text === 'this.tx.send' || text.endsWith('.tx.send'))) return;
+
+        const args = node.getArguments();
+        if (args.length === 0 || !args[0].isKind(SyntaxKind.StringLiteral)) return;
+
+        const pin = args[0].getLiteralText();
+
+        // Try to infer the class context of the tx.send call
+        const method = node.getFirstAncestorByKind(SyntaxKind.MethodDeclaration);
+        const classDecl = method?.getFirstAncestorByKind(SyntaxKind.ClassDeclaration) ?? node.getFirstAncestorByKind(SyntaxKind.ClassDeclaration);
+        const className = classDecl?.getName?.();
+
+        // Priority order: currentNode > className > topLevelClass > 'global'
+        const nodeName = currentNode || className || topLevelClass || null;
+
+        // check
+        if (!nodeName) return
+
+        // check if there is an entry for the node or create it 
+        nodeMap.has(nodeName) || nodeMap.set(nodeName, { handles: [], transmits: [] });
+
+        // add the entry to the transmits array
+        nodeMap.get(nodeName).transmits.push({
+            pin,
+            file: filePath,
+            line: node.getStartLineNumber()
+        });
+    });
+}
+

package/commands/profile/index.js

@@ -0,0 +1,16 @@
+import { profile } from './profile.js';
+
+export const command = 'profile <model-file>';
+export const describe = 'Find message handlers and message transmissions.';
+
+export const builder = [
+  { flag: '--out <file>', desc: 'specifies the output file' },
+  { flag: '--full', desc: 'check all source files in the model' },
+  { flag: '--changed <files...>', desc: 'only check changed files' },
+  { flag: '--deleted <files...>', desc: 'remove data from deleted files' },
+  { flag: '--delta-file <path>', desc: 'write the delta to a file' },
+  { flag: '--reason <text>', desc: 'information' },
+];
+
+export const handler = profile;
+

package/commands/profile/profile.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+
+// Native
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import ts from 'typescript';
+
+// ts-morph
+import { Project } from 'ts-morph';
+
+// vmblu
+import { ModelBlueprint, ModelCompiler } from '../../../core/model/index.js';
+import { ARL } from '../../../core/arl/arl-node.js'
+
+// profile tool
+import {findHandlers} from './find-handlers.js'
+import {findTransmissions} from './find-transmissions.js'
+
+const SRC_DOC_VERSION = '0.2';
+
+// The main function for the profile tool
+export async function profile(argv = process.argv.slice(2)) {
+
+    const cli = parseCliArgs(argv);
+
+    if (!cli.modelFile) {
+        //console.error('Usage: node profile <model-file> [--out <file>] [--full] [--changed <files...>] [--deleted <files...>] [--delta-file <path>] [--reason <text>]');
+        console.error('Usage: vmblu profile <model-file> [--out <file>] [--full] [--changed <files...>] [--deleted <files...>] [--delta-file <path>] [--reason <text>]');
+        process.exit(1);
+    }
+
+    const absoluteModelPath = path.resolve(cli.modelFile);
+    const modelPath = absoluteModelPath.replace(/\\/g, '/');
+
+    if (!fs.existsSync(absoluteModelPath) || !fs.statSync(absoluteModelPath).isFile()) {
+        console.error(cli.modelFile, 'is not a file');
+        process.exit(1);
+    }
+
+    const outPath = cli.outFile
+        ? path.resolve(cli.outFile)
+        : (() => {
+            const { dir, name } = path.parse(absoluteModelPath);
+            return path.join(dir, `${name}-doc.json`);
+        })();
+
+    if (cli.deltaFile) cli.deltaFile = path.resolve(cli.deltaFile);
+    if (cli.reason) console.log('[profile] reason:', cli.reason);
+
+    if (!cli.full && (cli.changed.length || cli.deleted.length || cli.deltaFile)) {
+        console.log('[profile] incremental updates not yet supported; performing full rescan.');
+    }
+
+    // Make an Application Resource Locator    // Make an Application Resource Locator
+    const arl = new ARL(modelPath);
+
+    // Create model object
+    const model = new ModelBlueprint(arl);
+
+    // create a model compile object - we do not need a uid generator
+    const compiler = new ModelCompiler(null);
+
+    // get all the factories that are refernced in the model and submodels
+    await compiler.getFactoriesAndModels(model);
+
+    // extract the factories
+    const factories = compiler.factories.map.values();
+
+    // setup the ts-morph project with the factory files
+    const project = setupProject(factories)
+
+    // Extract the source files
+    const sourceFiles = project.getSourceFiles()
+
+    // get all the handlers and transmissions of all the source files into the rxtx array
+    const rxtx = []
+    const generatedAt = new Date().toISOString()
+    for (const sourceFile of sourceFiles) {
+
+        // A file reference is always relative to the model file
+        const filePath = path.relative(path.dirname(modelPath), sourceFile.getFilePath()).replace(/\\/g, '/');
+
+        // the node map to collect the data for the file
+        const nodeMap = new Map();
+
+        // find the handlers in the file
+        findHandlers(sourceFile, filePath, nodeMap)
+
+        // find the transmissions in the file
+        findTransmissions(sourceFile, filePath, nodeMap)
+
+        // map the nodemap to an array 
+        const nodeArray = Array.from(nodeMap.entries()).map(([node, { handles, transmits }]) => ({node,handles,transmits}))
+
+        // add these to the overall rxtx array
+        rxtx.push(...nodeArray)
+    }
+
+    // Assemble the output file path
+    // (outPath was resolved earlier based on CLI arguments)
+
+    // and write the output to that file
+    const output = {
+        version: SRC_DOC_VERSION,
+        generatedAt,
+        entries: rxtx
+    };
+
+    // Persist the structured documentation with its header so downstream tools can validate against the schema.
+    fs.writeFileSync(outPath, JSON.stringify(output, null, 2));
+    console.log(`Documentation written to ${outPath}`);
+}
+
+function parseCliArgs(argv) {
+
+    const result = {
+        modelFile: null,
+        outFile: null,
+        full: false,
+        reason: null,
+        changed: [],
+        deleted: [],
+        deltaFile: null,
+    };
+
+    let i = 0;
+    while (i < argv.length) {
+        const token = argv[i];
+
+        if (token === '--out') {
+            const next = argv[i + 1];
+            if (next && !next.startsWith('--')) {
+                result.outFile = next;
+                i += 2;
+            } else {
+                console.warn('Warning: --out requires a path argument; ignoring.');
+                i += 1;
+            }
+            continue;
+        }
+
+        if (token === '--full') {
+            result.full = true;
+            i += 1;
+            continue;
+        }
+
+        if (token === '--reason') {
+            const next = argv[i + 1];
+            if (next && !next.startsWith('--')) {
+                result.reason = next;
+                i += 2;
+            } else {
+                result.reason = '';
+                i += 1;
+            }
+            continue;
+        }
+
+        if (token === '--delta-file') {
+            const next = argv[i + 1];
+            if (next && !next.startsWith('--')) {
+                result.deltaFile = next;
+                i += 2;
+            } else {
+                console.warn('Warning: --delta-file requires a path argument; ignoring.');
+                i += 1;
+            }
+            continue;
+        }
+
+        if (token === '--changed') {
+            const values = [];
+            i += 1;
+            while (i < argv.length && !argv[i].startsWith('--')) {
+                values.push(argv[i]);
+                i += 1;
+            }
+            if (values.length === 0) {
+                console.warn('Warning: --changed provided without any paths.');
+            } else {
+                result.changed.push(...values);
+            }
+            continue;
+        }
+
+        if (token === '--deleted') {
+            const values = [];
+            i += 1;
+            while (i < argv.length && !argv[i].startsWith('--')) {
+                values.push(argv[i]);
+                i += 1;
+            }
+            if (values.length === 0) {
+                console.warn('Warning: --deleted provided without any paths.');
+            } else {
+                result.deleted.push(...values);
+            }
+            continue;
+        }
+
+        if (typeof token === 'string' && token.startsWith('--')) {
+            console.warn('Warning: unknown option "' + token + '" ignored.');
+            i += 1;
+            continue;
+        }
+
+        if (!result.modelFile) {
+            result.modelFile = token;
+        } else {
+            console.warn('Warning: extra positional argument "' + token + '" ignored.');
+        }
+
+        i += 1;
+    }
+
+    return result;
+}
+
+
+
+// Gets all the source files that are part of this project
+function setupProject(factories) {
+
+    // Initialize ts-morph without tsconfig
+    const project = new Project({
+        compilerOptions: {
+            allowJs: true,
+            checkJs: true,
+            module: ts.ModuleKind.ESNext,
+            target: ts.ScriptTarget.ESNext,
+            moduleResolution: ts.ModuleResolutionKind.NodeJs,
+            esModuleInterop: true,
+            noEmit: true,
+        },
+        skipAddingFilesFromTsConfig: true,
+    });
+
+    // Add factory entry files
+    for (const factory of factories) {
+
+        // get the file path
+        const filePath = factory.arl.url;
+
+        // user feedback
+        console.log('Adding factory entry:', filePath);
+
+        // add to the project
+        try {
+            project.addSourceFileAtPath(factory.arl.url);
+        } catch (err) {
+            console.warn(`Could not load ${filePath}: ${err.message}`);
+        }
+    }
+
+    // Resolve all imports recursively
+    project.resolveSourceFileDependencies();
+
+    // done
+    return project
+}
+
+
+const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isDirectRun) {
+  profile().catch(err => {
+    console.error('Failed to generate source documentation:', err);
+    process.exit(1);
+  });
+}

package/commands/profile/rollup.config.js

@@ -0,0 +1,22 @@
+import resolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import json from '@rollup/plugin-json';
+
+export default {
+  input: './profile.js',
+  output: {
+    file: './profile.cjs', // ⬅️ Use .cjs extension and CommonJS format
+    format: 'cjs',
+    sourcemap: true
+  },
+  external: [
+    'ts-morph',
+    'typescript', // Exclude heavy dependencies from bundle
+  ],
+  plugins: [
+    commonjs(),
+    resolve({ preferBuiltins: true }),
+    json()
+  ]
+};
+

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "@vizualmodel/vmblu-cli",
-  "version": "0.1.0",
-  "type": "commonjs",
-  "bin": { "vmblu": "bin/vmblu.js" },
-  "files": ["bin", "commands", "templates", "README.md", "LICENSE"],
-  "engines": { "node": ">=18" }
+  "version": "0.2.0",
+  "type": "module",
+  "bin": {
+    "vmblu": "bin/vmblu.js"
+  },
+  "files": [
+    "bin",
+    "commands",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
 }