@fnet/cli 0.133.0 → 1.0.0

package/readme.md

@@ -16,12 +16,18 @@
 
 ## Overview
 
-Flownet is a revolutionary development framework that isolates non-functional components, allowing developers to focus solely on functional code. The `@fnet/cli` package provides command-line tools to create, build, and manage Flownet projects.
+Flownet is a low-level flow framework that separates **Core** (your business logic) from **Layers** (infrastructure, dev, build, runtime, and delivery). This separation allows developers to focus on functional code while Flownet automates the surrounding infrastructure. The `@fnet/cli` package provides command-line tools to create, build, and manage Flownet projects.
+
+Flownet provides primitives for composing workflows similar to how React provides components for UI development. It emphasizes a **schema-first approach** with **deterministic core**, enabling **multi-runtime portability**.
 
 ### Key Features
 
+- **Core vs Layers Architecture**: Separate your business logic (Core) from infrastructure (Layers) for cleaner, more maintainable code
+- **Nodes & Flows**: Reusable functional units (Nodes) with explicit I/O schemas, orchestrated by Flows
+- **I/O Contracts**: Schema-first contracts define clear input/output expectations for deterministic behavior
+- **Automatic Dependency Detection**: Simplified dependency management across your project
+- **Multi-Runtime Support**: Deploy to Node.js, Bun, Deno, or Python - choose the best runtime for each task
 - **Language Agnostic**: Support for multiple programming languages (JavaScript, Python) in the same project
-- **Runtime Flexibility**: Choose the best runtime for each task (Node.js, Python, Bun)
 - **Unified Interface**: Consistent commands across different project types
 - **Tag-Based Configuration**: Powerful conditional configuration with `--ftag` parameter
 - **Isolated Workspace**: All build artifacts and dependencies are kept in `.workspace` directory
@@ -97,54 +103,95 @@ fbin list
 fbin uninstall awesome-tool --yes
 ```
 
+## Core Concepts
+
+### Nodes & Flows
+
+**Nodes** are reusable functional units that encapsulate business logic with explicit input/output schemas. Each Node:
+
+- Has a deterministic, pure function at its core
+- Defines clear I/O contracts (input and output schemas)
+- Can be composed and reused across different Flows
+- Supports automatic dependency detection
+
+**Flows** orchestrate Nodes and sub-Flows to create complex workflows. Flows:
+
+- Connect multiple Nodes with explicit data contracts
+- Enable multi-runtime portability through schema-first design
+- Support complex data transformations and conditional logic
+- Maintain deterministic behavior across different runtimes
+
+### I/O Contracts
+
+Flownet uses schema-first contracts to define clear input and output expectations. This approach:
+
+- Ensures deterministic behavior across different runtimes
+- Enables automatic validation and type checking
+- Facilitates multi-runtime portability
+- Improves code clarity and maintainability
+
 ## Project Types
 
 Flownet supports two main project types:
 
 ### fnode Project
 
-An **fnode project** (Flow Node Project) is a classic/node-style project that focuses on creating reusable components or standalone applications. These projects:
+An **fnode project** (Flow Node Project) is a classic/node-style project that focuses on creating reusable Nodes or standalone applications. These projects:
 
 - Use `fnode.yaml` as their configuration file
 - Typically contain a single code file in the `src` directory
 - Can be built with different runtimes (Node.js, Python, Bun)
 - Support multiple programming languages simultaneously
+- Ideal for creating reusable components with explicit I/O contracts
 
 ### fnet Project
 
-An **fnet project** (Flow Project) is a workflow-oriented project that focuses on orchestrating multiple components. These projects:
+An **fnet project** (Flow Project) is a workflow-oriented project that focuses on orchestrating multiple Nodes and Flows. These projects:
 
 - Use `fnet.yaml` as their configuration file
-- Define workflows that connect multiple components
+- Define workflows that connect multiple Nodes and sub-Flows
 - Support complex data flows and transformations
+- Enable multi-runtime deployment strategies
+- Ideal for building complex business logic orchestrations
 
 ## CLI Tools
 
-Flownet provides four main CLI tools:
+Flownet provides five main CLI tools:
 
-- **`fnode`**: For Node/classic projects (uses `fnode.yaml`)
-- **`fnet`**: For Workflow projects (uses `fnet.yaml`)
+- **`fnode`**: For Node/classic projects (uses `fnode.yaml`) - create and manage reusable Nodes
+- **`fnet`**: For Workflow projects (uses `fnet.yaml`) - create and manage Flows that orchestrate Nodes
 - **`frun`**: Unified interface that works with both project types (auto-detects project file)
 - **`fbin`**: Binary management system for installing, compiling, and managing CLI tools
+- **`fservice`**: Service management for deploying and running Flownet applications
 
-## Multi-Language Support
+## Multi-Language & Multi-Runtime Support
 
-Flownet supports multiple programming languages simultaneously within the same project:
+Flownet supports multiple programming languages and runtimes simultaneously within the same project:
 
 ```text
 my-project/
 ├── src/
