@fnet/cli 0.133.0 → 1.0.0

package/template/fnet/node/src/cli/v2/modes/http/index.njk

@@ -0,0 +1,12 @@
+{# ============================================================================
+   HTTP MODE - MAIN
+   ============================================================================
+   HTTP REST API mode using Node.js built-in http module
+   Zero dependencies, simple and fast
+   ============================================================================ #}
+
+if (cliMode === 'http') {
+  // HTTP mode code
+  {% include "./builtin.njk" %}
+}
+

package/template/fnet/node/src/cli/v2/modes/mcp/imports.njk

@@ -0,0 +1,33 @@
+{# ============================================================================
+   MCP MODE - IMPORTS
+   ============================================================================
+   MCP SDK dependencies for Model Context Protocol support
+   Supports both ESM and CJS formats
+   ============================================================================ #}
+
+{% if atom.doc.features.project.format==='esm' %}
+{# ESM Format #}
+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";
+{% if atom.doc.features.cli.mcp.ws===true %}
+import expressWs from "express-ws";
+{% endif %}
+{# crypto imported in shared section #}
+
+{% elif atom.doc.features.project.format==='cjs' %}
+{# CJS Format #}
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const { ListToolsRequestSchema, CallToolRequestSchema } = require("@modelcontextprotocol/sdk/types.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { StreamableHTTPServerTransport } = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const express = require("express");
+{% if atom.doc.features.cli.mcp.ws===true %}
+const expressWs = require("express-ws");
+{% endif %}
+{# crypto imported in shared section #}
+
+{% endif %}
+

package/template/fnet/node/src/cli/v2/modes/mcp/index.njk

@@ -0,0 +1,30 @@
+{# ============================================================================
+   MCP MODE - MAIN
+   ============================================================================
+   Model Context Protocol mode orchestrator
+   Supports multiple transports: STDIO, HTTP (future: WebSocket, SSE, gRPC)
+   ============================================================================ #}
+
+if (cliMode === 'mcp') {
+  // MCP mode code
+  {% include "./server-setup.njk" %}
+  {% include "./tool-handlers.njk" %}
+
+  // Get transport type from arguments
+  const transportType = args['mcp-transport'] || args.mcp_transport || 'stdio';
+  let transport;
+
+  if (transportType === 'stdio') {
+    {% include "./transport-stdio.njk" %}
+  } else if (transportType === 'http') {
+    {% include "./transport-http.njk" %}
+  } else {
+    console.error(`Unknown MCP transport type: ${transportType}`);
+    console.error(`Supported types: stdio, http`);
+    process.exit(1);
+  }
+
+  await server.connect(transport);
+  return;
+}
+

package/template/fnet/node/src/cli/v2/modes/mcp/server-setup.njk

@@ -0,0 +1,15 @@
+{# ============================================================================
+   MCP MODE - SERVER SETUP
+   ============================================================================
+   Initialize MCP server with capabilities
+   ============================================================================ #}
+
+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: {}
+  }
+});
+

package/template/fnet/node/src/cli/v2/modes/mcp/tool-handlers.njk

@@ -0,0 +1,46 @@
+{# ============================================================================
+   MCP MODE - TOOL HANDLERS
+   ============================================================================
+   Register MCP tool handlers for listing and executing 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 {
+      {% if atom.doc.features.cli.extend===true %}
+      const result = await runExtended(request.params.arguments, { Engine });
+      {% else %}
+      const engine = new Engine();
+      const result = await engine.run(request.params.arguments);
+      {% endif %}
+      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");
+});
+

package/template/fnet/node/src/cli/v2/modes/mcp/transport-http.njk

@@ -0,0 +1,222 @@
+{# ============================================================================
+   MCP MODE - HTTP TRANSPORT
+   ============================================================================
+   Streamable HTTP transport for MCP protocol with session management
+   Official transport as of MCP 2025-03-26
+   ============================================================================ #}
+
+// Use Streamable HTTP transport (official transport as of MCP 2025-03-26)
+const app = express();
+{% if atom.doc.features.cli.mcp.ws===true %}
+// Enable WebSocket support
+expressWs(app);
+{% endif %}
+app.use(express.json());
+
+const port = args['cli-port'] || args.cli_port || 3000;
+const host = args['cli-host'] || args.cli_host || '0.0.0.0';
+const basePath = '{{atom.doc.features.cli.mcp.path or 'mcp'}}';
+const mcpEndpoint = `/${basePath}`;           // MCP protocol endpoint
+const verbose = args['cli-verbose'] || args.cli_verbose || false;
+
+// Optional endpoints (enabled via config)
+const httpEnabled = {{atom.doc.features.cli.mcp.http or false}};
+const wsEnabled = {{atom.doc.features.cli.mcp.ws or false}};
+const httpEndpoint = `/${basePath}/input`;    // HTTP input endpoint
+const wsEndpoint = `/${basePath}/ws`;         // WebSocket endpoint
+
+// Verbose logging helper
+const log = (...args) => {
+  if (verbose) {
+    console.log('[MCP]', new Date().toISOString(), ...args);
+  }
+};
+
+// Map to store transports by session ID
+const transports = {};
+
+// Handle POST requests for client-to-server communication
+app.post(mcpEndpoint, async (req, res) => {
+  // Check for existing session ID
+  const sessionId = req.get('Mcp-Session-Id');
+
+  log('POST request received');
+  log('Session ID:', sessionId || 'none');
+  log('Request body:', JSON.stringify(req.body, null, 2));
+
+  let transport;
+
+  if (sessionId && transports[sessionId]) {
+    // Reuse existing transport
+    log('Reusing existing transport for session:', sessionId);
+    transport = transports[sessionId];
+  } else if (!sessionId && req.body && (req.body.method === 'initialize' ||
+            (Array.isArray(req.body) && req.body.some(item => item.method === 'initialize')))) {
+    // New initialization request
+    log('Creating new transport for initialization');
+    transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => {
+        // Generate cryptographically secure session ID
+        return crypto.randomBytes(16).toString('hex');
+      },
+      onsessioninitialized: (sessionId) => {
+        // Store the transport by session ID
+        log('Session initialized:', sessionId);
+        transports[sessionId] = transport;
+      }
+    });
+
+    // Clean up transport when closed
+    transport.onclose = () => {
+      if (transport.sessionId) {
+        log('Transport closed, cleaning up session:', transport.sessionId);
+        delete transports[transport.sessionId];
+      }
+    };
+
+    // Connect to the MCP server
+    await server.connect(transport);
+    log('Server connected to transport');
+  } else {
+    // Invalid request
+    log('Invalid request - no valid session ID');
+    return res.status(400).json({
+      jsonrpc: '2.0',
+      error: {
+        code: -32000,
+        message: 'Bad Request: No valid session ID provided'
+      },
+      id: null
+    });
+  }
+
+  // Handle the request
+  log('Handling request with transport');
+  await transport.handleRequest(req, res, req.body);
+});
+
+// Reusable handler for GET and DELETE requests
+const handleSessionRequest = async (req, res) => {
+  const sessionId = req.get('Mcp-Session-Id');
+  log(`${req.method} request received for session:`, sessionId || 'none');
+
+  if (!sessionId || !transports[sessionId]) {
+    log('Invalid or missing session ID');
+    return res.status(400).send('Invalid or missing session ID');
+  }
+
+  const transport = transports[sessionId];
+  log('Handling request with existing transport');
+  await transport.handleRequest(req, res);
+};
+
+// Handle GET requests for server-to-client notifications via SSE
+app.get(mcpEndpoint, handleSessionRequest);
+
+// Handle DELETE requests for session termination
+app.delete(mcpEndpoint, handleSessionRequest);
+
+{% if atom.doc.features.cli.mcp.http===true %}
+// HTTP input endpoint (enabled via config: cli.mcp.http: true)
+app.post(httpEndpoint, async (req, res) => {
+  log('HTTP input request received');
+  log('Request body:', JSON.stringify(req.body, null, 2));
+
+  try {
+    // Call the Engine with the request body
+    {% if atom.doc.features.cli.extend===true %}
+    const result = await runExtended(req.body, { Engine });
+    {% else %}
+    const engine = new Engine();
+    const result = await engine.run(req.body);
+    {% endif %}
+
+    log('HTTP input processed successfully');
+    log('Result:', JSON.stringify(result, null, 2));
+
+    // Return the result as JSON
+    res.json(result);
+  } catch (error) {
+    log('HTTP input processing error:', error.message);
+
+    // Return error response
+    res.status(500).json({
+      error: error.message,
+      stack: verbose ? error.stack : undefined
+    });
+  }
+});
+{% endif %}
+
+{% if atom.doc.features.cli.mcp.ws===true %}
+// WebSocket endpoint (enabled via config: cli.mcp.ws: true)
+// Map to store WebSocket clients
+const wsClients = new Set();
+
+app.ws(wsEndpoint, (ws, req) => {
+  log('WebSocket connection established');
+  wsClients.add(ws);
+
+  // Handle incoming messages
+  ws.on('message', async (message) => {
+    log('WebSocket message received:', message);
+
+    try {
+      // Parse JSON message
+      const data = JSON.parse(message);
+
+      // Call the Engine
+      {% if atom.doc.features.cli.extend===true %}
+      const result = await runExtended(data, { Engine });
+      {% else %}
+      const engine = new Engine();
+      const result = await engine.run(data);
+      {% endif %}
+
+      log('WebSocket message processed successfully');
+      log('Result:', JSON.stringify(result, null, 2));
+
+      // Send result back to client
+      ws.send(JSON.stringify(result));
+    } catch (error) {
+      log('WebSocket message processing error:', error.message);
+
+      // Send error response
+      ws.send(JSON.stringify({
+        error: error.message,
+        stack: verbose ? error.stack : undefined
+      }));
+    }
+  });
+
+  // Handle connection close
+  ws.on('close', () => {
+    log('WebSocket connection closed');
+    wsClients.delete(ws);
+  });
+
+  // Handle errors
+  ws.on('error', (error) => {
+    log('WebSocket error:', error.message);
+    wsClients.delete(ws);
+  });
+});
+{% endif %}
+
+app.listen(port, host, () => {
+  console.log(`MCP server started with Streamable HTTP transport`);
+  console.log(`MCP endpoint: http://${host}:${port}${mcpEndpoint}`);
+  {% if atom.doc.features.cli.mcp.http===true %}
+  console.log(`HTTP endpoint: http://${host}:${port}${httpEndpoint}`);
+  {% endif %}
+  {% if atom.doc.features.cli.mcp.ws===true %}
+  console.log(`WebSocket endpoint: ws://${host}:${port}${wsEndpoint}`);
+  {% endif %}
+  console.log(`Listening on ${host}:${port}`);
+  if (verbose) {
+    console.log(`Verbose logging enabled`);
+  }
+});
+
+return;
+

package/template/fnet/node/src/cli/v2/modes/mcp/transport-stdio.njk

@@ -0,0 +1,9 @@
+{# ============================================================================
+   MCP MODE - STDIO TRANSPORT
+   ============================================================================
+   Standard input/output transport for MCP protocol
+   ============================================================================ #}
+
+// Use stdio transport
+transport = new StdioServerTransport();
+

package/template/fnet/node/src/cli/v2/modes/pipeline/imports.njk

@@ -0,0 +1,9 @@
+{# ============================================================================
+   PIPELINE MODE - IMPORTS
+   ============================================================================
+   No external dependencies needed - uses native Node.js streams
+   stdin/stdout are available globally
+   ============================================================================ #}
+
+{# No imports needed for pipeline mode - stdin/stdout are native #}
+

package/template/fnet/node/src/cli/v2/modes/pipeline/index.njk

@@ -0,0 +1,113 @@
+{# ============================================================================
+   PIPELINE MODE - MAIN
+   ============================================================================
+   Unix pipeline integration via stdin/stdout
+   Supports line-by-line processing and full input mode
+   ============================================================================ #}
+
+if (cliMode === 'pipeline') {
+  // Pipeline mode code
+  const pipelineMode = args['pipeline-mode'] || args.pipeline_mode || 'lines';
+  const pipelineFormat = args['pipeline-format'] || args.pipeline_format || 'json';
+  
+  if (pipelineMode === 'lines') {
+    // Line-by-line processing (default)
+{% if atom.doc.features.project.format==='esm' %}
+    const readline = await import('readline');
+{% elif atom.doc.features.project.format==='cjs' %}
+    const readline = require('readline');
+{% endif %}
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false
+    });
+
+    rl.on('line', async (line) => {
+      try {
+        // Parse input based on format
+        let input;
+        if (pipelineFormat === 'json') {
+          input = JSON.parse(line);
+        } else {
+          input = { data: line };
+        }
+
+        // Validate input
+        // TODO: Add schema validation if needed
+
+        // Process with Engine
+        {% if atom.doc.features.cli.extend===true %}
+        const result = await runExtended(input, { Engine });
+        {% else %}
+        const engine = new Engine();
+        const result = await engine.run(input);
+        {% endif %}
+
+        // Output result
+        if (pipelineFormat === 'json') {
+          console.log(JSON.stringify(result));
+        } else {
+          console.log(result);
+        }
+      } catch (error) {
+        console.error(`Error processing line: ${error.message}`);
+      }
+    });
+
+    rl.on('close', () => {
+      process.exit(0);
+    });
+
+  } else if (pipelineMode === 'full') {
+    // Full input processing
+    let inputData = '';
+
+    process.stdin.on('data', (chunk) => {
+      inputData += chunk;
+    });
+
+    process.stdin.on('end', async () => {
+      try {
+        // Parse input based on format
+        let input;
+        if (pipelineFormat === 'json') {
+          input = JSON.parse(inputData);
+        } else {
+          input = { data: inputData };
+        }
+
+        // Validate input
+        // TODO: Add schema validation if needed
+
+        // Process with Engine
+        {% if atom.doc.features.cli.extend===true %}
+        const result = await runExtended(input, { Engine });
+        {% else %}
+        const engine = new Engine();
+        const result = await engine.run(input);
+        {% endif %}
+
+        // Output result
+        if (pipelineFormat === 'json') {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(result);
+        }
+
+        process.exit(0);
+      } catch (error) {
+        console.error(`Error processing input: ${error.message}`);
+        process.exit(1);
+      }
+    });
+
+  } else {
+    console.error(`Unknown pipeline mode: ${pipelineMode}`);
+    console.error(`Supported modes: lines, full`);
+    process.exit(1);
+  }
+
+  return;
+}
+

package/template/fnet/node/src/cli/v2/modes/webhook/imports.njk

@@ -0,0 +1,9 @@
+{# ============================================================================
+   WEBHOOK MODE - IMPORTS
+   ============================================================================
+   No mode-specific imports needed
+   http and crypto modules are imported in shared imports section
+   ============================================================================ #}
+
+{# http and crypto modules imported in shared section #}
+

package/template/fnet/node/src/cli/v2/modes/webhook/index.njk

@@ -0,0 +1,127 @@
+{# ============================================================================
+   WEBHOOK MODE - IMPLEMENTATION
+   ============================================================================
+   Event-driven HTTP webhook server with HMAC signature verification
+   ============================================================================ #}
+
+if (cliMode === 'webhook') {
+  const port = args['cli-port'] || args.cli_port || 3000;
+  const webhookPath = args['webhook-path'] || args.webhook_path || '/webhook';
+  const webhookSecret = args['webhook-secret'] || args.webhook_secret || process.env.WEBHOOK_SECRET;
+  const signatureHeader = args['webhook-signature-header'] || args.webhook_signature_header || 'x-hub-signature-256';
+  
+  const server = http.createServer(async (req, res) => {
+    // CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, ' + signatureHeader);
+    
+    // Handle OPTIONS preflight
+    if (req.method === 'OPTIONS') {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+    
+    // Only accept POST requests
+    if (req.method !== 'POST') {
+      res.writeHead(405, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Method not allowed. Use POST.' }));
+      return;
+    }
+    
+    // Only accept webhook path
+    if (req.url !== webhookPath) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Not found. Use ' + webhookPath }));
+      return;
+    }
+    
+    // Read request body
+    let body = '';
+    req.on('data', chunk => {
+      body += chunk.toString();
+    });
+    
+    req.on('end', async () => {
+      try {
+        // Verify signature if secret is provided
+        if (webhookSecret) {
+          const signature = req.headers[signatureHeader.toLowerCase()];
+          
+          if (!signature) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing signature header: ' + signatureHeader }));
+            return;
+          }
+          
+          // Calculate expected signature (HMAC-SHA256)
+          const hmac = crypto.createHmac('sha256', webhookSecret);
+          hmac.update(body);
+          const expectedSignature = 'sha256=' + hmac.digest('hex');
+          
+          // Compare signatures (timing-safe)
+          const signatureBuffer = Buffer.from(signature);
+          const expectedBuffer = Buffer.from(expectedSignature);
+          
+          if (signatureBuffer.length !== expectedBuffer.length || 
+              !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid signature' }));
+            return;
+          }
+        }
+        
+        // Parse JSON payload
+        let payload;
+        try {
+          payload = JSON.parse(body);
+        } catch (e) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Invalid JSON payload' }));
+          return;
+        }
+        
+        // Process webhook with Engine
+        {% if atom.doc.features.cli.extend===true %}
+        const result = await runExtended(payload, { Engine });
+        {% else %}
+        const engine = new Engine();
+        const result = await engine.run(payload);
+        {% endif %}
+
+        // Send response
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+        
+      } catch (error) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ 
+          error: error.message,
+          type: 'processing_error'
+        }));
+      }
+    });
+    
+    req.on('error', (error) => {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        error: error.message,
+        type: 'request_error'
+      }));
+    });
+  });
+  
+  server.listen(port, () => {
+    console.log(`Webhook server started on port ${port}`);
+    console.log(`Webhook endpoint: ${webhookPath}`);
+    if (webhookSecret) {
+      console.log(`Signature verification: enabled (header: ${signatureHeader})`);
+    } else {
+      console.log(`Signature verification: disabled (no secret provided)`);
+    }
+  });
+  
+  return;
+}
+

package/template/fnet/node/src/cli/v2/modes/websocket/imports.njk

@@ -0,0 +1,15 @@
+{# ============================================================================
+   WEBSOCKET MODE - IMPORTS
+   ============================================================================
+   WebSocket server dependencies using 'ws' library
+   Supports both ESM and CJS formats
+   ============================================================================ #}
+
+{% if atom.doc.features.project.format==='esm' %}
+// Using ws library for WebSocket mode
+import { WebSocketServer } from 'ws';
+{% elif atom.doc.features.project.format==='cjs' %}
+// Using ws library for WebSocket mode
+const { WebSocketServer } = require('ws');
+{% endif %}
+