@fnet/cli 0.133.0 → 0.133.1

package/template/fnode/node/src/cli/v2/index.js.njk

@@ -0,0 +1,184 @@
+{# ============================================================================
+   CLI TEMPLATE V2 - MODULAR ARCHITECTURE
+   ============================================================================
+
+   This template uses a modular, registry-based approach for maximum
+   extensibility. New modes, transports, and output formats can be added
+   without modifying the core template structure.
+
+   Architecture:
+   - core/       : Base imports, argument parsing, error handling
+   - modes/      : CLI execution modes (default, mcp, http, pipeline, etc.)
+   - output/     : Output formatters (json, yaml, table, etc.)
+
+   Each mode is self-contained and can be enabled/disabled via feature flags.
+
+   Supports:
+   - ESM and CJS formats
+   - Standard and Extend modes
+   - Multiple CLI modes (default, mcp, http)
+
+   ============================================================================ #}
+
+{% if atom.doc.features.cli.enabled===true %}
+
+{# --------------------------------------------------------------------------
+   CORE IMPORTS
+   -------------------------------------------------------------------------- #}
+{% include "./core/imports.njk" %}
+
+{# --------------------------------------------------------------------------
+   SHARED IMPORTS
+   --------------------------------------------------------------------------
+   Shared dependencies used by multiple modes
+   Prevents duplicate imports when multiple modes are enabled
+   -------------------------------------------------------------------------- #}
+{% if atom.doc.features.cli.http.enabled===true or atom.doc.features.cli.webhook.enabled===true %}
+// Shared: http module (used by HTTP and Webhook modes)
+{% if atom.doc.features.project.format==='esm' %}
+import http from 'http';
+{% elif atom.doc.features.project.format==='cjs' %}
+const http = require('http');
+{% endif %}
+{% endif %}
+
+{% if atom.doc.features.cli.mcp.enabled === true or atom.doc.features.cli.webhook.enabled===true %}
+// Shared: crypto module (used by MCP and Webhook modes)
+{% if atom.doc.features.project.format==='esm' %}
+import crypto from 'crypto';
+{% elif atom.doc.features.project.format==='cjs' %}
+const crypto = require('crypto');
+{% endif %}
+{% endif %}
+
+{# --------------------------------------------------------------------------
+   MODE-SPECIFIC IMPORTS
+   --------------------------------------------------------------------------
+   Import dependencies for ALL enabled CLI modes
+   Multiple modes can be enabled simultaneously
+   -------------------------------------------------------------------------- #}
+{% if atom.doc.features.cli.mcp.enabled === true %}
+{% include "./modes/mcp/imports.njk" %}
+{% endif %}
+
+{% if atom.doc.features.cli.http.enabled===true %}
+{% include "./modes/http/imports.njk" %}
+{% endif %}
+
+{% if atom.doc.features.cli.pipeline.enabled===true %}
+{% include "./modes/pipeline/imports.njk" %}
+{% endif %}
+
+{% if atom.doc.features.cli.websocket.enabled===true %}
+{% include "./modes/websocket/imports.njk" %}
+{% endif %}
+
+{% if atom.doc.features.cli.webhook.enabled===true %}
+{% include "./modes/webhook/imports.njk" %}
+{% endif %}
+
+{# --------------------------------------------------------------------------
+   ARGUMENT PARSER
+   -------------------------------------------------------------------------- #}
+{% include "./core/args-parser.njk" %}
+
+{# --------------------------------------------------------------------------
+   MAIN RUN FUNCTION
+   --------------------------------------------------------------------------
+   Mode registry: Each mode is self-contained and handles its own logic
+   -------------------------------------------------------------------------- #}
+const run = async () => {
+  const args = parseArgs();
+  const cliMode = args['cli-mode'] || args.cli_mode || 'default';
+
+  {# --------------------------------------------------------------------------
+     DEFAULT MODE
+     --------------------------------------------------------------------------
+     Standard or extended mode based on CLI configuration
+     -------------------------------------------------------------------------- #}
+  {% if atom.doc.features.cli.extend===true %}
+  {% include "./modes/default/extend.njk" %}
+  {% else %}
+  {% include "./modes/default/standard.njk" %}
+  {% endif %}
+
+  {# --------------------------------------------------------------------------
+     MCP MODE
+     --------------------------------------------------------------------------
+     Model Context Protocol server with multiple transport options
+     -------------------------------------------------------------------------- #}
+  {% if atom.doc.features.cli.mcp.enabled === true %}
+  {% include "./modes/mcp/index.njk" %}
+  {% endif %}
+
+  {# --------------------------------------------------------------------------
+     HTTP MODE
+     --------------------------------------------------------------------------
+     REST API server using built-in http module
+     -------------------------------------------------------------------------- #}
+  {% if atom.doc.features.cli.http.enabled===true %}
+  {% include "./modes/http/index.njk" %}
+  {% endif %}
+
+  {# --------------------------------------------------------------------------
+     PIPELINE MODE
+     --------------------------------------------------------------------------
+     Unix pipeline integration via stdin/stdout
+     -------------------------------------------------------------------------- #}
+  {% if atom.doc.features.cli.pipeline.enabled===true %}
+  {% include "./modes/pipeline/index.njk" %}
+  {% endif %}
+
+  {# --------------------------------------------------------------------------
+     WEBSOCKET MODE
+     --------------------------------------------------------------------------
+     Real-time bidirectional communication
+     -------------------------------------------------------------------------- #}
+  {% if atom.doc.features.cli.websocket.enabled===true %}
+  {% include "./modes/websocket/index.njk" %}
+  {% endif %}
+
+  {# --------------------------------------------------------------------------
+     WEBHOOK MODE
+     --------------------------------------------------------------------------
+     Event-driven HTTP with HMAC signature verification
+     -------------------------------------------------------------------------- #}
+  {% if atom.doc.features.cli.webhook.enabled===true %}
+  {% include "./modes/webhook/index.njk" %}
+  {% endif %}
+
+  {# --------------------------------------------------------------------------
+     FUTURE MODES
+     --------------------------------------------------------------------------
+     Add new modes here by simply including their index.njk
+
+     Examples:
+     - gRPC mode for high-performance RPC
+     - GraphQL mode for flexible APIs
+     - SSE mode for server-sent events
+     -------------------------------------------------------------------------- #}
+
+  {# {% if atom.doc.features.cli.webhook.enabled===true %}
+  {% include "./modes/webhook/index.njk" %}
+  {% endif %} #}
+
+  {# {% if atom.doc.features.cli.grpc.enabled===true %}
+  {% include "./modes/grpc/index.njk" %}
+  {% endif %} #}
+
+  {# --------------------------------------------------------------------------
+     UNKNOWN MODE HANDLER
+     -------------------------------------------------------------------------- #}
+  console.error(`Unknown CLI mode: ${cliMode}`);
+  console.error(`Available modes: default{% if atom.doc.features.cli.mcp.enabled === true %}, mcp{% endif %}{% if atom.doc.features.cli.http.enabled===true %}, http{% endif %}{% if atom.doc.features.cli.pipeline.enabled===true %}, pipeline{% endif %}{% if atom.doc.features.cli.websocket.enabled===true %}, websocket{% endif %}{% if atom.doc.features.cli.webhook.enabled===true %}, webhook{% endif %}`);
+  process.exit(1);
+};
+
+{# --------------------------------------------------------------------------
+   ERROR HANDLER & RUN
+   -------------------------------------------------------------------------- #}
+{% include "./core/run-wrapper.njk" %}
+
+{% endif %}
+{# End of cli.enabled check #}
+

package/template/fnode/node/src/cli/v2/modes/default/extend.njk

@@ -0,0 +1,11 @@
+{# ============================================================================
+   DEFAULT MODE - EXTEND
+   ============================================================================
+   Extended CLI mode that returns result directly (for CLI wrapper usage)
+   ============================================================================ #}
+
+if (cliMode === 'default') {
+  // Default mode code
+  return await Node(await argv());
+}
+

package/template/fnode/node/src/cli/v2/modes/default/standard.njk

@@ -0,0 +1,19 @@
+{# ============================================================================
+   DEFAULT MODE - STANDARD
+   ============================================================================
+   Standard CLI mode that executes the Node function and prints result
+   ============================================================================ #}
+
+if (cliMode === 'default') {
+  // Default mode code
+  const result = await Node(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;
+}
+

package/template/fnode/node/src/cli/v2/modes/http/builtin.njk

@@ -0,0 +1,61 @@
+{# ============================================================================
+   HTTP MODE - BUILT-IN (Native Node.js HTTP)
+   ============================================================================
+   Simple REST API server using Node.js built-in http module
+   No external dependencies required
+   ============================================================================ #}
+
+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');
+
+  // 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' }));
+    return;
+  }
+
+  // Check path
+  const path = '/{{atom.doc.features.cli.http.path or atom.doc.name}}';
+  if (req.url !== path) {
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Not found' }));
+    return;
+  }
+
+  // Parse request body
+  let body = '';
+  req.on('data', chunk => {
+    body += chunk.toString();
+  });
+
+  req.on('end', async () => {
+    try {
+      const data = JSON.parse(body);
+      const result = await Node(data);
+      
+      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 }));
+    }
+  });
+});
+
+const port = args['cli-port'] || args.cli_port || 3000;
+server.listen(port, () => {
+  console.log(`HTTP server started on port ${port} (native http)`);
+});
+return;
+

package/template/fnode/node/src/cli/v2/modes/http/imports.njk

@@ -0,0 +1,9 @@
+{# ============================================================================
+   HTTP MODE - IMPORTS
+   ============================================================================
+   No mode-specific imports needed
+   http module is imported in shared imports section
+   ============================================================================ #}
+
+{# http module imported in shared section #}
+

package/template/fnode/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/fnode/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/fnode/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/fnode/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/fnode/node/src/cli/v2/modes/mcp/tool-handlers.njk

@@ -0,0 +1,41 @@
+{# ============================================================================
+   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 {
+      const result = await Node(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");
+});
+

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

@@ -0,0 +1,212 @@
+{# ============================================================================
+   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 Node function directly with the request body
+    const result = await Node(req.body);
+
+    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 Node function
+      const result = await Node(data);
+
+      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/fnode/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/fnode/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 #}
+