@vizualmodel/vmblu-cli 0.1.0

package/LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Sam Verstraete, vizualmodel organization
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,59 @@
+# CLI for vmblu
+This folder contains the CLI commands that are available for vmblu. Currently there is only the 'init' and 'help' command, but others will follow.
+
+
+## Folder layout
+
+```txt
+vmblu/
+  cli/                      # your CLI source
+    commands/
+      init/
+      migrate/
+    templates/
+      0.8.2/
+        vmblu.schema.json
+        vmblu.annex.md
+        seed.md
+        srcdoc.schema.json
+    bin/
+      vmblu.js             # the executable (router)
+    package.json
+    README.md
+```
+
+## Add more commands
+
+Create commands/migrate/index.js with the same export shape { command, describe, builder, handler }. The router auto-discovers it, so users can run vmblu migrate ….
+
+## Dev/test workflow
+
+### from vmblu/cli
+
+```bash
+npm link               # exposes "vmblu" globally
+vmblu init my-app --schema 0.8.2
+vmblu --help
+vmblu init --help
+```
+### Publish & use
+```bash
+npm publish --access public
+```
+## Usage
+
+```bash
+npx @vizualmodel/vmblu-cli init my-app --schema 0.8.2
+```
+
+**or, after global install:**
+
+```bash
+vmblu init my-app
+```
+## Tips
+
+* Keep templates inside the package and list them in "files" so npx works offline.
+* If you later prefer a richer UX, you can swap the router to commander/yargs without changing your command folders.
+* If your main repo houses both runtime and CLI, publish the CLI from vmblu/cli (separate package.json). This keeps runtime installs lean.
+* This gives you one tidy package for all current and future commands, with zero drift and easy discoverability.

package/bin/vmblu.js

@@ -0,0 +1,47 @@
+#!/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);
+});

package/commands/init/index.js

@@ -0,0 +1,45 @@
+// vmblu init [targetDir] --name <project> --schema <ver> --force --dry-run
+const path = require('path');
+const { initProject } = require('./init-project');
+
+exports.command = 'init';
+exports.describe = 'Scaffold an empty vmblu project';
+exports.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) => {
+  // tiny arg parse (no deps)
+  const args = { _: [] };
+  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;
+    else if (a === '--name') args.name = argv[++i];
+    else if (a === '--schema') args.schema = argv[++i];
+    else if (!a.startsWith('-')) args._.push(a);
+  }
+
+  const targetDir = path.resolve(args._[0] || '.');
+  const projectName = args.name || path.basename(targetDir);
+  const schemaVersion = args.schema || '0.8.2';
+
+  await initProject({
+    targetDir,
+    projectName,
+    schemaVersion,
+    force: !!args.force,
+    dryRun: !!args.dryRun,
+    templatesDir: path.join(__dirname, '..', '..', 'templates'),
+    ui: {
+      info: (m) => console.log(m),
+      warn: (m) => console.warn(m),
+      error: (m) => console.error(m)
+    }
+  });
+
+  console.log(`✔ vmblu project scaffolded in ${targetDir}`);
+};

package/commands/init/init-project.js