-│   ├── index.js          # JavaScript implementation (used by both Node.js and Bun)
+│   ├── index.js          # JavaScript implementation (used by Node.js and Bun)
 │   └── index.py          # Python implementation
 ├── fnode.yaml            # Project configuration file
 └── .workspace/           # Build infrastructure (managed by CLI)
 ```
 
-This allows you to:
+### Supported Runtimes
+
+- **Node.js**: JavaScript/TypeScript execution with full npm ecosystem support
+- **Bun**: Fast JavaScript runtime with improved performance
+- **Deno**: Secure JavaScript/TypeScript runtime with built-in tooling
+- **Python**: Python 3.x for data processing and scientific computing
+
+### Multi-Runtime Portability
+
+Thanks to Flownet's schema-first approach and deterministic core:
 
-- Write your core logic once and migrate it to other languages as needed
-- Choose the best language for each specific use case
-- Use JavaScript with Node.js for quick development, Python for data processing, and JavaScript with Bun for improved performance
+- Write your core logic once and deploy to multiple runtimes
+- Choose the best runtime for each specific use case
+- Migrate between runtimes without changing your business logic
+- Use JavaScript with Node.js for quick development, Python for data processing, and Bun for improved performance
 
 ## Tag-Based Configuration
 

package/template/fnet/core/object.js

@@ -1,6 +1,6 @@
-import getValue from "get-value";
-import setValue from "set-value";
-import print from "./print.js";
+// import getValue from "get-value";
+// import setValue from "set-value";
+import { setProperty, getProperty } from "dot-prop";
 
 export default class Object {
   #property;
@@ -14,14 +14,14 @@ export default class Object {
     this.#context = context;
 
     this.get = (path, options) => {
-      return getValue(this.#property, path, options);
+      return getProperty(this.#property, path, options);
     }
 
     this.set = (path, value, options) => {
-      return setValue(this.#property, path, value, options);
+      return setProperty(this.#property, path, value, options);
     }
 
-    this.print = print;
+    this.print = console.log;
   }
 
   get module() {
@@ -29,19 +29,19 @@ export default class Object {
   }
 
   getModule(path) {
-    return getValue(this.#module, path);
+    return getProperty(this.#module, path);
   }
 
   setModule(path, module) {
     if (typeof module !== "function") throw new Error("Module must be a function");
-    return setValue(this.#module, path, module);
+    return setProperty(this.#module, path, module);
   }
 
   get getValue() {
-    return getValue;
+    return getProperty;
   }
 
   get setValue() {
-    return setValue;
+    return setProperty;
   }
 }

package/template/fnet/node/package.json.njk

@@ -72,14 +72,14 @@
     {% if atom.doc.features.cli.enabled %}
       {% if atom.doc.features.project.format ==='cjs' %}
         ,"cli": "bun {{atom.doc.features.cli.node_options}} {{atom.doc.features.cli.dir}}/index.cjs"
-        {% if atom.doc.features.cli.mcp.enabled===true %}
+        {% if atom.doc.features.cli.mcp.enabled === true %}
           ,"mcp": "bun {{atom.doc.features.cli.node_options}} {{atom.doc.features.cli.dir}}/index.cjs --cli-mode=mcp"
           ,"mcp-inspect": "bunx @modelcontextprotocol/inspector bun {{atom.doc.features.cli.node_options}} {{atom.doc.features.cli.dir}}/index.cjs --cli-mode=mcp"
         {% endif %}
       {% else %}
         ,"cli": "bun {{atom.doc.features.cli.node_options}} {{atom.doc.features.cli.output.file}}"
-        ,"cli:dev": "bun {{atom.doc.features.cli.node_options}} {{atom.doc.features.cli.input.file}}"
-        {% if atom.doc.features.cli.mcp.enabled===true %}
+        ,"cli:dev": "NODE_PRESERVE_SYMLINKS=1 bun {{atom.doc.features.cli.node_options}} {{atom.doc.features.cli.input.file}}"
+        {% if atom.doc.features.cli.mcp.enabled === true %}
           ,"cli:mcp": "bun {{atom.doc.features.cli.node_options}} {{atom.doc.features.cli.output.file}} --cli-mode=mcp"
           ,"cli:mcp:inspect": "bunx @modelcontextprotocol/inspector bun {{atom.doc.features.cli.node_options}} {{atom.doc.features.cli.output.file}} --cli-mode=mcp"
           ,"cli:mcp:dev": "bun {{atom.doc.features.cli.node_options}} {{atom.doc.features.cli.input.file}} --cli-mode=mcp"
@@ -89,6 +89,9 @@
       ,"cli:compile": "fbin compile {{atom.doc.features.cli.output.file}} -o .bin/{{atom.doc['npm::bin'] or atom.doc['name'] or atom['id']}} --yes"
       ,"cli:compile:dev": "fbin compile {{atom.doc.features.cli.input.file}} -o .bin/{{atom.doc['npm::bin'] or atom.doc['name'] or atom['id']}} --yes"    
       ,"cli:install": "fbin install ./.bin/{{atom.doc['npm::bin'] or atom.doc['name'] or atom['id']}} --yes"
+      ,"cli:install:symlink": "fbin install ./.bin/{{atom.doc['npm::bin'] or atom.doc['name'] or atom['id']}} --yes --symlink"
+      ,"cli:uninstall": "fbin uninstall {{atom.doc['npm::bin'] or atom.doc['name'] or atom['id']}} --yes"
+
     {% endif %}
 
     {% if atom.doc.features.app.enabled %}

package/template/fnet/node/src/cli/index.js.njk

@@ -1,319 +1,9 @@
 {% if atom.doc.features.cli.enabled===true %}
 
-{# Define macros for reusable code blocks #}
-{% macro importMcpDependencies() %}
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import express from "express";
-{% endmacro %}
+  {% if atom.doc.features.cli.template.version ==='v1' %}
+    {% include "./index.js.v1.njk" %}
+  {% else %}
+    {% include "./v2/index.js.njk" %}
+  {% endif %}
 
-{% macro mcpModeCodeExtended(runFn) %}
-  if (cliMode === 'mcp') {
-    // MCP mode code
-    const server = new Server({
-      name: "{{atom.doc.features.cli.mcp.name or atom.doc.name}}",
-      version: "{{atom.doc.version or '0.0.1'}}"
-    }, {
-      capabilities: {
-        tools: {}
-      }
-    });
-
-    // Define available tools
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
-      return {
-        tools: [{
-          name: "{{atom.doc.features.cli.mcp.tool.name or atom.doc.name}}",
-          description: "{{atom.doc.features.cli.mcp.tool.description or atom.doc.description}}",
-          inputSchema: inputSchema,
-        }]
-      };
-    });
-
-    // Handle tool execution
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-      if (request.params.name === "{{atom.doc.features.cli.mcp.tool.name or atom.doc.name}}") {
-        try {
-          const result = await {{ runFn }}(request.params.arguments, { Engine });
-          return {
-            content: [{
-              type: "text",
-              text: JSON.stringify(result)
-            }]
-          };
-        } catch (error) {
-          return {
-            content: [{
-              type: "text",
-              text: `Error: ${error.message}`
-            }],
-            isError: true
-          };
-        }
-      }
-      throw new Error("Tool not found");
-    });
-
-    // Get transport type from arguments
-    const transportType = args['mcp-transport'] || args.mcp_transport || 'stdio';
-    let transport;
-
-    if (transportType === 'stdio') {
-      // Use stdio transport
-      transport = new StdioServerTransport();
-    } else if (transportType === 'sse') {
-      // Use SSE transport
-      const app = express();
-      app.use(express.json());
-
-      const port = args['cli-port'] || args.cli_port || 3000;
-      const server = app.listen(port, () => {
-        console.log(`MCP server started with SSE transport on port ${port}`);
-      });
-
-      transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: () => Math.random().toString(36).substring(2, 15),
-      });
-
-      app.post('/sse', async (req, res) => {
-        await transport.handleRequest(req, res, req.body);
-      });
-
-      app.get('/sse', async (req, res) => {
-        await transport.handleRequest(req, res);
-      });
-
-      app.delete('/sse', async (req, res) => {
-        await transport.handleRequest(req, res);
-      });
-    } else {
-      console.error(`Unknown MCP transport type: ${transportType}`);
-      console.error(`Supported types: stdio, sse`);
-      process.exit(1);
-    }
-
-    await server.connect(transport);
-    return;
-  }
-{% endmacro %}
-
-{% macro mcpModeCodeEngine(engineVar) %}
-  if (cliMode === 'mcp') {
-    // MCP mode code
-    const server = new Server({
-      name: "{{atom.doc.features.cli.mcp.name or atom.doc.name}}",
-      version: "{{atom.doc.version or '0.0.1'}}"
-    }, {
-      capabilities: {
-        tools: {}
-      }
-    });
-
-    // Define available tools
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
-      return {
-        tools: [{
-          name: "{{atom.doc.features.cli.mcp.tool.name or atom.doc.name}}",
-          description: "{{atom.doc.features.cli.mcp.tool.description or atom.doc.description}}",
-          inputSchema: inputSchema,
-        }]
-      };
-    });
-
-    // Handle tool execution
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-      if (request.params.name === "{{atom.doc.features.cli.mcp.tool.name or atom.doc.name}}") {
-        try {
-          const result = await {{ engineVar }}.run(request.params.arguments);
-          return {
-            content: [{
-              type: "text",
-              text: JSON.stringify(result)
-            }]
-          };
-        } catch (error) {
-          return {
-            content: [{
-              type: "text",
-              text: `Error: ${error.message}`
-            }],
-            isError: true
-          };
-        }
-      }
-      throw new Error("Tool not found");
-    });
-
-    // Note: Direct access to workflow nodes is not implemented in this version
-    // In a future version, we could expose workflow nodes as separate MCP tools
-
-    // Get transport type from arguments
-    const transportType = args['mcp-transport'] || args.mcp_transport || 'stdio';
-    let transport;
-
-    if (transportType === 'stdio') {
-      // Use stdio transport
-      transport = new StdioServerTransport();
-    } else if (transportType === 'sse') {
-      // Use SSE transport
-      const app = express();
-      app.use(express.json());
-
-      const port = args['cli-port'] || args.cli_port || 3000;
-      const server = app.listen(port, () => {
-        console.log(`MCP server started with SSE transport on port ${port}`);
-      });
-
-      transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: () => Math.random().toString(36).substring(2, 15),
-      });
-
-      app.post('/sse', async (req, res) => {
-        await transport.handleRequest(req, res, req.body);
-      });
-
-      app.get('/sse', async (req, res) => {
-        await transport.handleRequest(req, res);
-      });
-
-      app.delete('/sse', async (req, res) => {
-        await transport.handleRequest(req, res);
-      });
-    } else {
-      console.error(`Unknown MCP transport type: ${transportType}`);
-      console.error(`Supported types: stdio, sse`);
-      process.exit(1);
-    }
-
-    await server.connect(transport);
-    return;
-  }
-{% endmacro %}
-
-{% macro httpModeCodeExpress(runFn, engineParam) %}
-  if (cliMode === 'http') {
-    // HTTP mode code using Express
-    const app = express();
-    app.use(express.json());
-
-    app.post('/{{atom.doc.features.cli.http.path or atom.doc.name}}', async (req, res) => {
-      try {
-        const result = await {{ runFn }}(req.body{{ engineParam }});
-        res.json(result);
-      } catch (error) {
-        res.status(500).json({ error: error.message });
-      }
-    });
-
-    const port = args['cli-port'] || args.cli_port || 3000;
-    app.listen(port, () => {
-      console.log(`HTTP server started on port ${port}`);
-    });
-    return;
-  }
-{% endmacro %}
-
-{% macro defaultModeExtended() %}
-  if (cliMode === 'default') {
-    // Default mode code
-    return await runExtended(await argv(), { Engine });
-  }
-{% endmacro %}
-
-{% macro defaultModeEngine(engineVar) %}
-  if (cliMode === 'default') {
-    // Default mode code
-    const result = await {{ engineVar }}.run(await argv());
-
-    if (typeof result !== 'undefined') {
-      const stdout_format = args['stdout-format'] || args.stdout_format || null;
-
-      if (stdout_format === 'json') console.log(JSON.stringify(result, null, 2));
-      else console.log(result);
-    }
-    return;
-  }
-{% endmacro %}
-
-{% macro runWithCatch() %}
-run()
-  .catch((error) => {
-    console.error(error.message);
-    process.exit(1);
-  });
-{% endmacro %}
-
-{% macro runWithThenCatch() %}
-run()
-  .then(() => {
-    {# process.exit(0); #}
-  })
-  .catch((error) => {
-    console.error(error.message);
-    process.exit(1);
-  });
-{% endmacro %}
-
-{# Main template starts here #}
-import argv from '../default/input.args.js';
-import { schema as inputSchema } from '../default/validate_input.js';
-import { default as Engine } from '../default/{{atom.doc.features.cli_default_entry_file or atom.doc.features.main_default_entry_file}}';
-
-{% if atom.doc.features.cli.mcp.enabled===true %}
-{{ importMcpDependencies() }}
-{% elif atom.doc.features.cli.http.enabled===true %}
-// Using express for HTTP mode
-import express from 'express';
-{% endif %}
-
-{% if atom.doc.features.cli.extend===true %}
-  {# TYPE 1 #}
-  import { default as runExtended } from '../../../cli/index.js';
-  import argsParser from 'yargs-parser';
-
-  const run = async () => {
-    const args = argsParser(process.argv.slice(2));
-    const cliMode = args['cli-mode'] || args.cli_mode || 'default';
-
-    {{ defaultModeExtended() }}
-
-    {% if atom.doc.features.cli.mcp.enabled===true %}
-    {{ mcpModeCodeExtended('runExtended') }}
-    {% endif %}
-
-    {% if atom.doc.features.cli.http.enabled===true %}
-    {{ httpModeCodeExpress('runExtended', ', { Engine }') }}
-    {% endif %}
-
-    console.error(`Unknown CLI mode: ${cliMode}`);
-    process.exit(1);
-  };
-
-  {{ runWithThenCatch() }}
-{% else %}
-  {# TYPE 2 #}
-  import argsParser from 'yargs-parser';
-  const run = async () => {
-    const args =argsParser(process.argv.slice(2));
-    const cliMode = args['cli-mode'] || args.cli_mode || 'default';
-    const engine = new Engine();
-
-    {{ defaultModeEngine('engine') }}
-
-    {% if atom.doc.features.cli.mcp.enabled===true %}
-    {{ mcpModeCodeEngine('engine') }}
-    {% endif %}
-
-    {% if atom.doc.features.cli.http.enabled===true %}
-    {{ httpModeCodeExpress('engine.run', '') }}
-    {% endif %}
-
-    console.error(`Unknown CLI mode: ${cliMode}`);
-    process.exit(1);
-  };
-
-  {{ runWithCatch() }}
 {% endif %}
-{% endif %}