@vizualmodel/vmblu-cli 0.1.0 → 0.3.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));
@@ -73,14 +73,9 @@ function defaultModel(projectName) {
 function defaultDoc(projectName) {
   const now = new Date().toISOString();
   return JSON.stringify({
-    project: projectName,
-    generator: "vmblu-docgen",
-    generatorVersion: "0.0.0",
-    created: now,
-    files: [],
-    nodes: [],
-    pins: [],
-    handlers: []
+    version: "0.0.0",
+    generatedAt: now,
+    entries: {}
   }, null, 2);
 }
 
@@ -104,10 +99,10 @@ function fallbackSchema() {
 }`;
 }
 
-function fallbackSrcdocSchema() {
+function fallbackProfileSchema() {
   return `{
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "srcdoc.schema (placeholder)",
+  "title": "profile.schema (placeholder)",
   "type": "object",
   "description": "Placeholder schema. Replace with official version."
 }`;
@@ -119,16 +114,16 @@ function fallbackSeed() {
 vmblu (Vizual Model Blueprint) is a graphical editor that maintains a visual, runnable model of a software system.
 vmblu models software as interconnected nodes that pass messages via pins.  
 The model has a well defined format described by a schema. An additional annex gives semantic background information about the schema.
-The parameter profiles of messages and where in the actual source code messages are received and sent, is stored in a second file, the srcdoc file.
-The srcdoc file is generated automatically by vmblu and is only to be consulted, not written.
+The parameter profiles of messages and where in the actual source code messages are received and sent, is stored in a second file, the profile file.
+The profile file is generated automatically by vmblu and is only to be consulted, not written.
 
 You are an expert **architecture + code copilot** for **vmblu** .
-You can find the location of the model file, the model schema, the model annex, the srcdoc file and the srcdoc schema in the 'manifest.json' file of this project.
+You can find the location of the model file, the model schema, the model annex, the profile file and the profile schema in the 'manifest.json' file of this project.
 The location of all other files in the project can be found via the model file.
 
 Your job is to co-design the architecture and the software for the system.
 For modifications of the model, always follow the schema. 
-If the srcdoc does not contain profile information it could be that the code for a message has not been written yet, this should not stop you from continuing
+If the profile does not contain profile information it could be that the code for a message has not been written yet, this should not stop you from continuing
 `}
 
 /**
@@ -178,7 +173,7 @@ async function initProject(opts) {
   // Template sources
   const schemaSrc = path.join(templatesDir, schemaVersion, 'vmblu.schema.json');
   const annexSrc  = path.join(templatesDir, schemaVersion, 'vmblu.annex.md');
-  const srcdocSchemaSrc = path.join(templatesDir, schemaVersion, 'srcdoc.schema.json');
+  const profileSchemaSrc = path.join(templatesDir, schemaVersion, 'profile.schema.json');
   const seedSrc = path.join(templatesDir, schemaVersion, 'seed.md');
   
   // 1) Create folders
@@ -197,7 +192,7 @@ async function initProject(opts) {
   // 3) Copy schema + annex into llm/
   const schemaDst = path.join(llmDir, 'vmblu.schema.json');
   const annexDst  = path.join(llmDir, 'vmblu.annex.md');
-  const srcdocSchemaDst = path.join(llmDir, 'srcdoc.schema.json');
+  const profileSchemaDst = path.join(llmDir, 'profile.schema.json');
   const seedDst  = path.join(llmDir, 'seed.md');
 
 
@@ -207,8 +202,8 @@ async function initProject(opts) {
   ui.info(`copy ${annexSrc} -> ${annexDst}${force ? ' (force)' : ''}`);
   await copyOrWriteFallback(annexSrc, annexDst, fallbackAnnex(), { force, dry: dryRun });
 
-   ui.info(`copy ${srcdocSchemaSrc} -> ${srcdocSchemaDst}${force ? ' (force)' : ''}`);
-  await copyOrWriteFallback(srcdocSchemaSrc, srcdocSchemaDst, fallbackSrcdocSchema(), { force, dry: dryRun });
+   ui.info(`copy ${profileSchemaSrc} -> ${profileSchemaDst}${force ? ' (force)' : ''}`);
+  await copyOrWriteFallback(profileSchemaSrc, profileSchemaDst, fallbackProfileSchema(), { force, dry: dryRun });
 
   ui.info(`copy ${seedSrc} -> ${seedDst}${force ? ' (force)' : ''}`);
   await copyOrWriteFallback(seedSrc, seedDst, fallbackSeed(), { force, dry: dryRun });
@@ -235,9 +230,9 @@ async function initProject(opts) {
         schema: 'vmblu.schema.json',
         annex: 'vmblu.annex.md',
       },
-      srcdoc: { 
+      profile: { 
         path: rel(llmPosix, docFile), 
-        schema: 'srcdoc.schema.json',
+        schema: 'profile.schema.json',
       },
     };
 
@@ -251,7 +246,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` +
@@ -264,7 +259,7 @@ async function initProject(opts) {
       manifest.json
       vmblu.schema.json
       vmblu.annex.md
-      srcdoc.schema.json
+      profile.schema.json
       session/
     nodes/\n`);
 
@@ -277,7 +272,7 @@ async function initProject(opts) {
       doc: docFile,
       schema: schemaDst,
       annex: annexDst,
-      srdocSchema: srcdocSchemaDst,
+      profileSchema: profileSchemaDst,
       manifest: path.join(llmDir, 'manifest.json')
     },
     dryRun,
@@ -285,4 +280,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,271 @@
+#!/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: 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,21 @@
 {
   "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.3.0",
+  "type": "module",
+  "bin": {
+    "vmblu": "bin/vmblu.js"
+  },
+  "files": [
+    "bin",
+    "commands",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "vmblu": "vmblu"
+  }
 }

package/templates/0.8.2/{srcdoc.schema.json → profile.schema.json}

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://vmblu.dev/schema/srcdoc/0.2/srcdoc.schema.json",
+  "$id": "https://vmblu.dev/schema/profile/0.2/profile.schema.json",
   "title": "vmblu Source Documentation (grouped by node)",
   "type": "object",
   "required": ["version", "generatedAt", "entries"],

package/templates/0.8.2/seed.md

@@ -4,14 +4,14 @@ vmblu (Vizual Model Blueprint) is a graphical editor that maintains a visual, ru
 vmblu models software as interconnected nodes that pass messages via pins.
 
 The model has a well defined format described by a schema. An additional annex gives semantic background information about the schema.
-The parameter profiles of messages and where messages are received and sent in the actual source code, are stored in a second file, the srcdoc file.
-The srcdoc file is generated automatically by vmblu and is only to be consulted, not written, at the start of a project it does not yet exist
+The parameter profiles of messages and where messages are received and sent in the actual source code, are stored in a second file, the profile file.
+The profile file is generated automatically by vmblu and is only to be consulted, not written, at the start of a project it does not yet exist
 
 You are an expert **architecture + code copilot** for **vmblu** .
-You can find the location of the model file, the model schema, the model annex, the srcdoc file and the srcdoc schema in the 'manifest.json' file of this project. Read these files.
+You can find the location of the model file, the model schema, the model annex, the profile file and the profile schema in the 'manifest.json' file of this project. Read these files.
 
 The location of all other files in the project can be found via the model file.
 
 Your job is to co-design the architecture and the software for the system.
 For modifications of the model, always follow the schema. 
-If the srcdoc does not exist yet or does notcontain profile information it could be that the code for the node has not been written yet, this should not stop you from continuing.
+If the profile does not exist yet or does notcontain profile information it could be that the code for the node has not been written yet, this should not stop you from continuing.