@@ -0,0 +1,288 @@
+// 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');
+
+function rel(from, to) {
+  return path.posix.join(...path.relative(from, to).split(path.sep));
+}
+
+async function exists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+async function ensureDir(dir, dry) {
+  if (dry) return;
+  await fs.mkdir(dir, { recursive: true });
+}
+
+async function writeFileSafe(file, contents, { force = false, dry = false } = {}) {
+  const already = await exists(file);
+  if (already && !force) return false;
+  if (dry) return true;
+  await fs.writeFile(file, contents);
+  return true;
+}
+
+async function copyOrWriteFallback(src, dst, fallback, { force = false, dry = false } = {}) {
+  const already = await exists(dst);
+  if (already && !force) return false;
+
+  if (dry) return true;
+
+  if (src && fssync.existsSync(src)) {
+    await fs.copyFile(src, dst);
+  } else {
+    await fs.writeFile(dst, fallback);
+  }
+  return true;
+}
+
+// async function sha256(file) {
+//   const buf = await fs.readFile(file);
+//   return crypto.createHash('sha256').update(buf).digest('hex');
+// }
+
+function defaultModel(projectName) {
+  const now = new Date().toISOString();
+  return JSON.stringify({
+    header: {
+      version: "0.8.2",
+      created: now,
+      saved: now,
+      utc: now,
+      style: "#2c7be5",
+      runtime: "@vizualmodel/vmblu/runtime",
+      description: `${projectName} — vmblu model (scaffolded)`
+    },
+    models: [],
+    factories: [],
+    root: {
+      group: "Root",
+      pins: [],
+      nodes: [],
+      routes: [],
+      prompt: "Root group for the application."
+    }
+  }, null, 2);
+}
+
+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: []
+  }, null, 2);
+}
+
+function fallbackAnnex() {
+  return `# vmblu Annex (placeholder)
+This is a minimal scaffold. Replace with the official annex matching your pinned schema version.
+
+- Nodes: Source, Group, Dock
+- Pins: input/output/channel, 'profile' describes payloads
+- Routes: "output@NodeA" -> "input@NodeB" (or via group pads)
+- Keep names normalized; avoid ambiguous magic.
+`;
+}
+
+function fallbackSchema() {
+  return `{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vmblu.schema (placeholder)",
+  "type": "object",
+  "description": "Placeholder schema. Replace with official version."
+}`;
+}
+
+function fallbackSrcdocSchema() {
+  return `{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "srcdoc.schema (placeholder)",
+  "type": "object",
+  "description": "Placeholder schema. Replace with official version."
+}`;
+}
+
+function fallbackSeed() {
+  return `# Session Seed (System Prompt)
+
+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.
+
+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.
+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
+`}
+
+/**
+ * Initialize a vmblu project directory.
+ *
+ * @param {Object} opts
+ * @param {string} opts.targetDir           Absolute path to project dir (created if missing)
+ * @param {string} [opts.projectName]       Defaults to basename(targetDir)
+ * @param {string} [opts.schemaVersion]     e.g. "0.8.2"
+ * @param {boolean}[opts.force]             Overwrite existing files
+ * @param {boolean}[opts.dryRun]            Print actions, do not write
+ * @param {string} [opts.templatesDir]      Root where templates live (defaults to package templates)
+ *                                          expects:
+ *                                            templates/schemas/<ver>/vmblu.schema.json
+ *                                            templates/annex/<ver>/vmblu.annex.md
+ * @param {Object} [opts.ui]                { info, warn, error } callbacks (optional)
+ */
+async function initProject(opts) {
+  const {
+    targetDir,
+    projectName = path.basename(opts.targetDir),
+    schemaVersion = "0.8.2",
+    force = false,
+    dryRun = false,
+    templatesDir = path.join(__dirname, '..', 'templates'),
+    ui = {
+      info: console.log,
+      warn: console.warn,
+      error: console.error
+    }
+  } = opts || {};
+
+  if (!targetDir) throw new Error("initProject: targetDir is required");
+
+  const absTarget = path.resolve(targetDir);
+  const modelFile = path.join(absTarget, `${projectName}.vmblu`);
+  const docFile   = path.join(absTarget, `${projectName}-doc.json`);
+
+  const llmDir     = path.join(absTarget, 'llm');
+  const sessionDir = path.join(llmDir, 'session');
+  const nodesDir   = path.join(absTarget, 'nodes');
+
+  // Template sources
+  // const schemaSrc = path.join(templatesDir, 'schemas', schemaVersion, 'vmblu.schema.json');
+  // const annexSrc  = path.join(templatesDir, 'annex',   schemaVersion, 'vmblu.annex.md');
+
+  // 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 seedSrc = path.join(templatesDir, schemaVersion, 'seed.md');
+  
+  // 1) Create folders
+  for (const dir of [absTarget, llmDir, sessionDir, nodesDir]) {
+    ui.info(`mkdir -p ${dir}`);
+    await ensureDir(dir, dryRun);
+  }
+
+  // 2) Create root files
+  ui.info(`create ${modelFile}${force ? ' (force)' : ''}`);
+  await writeFileSafe(modelFile, defaultModel(projectName), { force, dry: dryRun });
+
+  ui.info(`create ${docFile}${force ? ' (force)' : ''}`);
+  await writeFileSafe(docFile, defaultDoc(projectName), { force, dry: dryRun });
+
+  // 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 seedDst  = path.join(llmDir, 'seed.md');
+
+
+  ui.info(`copy ${schemaSrc} -> ${schemaDst}${force ? ' (force)' : ''}`);
+  await copyOrWriteFallback(schemaSrc, schemaDst, fallbackSchema(), { force, dry: dryRun });
+
+  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 ${seedSrc} -> ${seedDst}${force ? ' (force)' : ''}`);
+  await copyOrWriteFallback(seedSrc, seedDst, fallbackSeed(), { force, dry: dryRun });
+
+  // 4) Build manifest with hashes
+  const willWriteManifest = !(await exists(path.join(llmDir, 'manifest.json'))) || force;
+  let manifest = null;
+
+  if (dryRun) {
+    ui.info(`would write manifest.json in ${llmDir}`);
+  } else {
+
+    // I don't need the hashes
+    // const [schemaHash, annexHash, modelHash, docHash] = await Promise.all([
+    //   sha256(schemaDst), sha256(annexDst), sha256(modelFile), sha256(docFile)
+    // ]);
+
+    // Paths in manifest should be relative to /llm to keep it portable
+    const llmPosix = llmDir; // absolute
+    manifest = {
+      version: schemaVersion,
+      model:  { 
+        path: rel(llmPosix, modelFile),
+        schema: 'vmblu.schema.json',
+        annex: 'vmblu.annex.md',
+      },
+      srcdoc: { 
+        path: rel(llmPosix, docFile), 
+        schema: 'srcdoc.schema.json',
+      },
+    };
+
+    if (willWriteManifest) {
+      const manifestPath = path.join(llmDir, 'manifest.json');
+      ui.info(`create ${manifestPath}${force ? ' (force)' : ''}`);
+      await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+    } else {
+      ui.warn(`manifest.json exists and --force not set. Skipped.`);
+    }
+  }
+
+  // 5) Make the package file
+  pckg.makePackageJson(  {absTarget, projectName, force, dryRun, addCliDep: true, cliVersion: "^0.1.0"}, ui);
+
+  // 6) Final tree hint
+  ui.info(`\nScaffold complete${dryRun ? ' (dry run)' : ''}:\n` +
+`  ${absTarget}/
+    ${path.basename(modelFile)}
+    ${path.basename(docFile)}
+    package.json
+    llm/
+      seed.md
+      manifest.json
+      vmblu.schema.json
+      vmblu.annex.md
+      srcdoc.schema.json
+      session/
+    nodes/\n`);
+
+  return {
+    targetDir: absTarget,
+    projectName,
+    schemaVersion,
+    files: {
+      model: modelFile,
+      doc: docFile,
+      schema: schemaDst,
+      annex: annexDst,
+      srdocSchema: srcdocSchemaDst,
+      manifest: path.join(llmDir, 'manifest.json')
+    },
+    dryRun,
+    manifest
+  };
+}
+
+module.exports = { initProject };

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

@@ -0,0 +1,59 @@
+const fs = require('fs/promises');
+const path = require('path');
+
+async function readJsonIfExists(file) {
+  try { return JSON.parse(await fs.readFile(file, 'utf8')); } catch { return null; }
+}
+
+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) {
+  const pkgPath = path.join(absTarget, 'package.json');
+  const existing = await readJsonIfExists(pkgPath);
+
+  // Base skeleton (created if missing)
+  const basePkg = existing || {
+    name: projectName,
+    private: true,
+    version: "0.0.0",
+  };
+
+  // Add/merge scripts (idempotent)
+  basePkg.scripts = Object.assign({}, basePkg.scripts, {
+    "vm:init": "vmblu init ."
+  });
+
+  // Optionally add the CLI as a devDependency
+  if (addCliDep) {
+    basePkg.devDependencies = Object.assign({}, basePkg.devDependencies, {
+      "@vizualmodel/vmblu-cli": basePkg.devDependencies?.["@vizualmodel/vmblu-cli"] || cliVersion
+    });
+  }
+
+  // Nice-to-have: keep deterministic key order
+  const ordered = {
+    ...sortKeys(basePkg),
+    scripts: sortKeys(basePkg.scripts || {}),
+    devDependencies: basePkg.devDependencies ? sortKeys(basePkg.devDependencies) : undefined
+  };
+
+  if (existing && !force) {
+    ui.info(`update package.json (merge scripts${addCliDep ? " + devDependency" : ""})`);
+  } else if (!existing) {
+    ui.info(`create ${pkgPath}`);
+  } else {
+    ui.info(`overwrite ${pkgPath} (force)`);
+  }
+
+  if (!dryRun) {
+    await fs.writeFile(pkgPath, JSON.stringify(ordered, null, 2) + '\n', 'utf8');
+  }
+
+  return pkgPath;
+}
+module.exports = { makePackageJson };

package/package.json

@@ -0,0 +1,8 @@
+{
+  "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" }
+}

package/templates/0.8.2/seed.md

@@ -0,0 +1,17 @@
+# Session Seed (System Prompt)
+
+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 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
+
+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.
+
+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.

package/templates/0.8.2/srcdoc.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://vmblu.dev/schema/srcdoc/0.2/srcdoc.schema.json",
+  "title": "vmblu Source Documentation (grouped by node)",
+  "type": "object",
+  "required": ["version", "generatedAt", "entries"],
+  "properties": {
+    "version": { "type": "string" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Entry" }
+    }
+  },
+  "$defs": {
+    "Param": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "type", "description"],
+      "properties": {
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "description": { "type": "string" }
+      }
+    },
+    "Handle": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pin", "handler", "file", "line", "summary", "returns", "examples", "params"],
+      "properties": {
+        "pin": { "type": "string" },
+        "handler": { "type": "string" },
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "summary": { "type": "string" },
+        "returns": { "type": "string" },
+        "examples": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "params": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Param" }
+        }
+      }
+    },
+    "Transmit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pin", "file", "line"],
+      "properties": {
+        "pin": { "type": "string" },
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "Entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["node", "handles", "transmits"],
+      "properties": {
+        "node": { "type": "string" },
+        "handles": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Handle" }
+        },
+        "transmits": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Transmit" }
+        }
+      }
+    }
+  }
+}

package/templates/0.8.2/vmblu.annex.md

@@ -0,0 +1,93 @@
+# Annex A: Semantic Clarifications for vmblu v0.8
+
+This annex captures subtle semantic points that are not fully enforceable in the JSON Schema but are critical for correct usage of the vmblu format by both humans and LLMs.
+
+---
+
+## A.1 Request / Reply Semantics
+
+- A **request pin** is an **output pin**.  
+  - It is used by the requester node to initiate a request with `tx.request('pinName', payload)`.  
+  - This function returns a **Promise** which resolves when the callee replies.
+
+- A **reply pin** is an **input pin** on the callee.  
+  - It receives the request payload and has a handler like any input pin.  
+  - Inside this handler, the callee must call `tx.reply(payload)` to respond to the requester.  
+  - The runtime delivers this reply on the backchannel and resolves the requester’s Promise.
+
+- **Connections**:  
+  - Normally, `request` pins connect to `reply` pins.  
+  - It is also valid to connect a `request` pin to an `input` pin (e.g. for logging or monitoring), but in that case no reply is sent.
+
+---
+
+## A.2 Handler Naming
+
+Every **input** or **reply** pin corresponds to a message handler in the node implementation.  
+
+- Handler name is `on<PinNameInCamelCase>`.  
+- Example:  
+  - Pin: `"name": "saveMessage", "kind": "input"`  
+  - Handler: `onSaveMessage(payload)`  
+
+This uniform convention ensures LLMs and the editor can always map pins to their corresponding handler.
+
+---
+
+## A.3 Factory Function Signature
+
+A source node references its implementation via a **factory** object (`path` + `function`).  
+The factory function is called by the runtime to create the node instance.
+
+In order to let documentation tools find the factory function add a *node* JSdoc tag before the function.
+
+- Signature:  
+  ```js
+  /**
+   * @node node name
+   */
+  export function createMyNode( tx, sx ) { ... }
+  ```
+
+- tx: object exposing runtime message functions (send, request, reply).
+- sx: arbitrary initialization data supplied by the model.
+- rx: not passed to the node. Runtime-only directives; used by the runtime to decide how/where to host the node (e.g. worker thread, debug flags).
+
+## A.4 Dock Nodes and Drift
+
+- A dock node references another node defined in a different file via a link.
+- Pins and connections of the dock node are kept in the importing file.
+- If the external node definition changes, the editor highlights differences (“drift”) between the dock node and its linked definition.
+
+## A.5 Buses and Pads
+
+A bus simplifies routing:
+
+- Outputs connected to a bus are forwarded to inputs of the same name.
+- Buses do not introduce new message names; they only group routes.
+
+Pads are how group nodes expose their internal pins externally.
+- If a connection omits the node in its address, it refers to a pad on the group itself.
+
+## A.6 Connections
+
+A connection is between pins or interfaces.
+
+For a connection between pins, the message flow is from 'src' to 'dst'. So 'src is either an ouput pin of a node or an input pin of the containing group node (a pad in the editor) and 'dst' is either an input pin of a node or an ouput pin of the containing group node.
+
+When connecting interfaces the *ouput pins* of the interface are connected the *input pins* with the same name, of the interface on the other node, and in the same way the *input pins* of the interface are connected to the *output pins* with the same name of the interface connected to on the other node. Not all pins have to be present in both interfaces.
+
+## A.7 AI Generation Guidelines
+
+For LLMs working with vmblu files:
+
+- Respect node and pin names — do not rename unless explicitly asked.
+- Connection rules — only connect compatible pins:
+
+    - output → input
+    - request → reply
+
+- Reply requirement — every new request pin should be connected to at least one reply pin.
+- Do not edit editor fields — they are for the graphical editor only.
+
+When generating source code for the nodes in the vmblu file, only generate code for the nodes, the *main* function and node setup is generated directly from the vmblu file itself.

package/templates/0.8.2/vmblu.schema.json

@@ -0,0 +1,268 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "@vizual_model/cli/templates/0.8.2/vmblu.schema.json",
+    "title": "vmblu Model (v0.8.2 draft)",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["header", "root"],
+    "properties": {
+        "header": { "$ref": "#/$defs/Header" },
+        "imports": {
+            "description": "List of vmblu files that are referenced in the model. Allows for faster loading.",
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "uniqueItems": true
+        },
+        "factories": {
+            "description": "List of files where the source code of the source nodes can be found. Used by the docgen tool.",
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "uniqueItems": true
+        },
+        "libraries": {
+            "description": "List of vmblu files from which the editor allows the user to select nodes in an easy way.",
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "uniqueItems": true
+        },
+        "root": { 
+            "description": "The starting point of the vmblu model. Every field named 'editor' is there only to let the editor display the model for the user.",
+            "$ref": "#/$defs/Node" 
+        }
+    },
+    "$defs": {
+        "Header": {
+            "description": "Contains meta information about the model. Used by the editor.",
+            "type": "object",
+            "properties": {
+                "version": { "type": "string" },
+                "created": { "type": "string", "format": "date-time"  },
+                "saved": { "type": "string", "format": "date-time"  },
+                "utc": { "type": "string", "format": "date-time" },
+                "style": { "type": "string" },
+                "runtime": { "type": "string" }
+            },
+            "additionalProperties": false,
+            "required": ["version", "created", "saved", "utc"]
+        },
+        "Node" : {
+            "description": "A node describes a component of a software system. Nodes communicate via messages. There are three types of nodes.",
+            "type": "object",
+            "properties": {
+                "kind": {"enum": ["source", "group", "dock"]},
+                "name": { "type": "string", "minLength": 1, "pattern": "^[^@]+$" },
+                "label": { "type": "string"},
+                "interfaces":{
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/Interface" }
+                },
+                "prompt": {"type": "string"},
+                "sx": { "$ref": "#/$defs/NodeInitialization" },
+                "rx": { "$ref": "#/$defs/RuntimeDirectives" }
+            },
+            "oneOf": [
+                { "$ref": "#/$defs/SourceNode" },
+                { "$ref": "#/$defs/GroupNode" },
+                { "$ref": "#/$defs/DockNode" }
+            ],
+            "required": ["kind", "name"],
+            "unevaluatedProperties": false
+        },
+        "SourceNode": {
+            "description": "A source node has an implementation in source code.",
+            "type": "object",
+            "properties": {
+                "kind": {"const": "source"},
+                "factory": {
+                    "type": "object",
+                    "properties": {
+                        "path": { "type": "string", "minLength": 1 },
+                        "function": { "type": "string", "minLength": 1 }
+                    },
+                    "required": ["name"]
+                },
+                "editor": { "$ref": "#/$defs/EditorNode" }
+            }
+        },
+        "GroupNode": {
+            "description": "A group node consists of other connected nodes. It allows to build modular models.",
+            "type": "object",
+            "properties": {
+                "kind": {"const": "group"},
+                "nodes": { 
+                    "type": "array", 
+                    "items": { "$ref": "#/$defs/Node" } 
+                },
+                "connections": { 
+                    "type": "array", 
+                    "items": { "$ref": "#/$defs/Connection" } 
+                },
+                "editor": { "$ref": "#/$defs/EditorGroupNode" }
+            }
+        },
+        "DockNode": {
+            "description": "A dock node is a placeholder for a node that is defined in another file, specified in the link field.",
+            "type": "object",
+            "properties": {
+                "kind": {"const": "dock"},
+                "link": {
+                    "type": "object",
+                    "required": ["name"],
+                    "properties": {
+                        "path": { "type": "string", "minLength": 1 },
+                        "node": { "type": "string", "minLength": 1, "pattern": "^[^@]+$" }
+                    }
+                },
+                "editor": { "$ref": "#/$defs/EditorNode" }
+            }
+        },
+        "Interface": {
+            "description": "An interface groups a number of pins of a node.",
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+                "name": { "type": "string", "pattern": "^[^@]+$" },
+                "pins": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/Pin" }
+                },
+                "editor" : {
+                    "type": "object",
+                    "required": ["id"],
+                    "properties": {
+                        "id": {"type": "integer"}
+                    }
+                }
+            }
+        },
+        "Pin": {
+            "description": "A node can receive or send a message via a pin. Inputs connect to outputs and requests connect to replies.",
+            "type": "object",
+            "required": ["name", "kind"],
+            "properties": {
+                "name": { "type": "string", "minLength": 1, "pattern": "^[^@]+$"},
+                "kind": { "enum": ["input", "output", "request", "reply"] },
+                "editor": {"$ref": "#/$defs/EditorPin"}
+            }
+        },
+        "Connection": {
+            "description": "A connection can be made between two pins or between two interfaces. For pins the message flow is from 'src' to 'dst', so 'src' is either an output pin of a node or an input pin of the containing group node and 'dst' is either an input pin of a node or an output pin of the containing group node.",
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["from", "to"],
+            "properties": {
+                "src":   { "$ref": "#/$defs/Address" },
+                "dst":     { "$ref": "#/$defs/Address" }
+            }
+        },
+        "Address": {
+            "description": "The format for the address of a pin or interface. If node is omitted the node is the containing group node, and the pin or interface are represented as pads.",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "node":      { "type": "string", "minLength": 1, "pattern": "^[^@]+$" },
+                "pin":       { "type": "string", "minLength": 1, "pattern": "^[^@]+$" },
+                "interface": { "type": "string", "minLength": 1, "pattern": "^[^@]+$" }
+            },
+            "oneOf": [
+                { "required": ["pin"] },
+                { "required": ["interface"] }
+            ]
+        },
+        "NodeInitialization": {
+            "description": "Node-defined initialization data passed to the node at creation time. Shape is entirely up to the node designer.",
+            "type": "object"
+        },
+        "RuntimeDirectives": {
+            "description": "Runtime-defined creation/hosting directives. Shape is determined by the runtime (e.g., host=worker, debug=true).",
+            "type": "object",
+            "properties": {
+            "$contract": {
+                "type": "string",
+                "description": "Optional contract/version tag or URI (e.g., 'vmblu.rx/v1'). Lets tools know which directive dialect to expect."
+            }
+            },
+            "examples": [
+                { "$contract": "vmblu.rx/v1", "host": "worker", "debug": true, "logLevel": "info" }
+            ]
+        },
+        "EditorNode": {
+            "description": "Allows the editor to position and draw the node.",
+            "type": "object",
+            "properties": {
+                "rect": { "type": "string" }
+            }
+        },
+        "EditorGroupNode": {
+            "description": "Allows the editor to position and draw the content of a group node in a dedicated view.",
+            "type": "object",
+            "properties": {
+                "rect": { "type": "string" },
+                "view": {
+                    "type": "object",
+                    "required": ["rect"],
+                    "properties": {
+                        "state": {"enum": ["open", "closed"]},
+                        "rect": { "type": "string" },
+                        "transform": { "type": "string" }
+                    }
+                },
+                "buses": {
+                    "type": "array",
+                    "items": {"$ref": "#/$defs/EditorBus"}
+                },
+                "routes": {
+                    "type": "array",
+                    "items": {"$ref": "#/$defs/EditorRoute"}
+                }
+            }
+        },
+        "EditorPin" : {
+            "description": "Allows the editor to draw the pin in the node it belongs to.",
+            "type": "object",
+            "properties": {
+                "id": { "type": "integer" },
+                "align": { "enum": ["left", "right"]},
+                "pad": {
+                    "type": "object",
+                    "required": ["rect"],
+                    "properties": {
+                        "rect": { "type": "string" },
+                        "align": { "enum": ["left", "right"]}
+                    }
+                }
+            }
+        },
+        "EditorBus": {
+            "description": "A bus is an easy way to route multiple connections between nodes. A bus can also do some routing via a filter.",
+            "type": "object",
+            "required": ["kind","name"],
+            "properties": {
+                "kind": { "enum": ["busbar", "cable"]},
+                "name": { "type": "string", "minLength": 1, "pattern": "^[^@]+$" },
+                "filter": { "$ref": "#/$defs/Filter" },
+                "start" : { "type": "string"},
+                "wire": { "type": "string" }
+            }
+        },
+        "Filter": {
+            "description": "A bus uses a filter to route messages based on message parameters. A filter is a software routine.",
+            "type": "object",
+            "required": ["path", "function"],
+            "properties": {
+                "path": { "type": "string", "minLength": 1 },
+                "function": { "type": "string", "minLength": 1 }
+            }
+        },
+        "EditorRoute": {
+            "description": "A route is how the editor shows the connections between pins or interfaces.The from-string and to-string start with either pin, bus, pad or itf",
+            "type": "object",
+            "properties": {
+                "from":{ "type": "string" },
+                "to":{ "type": "string" },
+                "wire": { "type": "string" }
+            }
+        }
+    }
+}
+